Struct Raster 

pub struct Raster {
    pub cols: usize,
    pub rows: usize,
    pub bands: usize,
    pub x_min: f64,
    pub y_min: f64,
    pub cell_size_x: f64,
    pub cell_size_y: f64,
    pub nodata: f64,
    pub data_type: DataType,
    pub crs: CrsInfo,
    pub metadata: Vec<(String, String)>,
    pub data: RasterData,
}

A raster grid with one or more bands.

Data is stored in a typed contiguous buffer matching data_type. Conversion to f64 happens only through accessor helpers when needed.

Layout: band-major, then row-major top-down within each band (index = band * rows * cols + row * cols + col).

Fields

cols: usize

Number of columns.

rows: usize

Number of rows.

bands: usize

Number of bands.

x_min: f64

West edge X coordinate.

y_min: f64

South edge Y coordinate.

cell_size_x: f64

Cell width in map units (always positive).

cell_size_y: f64

Cell height in map units (always positive, stored as absolute value).

nodata: f64

No-data value.

data_type: DataType

On-disk data type (used for writing).

crs: CrsInfo

Spatial reference.

metadata: Vec<(String, String)>

Free-form key/value metadata.

data: RasterData

Raw data buffer, band-major then row-major top-down. Length = bands * cols * rows.

Implementations

impl Raster

pub fn new(cfg: RasterConfig) -> Self

Create a new raster from a RasterConfig, filling all cells with nodata.

pub fn from_data(cfg: RasterConfig, data: Vec<f64>) -> Result<Self>

Create a raster from a raw f64 data buffer.

Errors

Returns RasterError::InvalidDimensions if data.len() != cols * rows * bands.

pub fn from_data_native(cfg: RasterConfig, data: RasterData) -> Result<Self>

Create a raster from a typed data buffer.

Errors

Returns RasterError::InvalidDimensions if data.len() != cols * rows * bands. Returns RasterError::Other if cfg.data_type != data.data_type().

pub fn new_like(template: &Raster) -> Self

Create a new raster that reuses spatial metadata and layout from template.

Cell values are initialized to the template’s nodata value.

pub fn new_like_uninit(template: &Raster) -> Self

Like [new_like] but skips initializing the data buffer.

Use this when every cell will be written before any read (e.g. immediately followed by par_fill_with). Avoids a redundant full-buffer nodata write.

pub fn data_u8(&self) -> Option<&[u8]>

Typed fast-path access to u8 storage.

pub fn data_u8_mut(&mut self) -> Option<&mut [u8]>

Typed fast-path mutable access to u8 storage.

pub fn data_i8(&self) -> Option<&[i8]>

Typed fast-path access to i8 storage.

pub fn data_i8_mut(&mut self) -> Option<&mut [i8]>

Typed fast-path mutable access to i8 storage.

pub fn data_u16(&self) -> Option<&[u16]>

Typed fast-path access to u16 storage.

pub fn data_u16_mut(&mut self) -> Option<&mut [u16]>

Typed fast-path mutable access to u16 storage.

pub fn data_i16(&self) -> Option<&[i16]>

Typed fast-path access to i16 storage.

pub fn data_i16_mut(&mut self) -> Option<&mut [i16]>

Typed fast-path mutable access to i16 storage.

pub fn data_u32(&self) -> Option<&[u32]>

Typed fast-path access to u32 storage.

pub fn data_u32_mut(&mut self) -> Option<&mut [u32]>

Typed fast-path mutable access to u32 storage.

pub fn data_i32(&self) -> Option<&[i32]>

Typed fast-path access to i32 storage.

pub fn data_i32_mut(&mut self) -> Option<&mut [i32]>

Typed fast-path mutable access to i32 storage.

pub fn data_u64(&self) -> Option<&[u64]>

Typed fast-path access to u64 storage.

pub fn data_u64_mut(&mut self) -> Option<&mut [u64]>

Typed fast-path mutable access to u64 storage.

pub fn data_i64(&self) -> Option<&[i64]>

Typed fast-path access to i64 storage.

pub fn data_i64_mut(&mut self) -> Option<&mut [i64]>

Typed fast-path mutable access to i64 storage.

pub fn data_f32(&self) -> Option<&[f32]>

Typed fast-path access to f32 storage.

pub fn data_f32_mut(&mut self) -> Option<&mut [f32]>

Typed fast-path mutable access to f32 storage.

pub fn data_f64(&self) -> Option<&[f64]>

Typed fast-path access to f64 storage.

pub fn data_f64_mut(&mut self) -> Option<&mut [f64]>

