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 supportasync- Enable async I/O supportdeflate(default) - DEFLATE/zlib compressionlzw(default) - LZW compressionzstd- ZSTD compressionjpeg- JPEG compression (planned)webp- WebP compression (pure Rust viaimage-webp; encoder is lossless VP8L only)parallel- Decode a band/window’s tiles across rayon workers (off by default: this crate targetswasm32-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):
GeoTiffReader::read_band,GeoTiffReader::read_band_into,GeoTiffReader::read_band_into_typedGeoTiffReader::read_window,GeoTiffReader::read_window_into,GeoTiffReader::read_window_into_typedGeoTiffReader::read_tile,GeoTiffReader::read_tile_buffer,GeoTiffReader::read_tile_band_bufferCogReader::read_tile,CogReader::read_tile_into
Not normalising, by design:
CogReader::read_tile_raw— returns the block’s compressed bytes exactly as stored; there are no samples to normalise.compressionandcompression::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
writermodule, 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§
- GeoTiff
Reader - GeoTIFF reader (high-level API)