Skip to main content

Crate oxigeo_geotiff

Crate oxigeo_geotiff 

Source
Expand description

OxiGeo GeoTIFF Driver - Pure Rust GeoTIFF/COG Support

This crate provides a pure Rust implementation of GeoTIFF and Cloud Optimized GeoTIFF (COG) reading and writing capabilities.

§Features

  • std (default) - Enable standard library support
  • async - Enable async I/O support
  • deflate (default) - DEFLATE/zlib compression
  • lzw (default) - LZW compression
  • zstd - ZSTD compression
  • jpeg - JPEG compression (planned)
  • webp - WebP compression (pure Rust via image-webp; encoder is lossless VP8L only)
  • parallel - Decode a band/window’s tiles across rayon workers (off by default: this crate targets wasm32-unknown-unknown, which has no threads)

§Example

ⓘ
use oxigeo_geotiff::cog::CogReader;
use oxigeo_core::io::FileDataSource;

let source = FileDataSource::open("image.tif")?;
let reader = CogReader::open(source)?;

println!("Image size: {}x{}", reader.width(), reader.height());
println!("Tile size: {:?}", reader.tile_size());
println!("Overview count: {}", reader.overview_count());

// Read a tile
let tile_data = reader.read_tile(0, 0, 0)?;

§Byte order of decoded samples

Every entry point that yields decoded pixel samples returns them in the host’s byte order, whatever the file’s II/MM header says. This is the contract GDAL’s RasterIO has always had, and it is what the rest of the workspace assumes: oxigeo_core::buffer::RasterBuffer carries no byte-order field and all of its accessors (get_pixel, get_u16…get_f64, as_slice) and oxigeo_core::buffer::convert_raw_into are native-endian. Before cool-japan/oxigeo#14 the driver handed back samples in the file’s order, so every numeric value read from a big-endian (MM) GeoTIFF anywhere in the workspace was silently byte-reversed.

§Which APIs normalise

Normalising (samples come back native-endian):

Not normalising, by design:

  • CogReader::read_tile_raw — returns the block’s compressed bytes exactly as stored; there are no samples to normalise.
  • compression and compression::apply_predictor_reverse — the predictor is defined on file-order samples (TIFF 6.0 §14 / TN3) and therefore runs before normalisation. Callers driving the codec layer by hand own the conversion.
  • The writer module, which takes native-order samples and emits them in the byte order its options declare.

§Scope and limits

Normalisation swaps samples of 2, 4 and 8 bytes. Sub-byte BitsPerSample (which the reader reports as bytes_per_sample == 0), 1-byte samples and any other width (e.g. a 24-bit BitsPerSample, which rounds to 3) are passed through untouched — for widths under two bytes there is nothing to swap, and for exotic widths there is no defined sample order to swap to. Lerc blocks are also passed through: this crate’s LERC decoder emits native-order samples already (lerc_codec::serialize_native), so swapping them would corrupt data rather than fix it.

§Codec/predictor combinations that are refused

A Lerc block carrying a Predictor tag is rejected outright rather than decoded (see reject_undefined_predictor): no encoder defines that combination — libtiff’s LERC codec ignores tag 317 entirely and GDAL refuses PREDICTOR for LERC — so a decoder cannot know whether a predictor was ever applied. Reversing one anyway, which is what the driver used to do, corrupts every sample of the block with no error raised.

A file whose byte order already matches the host — every real-world little-endian GeoTIFF on every target this crate supports — pays a single predictable branch per decoded block and no per-sample work at all.

Re-exports§

pub use cog::CogReader;
pub use geokeys::GeoKey;
pub use geokeys::GeoKeyDirectory;
pub use geokeys::ModelType;
pub use geokeys::RasterType;
pub use tiff::ByteOrderType;
pub use tiff::Compression;
pub use tiff::ImageInfo;
pub use tiff::PhotometricInterpretation;
pub use tiff::TiffFile;
pub use tiff::TiffHeader;
pub use tiff::TiffTag;
pub use writer::CogWriter;
pub use writer::CogWriterOptions;
pub use writer::GeoTiffWriter;
pub use writer::GeoTiffWriterOptions;
pub use writer::OverviewResampling;
pub use writer::WriterConfig;

Modules§

adaptive_tiling
Adaptive tile size selection for Cloud Optimized GeoTIFF (COG).
band_algebra
Raster Band Algebra and Spectral Indices
band_read
Single-band read engine: whole-band and windowed reads that decode straight into a caller-owned buffer.
cog
Cloud Optimized GeoTIFF (COG) support
color_space
Color space transformation support for GeoTIFF.
compression
Compression and decompression for TIFF data
geokeys
GeoTIFF GeoKey parsing
jpeg_codec
JPEG-in-TIFF decompression codec for TIFF compression types 6 and 7.
lerc_codec
LERC (Limited Error Raster Compression) codec for GeoTIFF
overviews
GeoTIFF overview (pyramid) generation and reading.
tiff
TIFF/BigTIFF file format parsing
writer
GeoTIFF and COG writing functionality

Structs§

GeoTiffReader
GeoTIFF reader (high-level API)

Functions§

is_cog
Checks if a TIFF appears to be a COG
is_tiff
Checks if data looks like a TIFF file