Typed fast-path mutable access to f64 storage.

pub fn band_view(&self, band: usize) -> BandView

Materialize one band (zero-based) as a BandView.

This is the canonical input path for tool kernels that need per-cell read access without explicit bounds checks or type dispatch at every call site. Call once at tool entry, wrap in Arc, share across worker threads, and call view.get(row, col) in the hot loop.

For F64 rasters the internal buffer is a direct subslice clone (one allocation). For all other storage types each cell is converted once.

pub fn band_as_f64_slice(&self, band: usize) -> Option<&[f64]>

Returns a direct reference to the raw f64 storage for a single band (zero-based) when the raster’s native storage type is F64, otherwise returns None.

The slice has length rows * cols and is indexed as row * cols + col.

Use this as a zero-copy fast path before spawning worker threads on F64 rasters (e.g. DEMs). For non-F64 rasters, call [band_to_vec_f64] instead to get a converted, owned buffer with the same indexing convention.

pub fn band_to_vec_f64(&self, band: usize) -> Vec<f64>

Materializes one band (zero-based) as a flat, row-major Vec<f64>.

For F64 rasters this clones the band’s subslice directly (one allocation, no per-cell conversion). For all other storage types each cell is converted from the native type in a single pass.

The returned buffer has length rows * cols and is indexed as row * cols + col. Out-of-bounds values are the caller’s responsibility; respect raster.rows and raster.cols.

Use this once before spawning worker threads so that hot kernels can index a plain Vec directly rather than going through the generic [get] accessor on every cell access.

let buf = raster.band_to_vec_f64(0);
let z = buf[row * cols + col];  // no per-cell dispatch overhead

pub fn par_fill_with<F>(&mut self, f: F)

where F: Fn(usize) -> f64 + Send + Sync,

Fill all cells in-place using a parallel closure f(index) -> f64.

The index is the flat band-major, row-major cell index. For typed storage other than F64, the returned f64 is down-cast to the native stored type before writing.

pub fn apply_unary_math<F>( &mut self, f: F, target_bands: Option<Vec<usize>>, ) -> Result<()>

where F: Fn(f64) -> f64 + Send + Sync,

Apply a unary math operation to selected bands (or all bands if target_bands is None).

Operates in-place on self. For floating-point rasters (F32/F64), uses direct typed slice access + SIMD-friendly iteration. For integer rasters, falls back to per-band copy-loop.

If target_bands is None, operates on the entire flat buffer with fast F32/F64 paths. If target_bands is Some(vec), operates only on those band indices via per-band slicing.

Errors

Returns an error if a band index is out of bounds (only when target_bands is Some).

pub fn apply_unary_math_from<F>(&mut self, f: F, src: &Raster) -> Result<()>

where F: Fn(f64) -> f64 + Send + Sync,

Apply a unary math operation reading from src and writing to self.

Copies each cell value from src, applies the operation, and stores in self. Uses direct typed slice access (F32/F64) for performance.

Errors

Returns an error if rasters have different dimensions.

pub fn apply_binary_math_from<F>( &mut self, f: F, src1: &Raster, src2: &Raster, ) -> Result<()>

where F: Fn(f64, f64) -> f64 + Send + Sync,

Apply a binary math operation from two source rasters, writing results into self.

self must be a freshly-allocated output (e.g. from Raster::new_like). The closure f(z1, z2) -> f64 is called only for cell pairs where neither source is nodata. When either source is nodata the output cell is set to self.nodata.

Fast paths: when self, src1, and src2 are all F32 or all F64 the typed slices are zipped in parallel without any enum dispatch per cell.

Errors

Returns an error if the raster dimensions do not all match.

pub fn apply_scalar_add(&mut self, src: &Raster, scalar: f64) -> Result<()>

Add a scalar constant to every non-nodata cell, reading from src, writing to self.

Equivalent to apply_unary_math_from(|z| z + scalar, src) but expresses intent clearly and is the canonical kernel shared by the increment tool.

Errors

Returns an error if raster dimensions do not match.

pub fn apply_scalar_sub(&mut self, src: &Raster, scalar: f64) -> Result<()>

Subtract a scalar constant from every non-nodata cell, reading from src, writing to self.

Equivalent to apply_unary_math_from(|z| z - scalar, src) but expresses intent clearly and is the canonical kernel shared by the decrement tool.

Errors

Returns an error if raster dimensions do not match.

pub fn index(&self, band: isize, row: isize, col: isize) -> Option<usize>

Return the flat buffer index for signed band, row, and column coordinates. Returns None when coordinates are outside the raster bounds.

