lerc 0.2.1

Safe and idiomatic Rust wrapper for Esri's LERC compression library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

use lerc_sys::ffi;

use crate::{BlobInfo, LercError, datatype::LercDataType, get_blob_info};

/// Decodes a LERC-compressed byte buffer into typed raster values.
///
/// # Parameters
/// - `blob`: Compressed LERC byte buffer.
/// - `width`, `height`: Dimensions of the raster image.
/// - `depth`: Number of values per pixel.
/// - `n_bands`: Number of spectral or channel bands.
/// - `n_masks`: Number of masks (usually 1).
///
/// # Returns
/// A tuple `(Vec<T>, Option<Vec<u8>>)` with the decoded data and an optional pixel validity mask.
///
/// # Errors
/// Returns `LercError` if decoding fails.
pub fn decode<T: LercDataType>(
    blob: &[u8],
    width: usize,
    height: usize,
    depth: usize,
    n_bands: usize,
    n_masks: usize,
) -> Result<(Vec<T>, Option<Vec<u8>>), LercError> {
    let total_values = width * height * depth * n_bands;

    let mut valid_mask: Option<Vec<u8>> = None;

    let p_valid_bytes = if n_masks > 0 {
        let mut mask = vec![0u8; width * height * n_masks];

        let ptr = mask.as_mut_ptr();

        valid_mask = Some(mask);

        ptr
    } else {
        std::ptr::null_mut()
    };

    let mut data = vec![T::default(); total_values];

    let status = unsafe {
        ffi::lerc_decode(
            blob.as_ptr(),
            blob.len() as u32,
            n_masks as i32,
            p_valid_bytes,
            depth as i32,
            width as i32,
            height as i32,
            n_bands as i32,
            T::LERC_TYPE,
            data.as_mut_ptr().cast(),
        )
    };

    if status != 0 {
        return Err(LercError::from_status(status));
    }

    Ok((data, valid_mask))
}

/// Decodes a LERC blob using the provided [`BlobInfo`] metadata.
///
/// This is a convenience wrapper over [`decode`] that extracts all
/// necessary dimensions and layout parameters from a `BlobInfo` instance.
///
/// # Parameters
/// - `blob`: The LERC-compressed input byte slice.
/// - `info`: Metadata describing the compressed layout.
///
/// # Returns
/// A tuple of decoded data and optional validity mask.
pub fn decode_with_info<T: LercDataType>(
    blob: &[u8],
    info: &BlobInfo,
) -> Result<(Vec<T>, Option<Vec<u8>>), LercError> {
    decode::<T>(
        blob,
        info.width as usize,
        info.height as usize,
        info.depth as usize,
        info.bands as usize,
        info.masks as usize,
    )
}

/// Decodes a LERC blob by first inspecting its metadata with [`get_blob_info`].
///
/// This is the simplest way to decode a LERC blob when you don’t know its
/// layout ahead of time. Internally calls [`get_blob_info`] and then [`decode_with_info`].
///
/// # Parameters
/// - `blob`: The LERC-compressed input byte slice.
///
/// # Returns
/// A tuple of decoded data and optional validity mask.
pub fn decode_auto<T: LercDataType>(blob: &[u8]) -> Result<(Vec<T>, Option<Vec<u8>>), LercError> {
    let info = get_blob_info(blob)?;

    decode_with_info::<T>(blob, &info)
}