oxigdal-vrt

Pure Rust VRT (Virtual Raster) driver for OxiGDAL - create mosaics, transformations, and virtual datasets without copying data.

Overview

VRT (Virtual Raster) is an XML-based format that references other raster files without copying data. This driver provides a pure Rust implementation enabling efficient multi-file processing and on-the-fly transformations.

Features

Pure Rust - 100% Pure Rust implementation, no GDAL dependency
Mosaicking - Combine multiple tiles into a single virtual dataset
Band Subsetting - Extract specific bands from multi-band rasters
On-the-fly Transformations - Apply scaling, offset, and pixel functions
Windowing - Create virtual subsets of large rasters
XML-based - Human-readable XML format for easy editing
Zero-copy - References source files without data duplication
Async I/O - Optional async support for non-blocking operations
No unwrap policy - All operations return Result<T, E>

Installation

Add to your Cargo.toml:

[dependencies]
oxigdal-vrt = "0.1.0"

Feature Flags

std (default) - Enable standard library support
async - Enable async I/O with Tokio

Example with async support:

[dependencies]
oxigdal-vrt = { version = "0.1.0", features = ["async"] }

Quick Start

Creating a VRT Mosaic

use oxigdal_vrt::VrtBuilder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a 2x2 tile mosaic
    let vrt = VrtBuilder::new()
        .add_tile("/data/tile1.tif", 0, 0, 512, 512)?
        .add_tile("/data/tile2.tif", 512, 0, 512, 512)?
        .add_tile("/data/tile3.tif", 0, 512, 512, 512)?
        .add_tile("/data/tile4.tif", 512, 512, 512, 512)?
        .build_file("mosaic.vrt")?;

    println!("Created VRT: {}x{}", vrt.raster_x_size, vrt.raster_y_size);
    Ok(())
}

Reading from a VRT

use oxigdal_vrt::VrtReader;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = VrtReader::open("mosaic.vrt")?;

    println!("VRT dimensions: {}x{}", reader.width(), reader.height());
    println!("Bands: {}", reader.band_count());

    // Read a window
    let window = reader.read_window(0, 0, 256, 256, 1)?;

    Ok(())
}

Usage

Band Subsetting

Extract specific bands from multi-band rasters:

use oxigdal_vrt::VrtBuilder;

// Create RGB VRT from 4-band RGBA
let vrt = VrtBuilder::new()
    .add_source("input.tif")?
    .select_bands(&[1, 2, 3])? // Red, Green, Blue only
    .build_file("rgb_only.vrt")?;

On-the-fly Scaling

Apply scale and offset transformations:

use oxigdal_vrt::{VrtBuilder, PixelFunction};

let vrt = VrtBuilder::new()
    .add_source("temperature_kelvin.tif")?
    .set_scale_offset(1.0, -273.15)? // Convert Kelvin to Celsius
    .build_file("temperature_celsius.vrt")?;

Pixel Functions

Apply custom pixel functions:

use oxigdal_vrt::{VrtBuilder, PixelFunction};

// Calculate NDVI from red and NIR bands
let vrt = VrtBuilder::new()
    .add_source("multispectral.tif")?
    .set_pixel_function(PixelFunction::Ndvi {
        red_band: 3,
        nir_band: 4,
    })?
    .build_file("ndvi.vrt")?;

Virtual Warping

Create reprojected virtual datasets:

use oxigdal_vrt::VrtBuilder;

let vrt = VrtBuilder::new()
    .add_source("utm_zone_10.tif")?
    .set_srs("EPSG:4326")? // Reproject to WGS84
    .build_file("wgs84.vrt")?;

Complex Mosaics

Build mosaics with overlapping tiles:

use oxigdal_vrt::{VrtBuilder, ResampleAlg};

let vrt = VrtBuilder::new()
    .add_tile_with_options(
        "tile1.tif",
        0, 0, 1024, 1024,
        ResampleAlg::Bilinear,
    )?
    .add_tile_with_options(
        "tile2.tif",
        512, 0, 1024, 1024, // Overlaps with tile1
        ResampleAlg::Bilinear,
    )?
    .set_blend_mode(BlendMode::Average)?
    .build_file("blended_mosaic.vrt")?;

API Overview

Module	Description
`builder`	VRT creation with builder pattern
`reader`	Reading VRT datasets
`dataset`	VRT dataset representation
`band`	Virtual band configuration
`source`	Source raster references
`mosaic`	Mosaic creation utilities
`xml`	XML parsing and generation
`error`	Error types

Key Types

VrtBuilder - Builder for creating VRT datasets
VrtReader - Read and query VRT files
VrtDataset - In-memory VRT representation
VrtBand - Virtual band configuration
VrtSource - Reference to source raster
PixelFunction - Built-in pixel transformation functions
ResampleAlg - Resampling algorithms (Nearest, Bilinear, Cubic, etc.)

Supported Pixel Functions

The VRT driver supports various built-in pixel functions:

