Module element 

Typed raster elements and allocation-free bulk conversions.

This module is the answer to “how do I read a band straight into my own Vec<f64> / ndarray::Array2<f64> without an extra full-size allocation?”.

• RasterElement associates a Rust primitive with its RasterDataType and defines exact conversion semantics.
• convert_raw_into converts raw driver bytes into a caller-supplied &mut [T] in a single pass, with no intermediate buffer.
• convert_raw_bytes is the byte-to-byte variant used by RasterBuffer::convert_to.

Conversion semantics

source → destination	behaviour
same type	memcpy, bit-for-bit
integer → integer	saturating, exact (bridged through i128, never through f64)
integer → float	as cast, round-to-nearest-even (IEEE 754 default)
float → float	as cast, round-to-nearest-even
float → integer	saturating, FloatToIntRounding::Nearest (half away from zero) by default

Special float inputs converting to an integer destination:

input	result
NaN	0
+∞ / value above T::MAX	T::MAX
-∞ / value below T::MIN	T::MIN

Nothing ever wraps, traps or produces undefined behaviour.

Precision

Integer → integer conversions go through i128, so u64/i64 values beyond 2⁵³ survive exactly — unlike the historical get_pixel/set_pixel path, which bridged everything through f64.

Conversions whose destination is a float are still bounded by the destination’s mantissa: a u64/i64 magnitude above 2⁵³ cannot be represented exactly in f64 (above 2²⁴ for f32) and is rounded to the nearest representable value. This is inherent to the destination type, not an artefact of the conversion.

Complex data types

RasterDataType::CFloat32 and RasterDataType::CFloat64 have no RasterElement impl (they are not scalars). They are still accepted by convert_raw_into and convert_raw_bytes as source types, where the real component is used — matching RasterBuffer::get_pixel. As a destination (only reachable through convert_raw_bytes) the real component is written and the imaginary component is zeroed.

Examples

use oxigeo_core::buffer::convert_raw_into;
use oxigeo_core::types::RasterDataType;

// Raw bytes exactly as a driver hands them over (native-endian UInt16).
let raw: Vec<u8> = [1u16, 2, 3, 60_000]
    .iter()
    .flat_map(|v| v.to_ne_bytes())
    .collect();

// Destination owned by the caller — one allocation, and it is *yours*.
let mut pixels = vec![0.0f64; 4];
convert_raw_into(&raw, RasterDataType::UInt16, &mut pixels)?;

assert_eq!(pixels, vec![1.0, 2.0, 3.0, 60_000.0]);

Enums

FloatToIntRounding

Rounding applied when a floating-point sample is stored into an integer type.

RasterElementKind

Broad category of a RasterElement, used to pick an exact conversion path.

Traits

RasterElement

A Rust primitive that can appear as a raster sample.

Functions

convert_raw_bytes

Converts raw raster bytes of src_type into raw bytes of dst_type, in a single pass and without allocating.

convert_raw_into

Converts raw raster bytes of src_type into dst in a single pass, without allocating.

convert_raw_into_with

convert_raw_into with an explicit float→integer rounding mode.

elements_as_bytes

Reinterprets typed samples as their native-endian bytes.