pub fn get(&self, band: isize, row: isize, col: isize) -> f64

Get the value at signed pixel coordinates (band, row, col).

Returns the raster’s numeric nodata sentinel when coordinates are out-of-bounds or the stored value is nodata.

pub fn get_opt(&self, band: isize, row: isize, col: isize) -> Option<f64>

Get the value at signed pixel coordinates (band, row, col) as Option<f64>.

Returns None if coordinates are out-of-bounds or the value is nodata.

pub fn get_raw(&self, band: isize, row: isize, col: isize) -> Option<f64>

Get the raw value (including nodata) at signed pixel coordinates (band, row, col). Returns None only on out-of-bounds.

pub fn set( &mut self, band: isize, row: isize, col: isize, value: f64, ) -> Result<()>

Set the value at signed pixel coordinates (band, row, col).

Errors

Returns RasterError::OutOfBounds if coordinates are outside the grid.

pub fn set_unchecked(&mut self, band: isize, row: isize, col: isize, value: f64)

Set a value at signed pixel coordinates, panicking on out-of-bounds. Convenience alias.

pub fn is_nodata(&self, v: f64) -> bool

Returns true if v equals this raster’s nodata sentinel.

pub fn y_max(&self) -> f64

Northern extent (Y max) — top of the grid.

pub fn x_max(&self) -> f64

Eastern extent (X max) — right edge of the grid.

pub fn extent(&self) -> Extent

The geographic extent of the raster.

pub fn col_center_x(&self, col: isize) -> f64

Cell-center X coordinate for signed column index col.

pub fn row_center_y(&self, row: isize) -> f64

Cell-center Y coordinate for signed row index row (row 0 = north).

pub fn world_to_pixel(&self, x: f64, y: f64) -> Option<(isize, isize)>

Convert geographic coordinates (x, y) to signed pixel indices (col, row). Returns None if the point lies outside the raster extent.

pub fn assign_crs_epsg(&mut self, epsg: u32)

Assign a CRS to this raster using an EPSG code.

Replaces the entire crs struct with a new CrsInfo containing only the EPSG code. Any existing wkt or proj4 fields are cleared to ensure CRS consistency.

pub fn assign_crs_wkt(&mut self, wkt: &str)

Assign a CRS to this raster using WKT text.

Replaces the entire crs struct with a new CrsInfo containing only the WKT definition. Any existing epsg or proj4 fields are cleared to ensure CRS consistency.

pub fn reproject_to_epsg( &self, dst_epsg: u32, resample: ResampleMethod, ) -> Result<Raster>

Reproject this raster to another EPSG CRS.

This MVP implementation uses an auto-derived output extent from transformed sampled source-boundary points (corners + edge densification) and supports nearest, bilinear, cubic, and Lanczos sampling.

For explicit output grid controls (cols, rows, extent), use Raster::reproject_with_options.

Errors

Returns an error when source/destination EPSG codes are unsupported, source CRS metadata (EPSG/WKT/PROJ) is missing or invalid, or transformed extents are invalid.

pub fn reproject_with_options( &self, options: &ReprojectOptions, ) -> Result<Raster>

Reproject this raster using detailed output-grid options.

pub fn reproject_with_options_and_progress<F>( &self, options: &ReprojectOptions, progress: F, ) -> Result<Raster>

where F: Fn(f64) + Send + Sync,

Reproject this raster using detailed output-grid options and emit progress updates in the range [0, 1] as destination rows are completed.

pub fn reproject_with_crs( &self, src_crs: &Crs, dst_crs: &Crs, options: &ReprojectOptions, ) -> Result<Raster>

Reproject this raster using caller-supplied source/destination CRS objects.

This advanced path bypasses source CRS metadata parsing, enabling workflows where CRS definitions are managed externally.

Note: options.dst_epsg is still used for output CrsInfo metadata and EPSG-specific extent behavior (e.g., antimeridian handling for EPSG:4326).

pub fn reproject_with_crs_and_progress<F>( &self, src_crs: &Crs, dst_crs: &Crs, options: &ReprojectOptions, progress: F, ) -> Result<Raster>

where F: Fn(f64) + Send + Sync,

Reproject this raster with caller-supplied CRS objects and emit progress updates in the range [0, 1] as destination rows are completed.

pub fn reproject_to_epsg_nearest(&self, dst_epsg: u32) -> Result<Raster>

Convenience helper for nearest-neighbor reprojection.

pub fn reproject_to_epsg_bilinear(&self, dst_epsg: u32) -> Result<Raster>

