ebcc 0.1.0

High-level Rust bindings to the EBCC compressor
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
107
108
109
110
111
112
113
114
115
116
117

//! Configuration types for EBCC compression.

use crate::error::{EBCCError, EBCCResult};

/// Residual compression types supported by EBCC.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum EBCCResidualType {
    /// No residual compression - base JPEG2000 only
    Jpeg2000Only,
    /// Residual compression with absolute maximum error bound
    AbsoluteError(f32),
    /// Residual compression with relative error bound
    RelativeError(f32),
}

impl EBCCResidualType {
    pub(crate) const fn as_residual(self) -> ebcc_sys::residual_t::Type {
        match self {
            Self::Jpeg2000Only => ebcc_sys::residual_t::NONE,
            Self::AbsoluteError(_) => ebcc_sys::residual_t::MAX_ERROR,
            Self::RelativeError(_) => ebcc_sys::residual_t::RELATIVE_ERROR,
        }
    }

    pub(crate) const fn as_error(self) -> f32 {
        match self {
            Self::Jpeg2000Only => 0.0,
            Self::AbsoluteError(error) | Self::RelativeError(error) => error,
        }
    }
}

/// Configuration for EBCC compression.
#[derive(Debug, Clone, PartialEq)]
pub struct EBCCConfig {
    /// Base compression ratio for JPEG2000 layer
    pub base_cr: f32,

    /// Type of residual compression to apply
    pub residual_compression_type: EBCCResidualType,
}

impl Default for EBCCConfig {
    fn default() -> Self {
        Self::new()
    }
}

impl EBCCConfig {
    /// Create a new EBCC configuration with default values.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            base_cr: 10.0,
            residual_compression_type: EBCCResidualType::Jpeg2000Only,
        }
    }

    /// Create a configuration for JPEG2000-only compression.
    #[must_use]
    pub const fn jpeg2000_only(base_cr: f32) -> Self {
        Self {
            base_cr,
            residual_compression_type: EBCCResidualType::Jpeg2000Only,
        }
    }

    /// Create a configuration for maximum error bounded compression.
    #[must_use]
    pub const fn max_absolute_error_bounded(base_cr: f32, error: f32) -> Self {
        Self {
            base_cr,
            residual_compression_type: EBCCResidualType::AbsoluteError(error),
        }
    }

    /// Create a configuration for relative error bounded compression.
    #[must_use]
    pub const fn relative_error_bounded(base_cr: f32, error: f32) -> Self {
        Self {
            base_cr,
            residual_compression_type: EBCCResidualType::RelativeError(error),
        }
    }

    /// Validate the configuration parameters.
    ///
    /// # Errors
    ///
    /// - [`EBCCError::InvalidConfig`] if `base_cr` is non-positive
    /// - [`EBCCError::InvalidConfig`] if the absolute or relative error bound
    ///   is non-positive
    pub fn validate(&self) -> EBCCResult<()> {
        // Check compression ratio
        if self.base_cr <= 0.0 {
            return Err(EBCCError::InvalidConfig(String::from(
                "Base compression ratio must be positive",
            )));
        }

        // Check residual-specific parameters
        match self.residual_compression_type {
            EBCCResidualType::AbsoluteError(error) | EBCCResidualType::RelativeError(error) => {
                if error <= 0.0 {
                    return Err(EBCCError::InvalidConfig(String::from(
                        "Error bound must be positive",
                    )));
                }
            }
            EBCCResidualType::Jpeg2000Only => {
                // No additional validation needed
            }
        }

        Ok(())
    }
}