Function	Description	Example Use Case
`Ndvi`	Normalized Difference Vegetation Index	Vegetation analysis
`Ndwi`	Normalized Difference Water Index	Water body detection
`Hillshade`	Terrain hillshade	Elevation visualization
`Slope`	Terrain slope	Gradient analysis
`Aspect`	Terrain aspect	Direction analysis
`Sum`	Sum of bands	Band arithmetic
`Diff`	Difference of bands	Change detection
`Mul`	Multiply bands	Masking operations
`Div`	Divide bands	Ratio indices

Resampling Algorithms

Nearest - Nearest neighbor (fastest)
Bilinear - Bilinear interpolation
Cubic - Cubic convolution
CubicSpline - Cubic spline
Lanczos - Lanczos windowed sinc (best quality)
Average - Average of all contributing pixels
Mode - Most common value
Max - Maximum value
Min - Minimum value

VRT XML Format

VRT files are XML documents with the following structure:

<VRTDataset rasterXSize="1024" rasterYSize="1024">
  <SRS>EPSG:4326</SRS>
  <GeoTransform>-180.0, 0.35, 0.0, 90.0, 0.0, -0.35</GeoTransform>

  <VRTRasterBand dataType="Float32" band="1">
    <ColorInterp>Gray</ColorInterp>
    <NoDataValue>-9999</NoDataValue>

    <SimpleSource>
      <SourceFilename relativeToVRT="1">tile1.tif</SourceFilename>
      <SourceBand>1</SourceBand>
      <SrcRect xOff="0" yOff="0" xSize="512" ySize="512"/>
      <DstRect xOff="0" yOff="0" xSize="512" ySize="512"/>
    </SimpleSource>
  </VRTRasterBand>
</VRTDataset>

Performance

VRT datasets provide zero-copy access to source rasters:

Operation	Performance	Notes
VRT Creation	<1ms	XML generation only
VRT Parsing	1-10ms	Depends on complexity
Pixel Access	Same as source	No overhead for simple VRTs
Mosaic Access	Linear with sources	Cached for repeated access

Optimization Tips

Use relative paths - Enables portability
Enable caching - For repeated window reads
Align windows to tiles - Minimizes source file access
Use overviews - For multi-resolution access

Error Handling

The VRT driver follows the "no unwrap" policy. All operations return Result<T, VrtError>:

use oxigdal_vrt::{VrtReader, VrtError};

match VrtReader::open("data.vrt") {
    Ok(reader) => {
        println!("Opened VRT: {}x{}", reader.width(), reader.height());
    }
    Err(VrtError::FileNotFound { path }) => {
        eprintln!("VRT file not found: {}", path);
    }
    Err(VrtError::InvalidXml { message }) => {
        eprintln!("Invalid VRT XML: {}", message);
    }
    Err(e) => {
        eprintln!("VRT error: {}", e);
    }
}

Pure Rust

This library is 100% Pure Rust with no GDAL or C dependencies. All VRT parsing, generation, and processing is implemented in Rust.

Benefits:

Cross-platform - Works on any platform Rust supports
WebAssembly - Compiles to WASM
Embedded - Suitable for embedded systems
Memory-safe - Guaranteed memory safety

Examples

See the tests/ directory for comprehensive examples:

create_vrt_mosaic.rs - Creating tile mosaics
vrt_band_subset.rs - Band extraction
vrt_pixel_functions.rs - Pixel transformations
vrt_virtual_warp.rs - Reprojection

Run examples:

cargo test --package oxigdal-vrt --test create_vrt_mosaic -- --nocapture

OxiGDAL Integration

VRT integrates seamlessly with other OxiGDAL drivers:

use oxigdal_core::DataSource;
use oxigdal_vrt::VrtReader;
use oxigdal_geotiff::GeoTiffWriter;

// Read from VRT, write to GeoTIFF
let vrt = VrtReader::open("mosaic.vrt")?;
let data = vrt.read_all()?;

let writer = GeoTiffWriter::create("output.tif")?;
writer.write_band(&data, 1)?;
writer.close()?;

Testing

Run the test suite:

# All tests
cargo test --package oxigdal-vrt

# With async support
cargo test --package oxigdal-vrt --features async

Documentation

API Documentation: docs.rs/oxigdal-vrt
GDAL VRT Format: GDAL VRT Specification
Main Project: github.com/cool-japan/oxigdal

Contributing

Contributions are welcome! Please ensure:

All tests pass
No unwrap() in production code
Comprehensive error handling
Documentation for public APIs
Follow Rust naming conventions

Related Projects

OxiGDAL Ecosystem:

oxigdal-core - Core types and traits
oxigdal-geotiff - GeoTIFF driver
oxigdal-cloud - Cloud storage backends

COOLJAPAN Ecosystem:

SciRS2 - Scientific computing
OxiBLAS - Pure Rust BLAS
Oxicode - Serialization

License

Licensed under the Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0).

Authors

COOLJAPAN OU (Team Kitasan)

Part of the COOLJAPAN ecosystem - Building the future of geospatial computing in Pure Rust.

oxigdal-vrt 0.1.0