Convenience helper for bilinear reprojection.

pub fn reproject_to_epsg_cubic(&self, dst_epsg: u32) -> Result<Raster>

Convenience helper for cubic reprojection.

pub fn reproject_to_epsg_lanczos(&self, dst_epsg: u32) -> Result<Raster>

Reproject to destination EPSG using Lanczos interpolation.

pub fn reproject_to_epsg_average(&self, dst_epsg: u32) -> Result<Raster>

Reproject to destination EPSG using 3x3 mean resampling.

pub fn reproject_to_epsg_min(&self, dst_epsg: u32) -> Result<Raster>

Reproject to destination EPSG using 3x3 minimum resampling.

pub fn reproject_to_epsg_max(&self, dst_epsg: u32) -> Result<Raster>

Reproject to destination EPSG using 3x3 maximum resampling.

pub fn reproject_to_epsg_mode(&self, dst_epsg: u32) -> Result<Raster>

Reproject to destination EPSG using 3x3 modal resampling.

pub fn reproject_to_epsg_median(&self, dst_epsg: u32) -> Result<Raster>

Reproject to destination EPSG using 3x3 median resampling.

pub fn reproject_to_epsg_stddev(&self, dst_epsg: u32) -> Result<Raster>

Reproject to destination EPSG using 3x3 standard-deviation resampling.

pub fn reproject_to_match_grid( &self, target_grid: &Raster, resample: ResampleMethod, ) -> Result<Raster>

Reproject this raster to match another raster’s grid (CRS, extent, rows, cols).

The target_grid provides destination EPSG, output extent, and output dimensions. This is useful when aligning products from multiple sources onto a shared reference grid.

Errors

Returns an error if target_grid.crs.epsg is missing or unsupported.

pub fn reproject_to_match_grid_and_progress<F>( &self, target_grid: &Raster, resample: ResampleMethod, progress: F, ) -> Result<Raster>

where F: Fn(f64) + Send + Sync,

Reproject this raster to match another raster’s grid while emitting progress updates in the range [0, 1] as destination rows are completed.

pub fn reproject_to_match_resolution( &self, reference_grid: &Raster, resample: ResampleMethod, ) -> Result<Raster>

Reproject this raster using another raster’s CRS, resolution, and snap origin.

Unlike Raster::reproject_to_match_grid, this keeps the destination extent auto-derived from the transformed source footprint, while aligning that extent to the reference grid’s origin and pixel size.

Errors

Returns an error if reference_grid.crs.epsg is missing or unsupported.

pub fn reproject_to_match_resolution_and_progress<F>( &self, reference_grid: &Raster, resample: ResampleMethod, progress: F, ) -> Result<Raster>

where F: Fn(f64) + Send + Sync,

Reproject this raster while matching a reference raster’s resolution and snap origin, emitting progress updates in [0, 1].

pub fn reproject_to_match_resolution_in_epsg( &self, dst_epsg: u32, reference_grid: &Raster, resample: ResampleMethod, ) -> Result<Raster>

Reproject this raster to an explicit destination EPSG while matching a reference raster’s resolution and snap origin.

If reference_grid is in a different CRS than dst_epsg, the reference snap origin and per-axis cell sizes are transformed to destination CRS using local axis steps at the reference origin.

Errors

Returns an error if reference/destination EPSG values are missing or unsupported, or if transformed reference resolution is invalid.

pub fn reproject_to_match_resolution_in_epsg_and_progress<F>( &self, dst_epsg: u32, reference_grid: &Raster, resample: ResampleMethod, progress: F, ) -> Result<Raster>

where F: Fn(f64) + Send + Sync,

Reproject this raster to an explicit destination EPSG while matching a reference raster’s transformed resolution/snap, emitting progress in [0, 1].

pub fn sample_world( &self, band: isize, x: f64, y: f64, method: ResampleMethod, nodata_policy: NodataPolicy, ) -> Option<f64>

Sample a raster value at world coordinates using the selected resampling method.

pub fn statistics(&self) -> Statistics

Compute basic statistics over all valid (non-nodata) cells.

pub fn statistics_with_mode( &self, mode: StatisticsComputationMode, ) -> Statistics

Compute basic statistics over all valid (non-nodata) cells using a selected computation path.

pub fn statistics_band(&self, band: isize) -> Result<Statistics>

Compute basic statistics over all valid (non-nodata) cells in one band.

pub fn statistics_band_with_mode( &self, band: isize, mode: StatisticsComputationMode, ) -> Result<Statistics>

Compute basic statistics over one band using a selected computation path.

pub fn band_slice(&self, band: isize) -> Vec<f64>

Return a copy of one full band as row-major values.

pub fn set_band_slice(&mut self, band: isize, values: &[f64]) -> Result<()>

Set one full band from row-major values.

pub fn row_slice(&self, band: isize, row: isize) -> Vec<f64>

Return a slice of the raw data for signed (band, row).

pub fn set_row_slice( &mut self, band: isize, row: isize, values: &[f64], ) -> Result<()>

Set all values in signed (band, row) from an f64 slice.

pub fn iter_valid( &self, ) -> impl Iterator<Item = (isize, isize, isize, f64)> + '_

Iterate over signed (band, row, col, value) for all valid cells.

pub fn iter_valid_band( &self, band: isize, ) -> Result<Box<dyn Iterator<Item = (isize, isize, f64)> + '_>>

Iterate over signed (row, col, value) for all valid cells in one band.

pub fn iter_band_rows( &self, band: isize, ) -> Result<Box<dyn Iterator<Item = Vec<f64>> + '_>>

Iterate over row vectors (Vec<f64>) for one band from north to south.

pub fn for_each_band_row_mut<F>(&mut self, band: isize, f: F) -> Result<()>

where F: FnMut(isize, RasterRowMut<'_>),

Traverse mutable native row slices for one band from north to south.

This is a zero-allocation fast path for in-place row-wise processing. The callback receives (row_index, typed_row_slice).

pub fn for_each_band_row<F>(&self, band: isize, f: F) -> Result<()>

where F: FnMut(isize, RasterRowRef<'_>),

Traverse immutable native row slices for one band from north to south.

This is a zero-allocation fast path for read-only row-wise processing. The callback receives (row_index, typed_row_slice).

pub fn fill(&mut self, value: f64)

Fill all cells with value.

pub fn fill_nodata(&mut self)

Fill all cells with the nodata value.

pub fn map_valid<F: Fn(f64) -> f64>(&mut self, f: F)

Apply a function to every valid (non-nodata) cell value in-place.

pub fn map_valid_band<F: Fn(f64) -> f64>( &mut self, band: isize, f: F, ) -> Result<()>

Apply a function to every valid (non-nodata) cell value in one band in-place.

pub fn replace(&mut self, from: f64, to: f64)

Replace all occurrences of from with to in the data buffer.

pub fn replace_band(&mut self, band: isize, from: f64, to: f64) -> Result<()>

Replace all occurrences of from with to in one band.

pub fn read<P: AsRef<Path>>(path: P) -> Result<Self>

Read a raster from path, detecting the format automatically.

pub fn read_with_format<P: AsRef<Path>>( path: P, fmt: RasterFormat, ) -> Result<Self>

Read a raster from path using the specified format.

pub fn write<P: AsRef<Path>>(&self, path: P, fmt: RasterFormat) -> Result<()>

Write this raster to path, detecting the format from the extension.

pub fn write_auto<P: AsRef<Path>>(&self, path: P) -> Result<()>

Write this raster, auto-detecting the format from the file extension.

pub fn write_geotiff_with_options<P: AsRef<Path>>( &self, path: P, opts: &GeoTiffWriteOptions, ) -> Result<()>

Write this raster as GeoTIFF/BigTIFF/COG using typed options.

pub fn write_cog<P: AsRef<Path>>(&self, path: P) -> Result<()>

Write this raster as a Cloud-Optimized GeoTIFF (COG) using convenience defaults.

Defaults:

• compression: Deflate
• BigTIFF: false
• COG tile size: 512

pub fn write_cog_with_tile_size<P: AsRef<Path>>( &self, path: P, tile_size: u32, ) -> Result<()>

Write this raster as a Cloud-Optimized GeoTIFF (COG) using convenience defaults and a custom tile size.

Defaults:

• compression: Deflate
• BigTIFF: false
• COG tile size: tile_size

pub fn write_cog_with_options<P: AsRef<Path>>( &self, path: P, opts: &CogWriteOptions, ) -> Result<()>

Write this raster as a Cloud-Optimized GeoTIFF (COG) using COG-focused typed options.

Any option set to None uses convenience defaults:

• compression: Deflate
• BigTIFF: false
• COG tile size: 512

pub fn write_jpeg2000_with_options<P: AsRef<Path>>( &self, path: P, opts: &Jpeg2000WriteOptions, ) -> Result<()>

Write this raster as JPEG2000/GeoJP2 using typed options.

Trait Implementations

impl Clone for Raster

fn clone(&self) -> Raster

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Raster

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Raster

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.