Hayro JPEG 2000

https://docs.rs/hayro-jpeg2000/0.3.5
Admin
A memory-safe, pure-Rust JPEG 2000 decoder that supports both raw J2C codestreams and JP2 container...
Tokens:116,688
Snippets:857
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic unwrap Usage

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Demonstrates the basic usage of `unwrap` to get the value from an `Ok` variant. Panics if the `Result` is an `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

--------------------------------

### Calculate Precinct Start Coordinates and Dimensions

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tile.rs.html

Calculates the starting coordinates and dimensions for precincts within a tile, considering resolution and stride. It handles alignment to multiples of precinct step sizes.

```rust
let num_precincts_x = self.num_precincts_x();

        let mut ppx = self.precinct_exponent_x();
        let mut ppy = self.precinct_exponent_y();

        let mut y_start = (self.rect.y0 / (1 << ppy)) * (1 << ppy);
        let mut x_start = (self.rect.x0 / (1 << ppx)) * (1 << ppx);

        // It is unclear why this is necessary, but it is. The spec only
        // mentions that ppx/ppy must be decreased when calculating codeblock
        // dimensions, but not that it's necessary for precincts as well.
        if self.resolution > 0 {
            ppx = ppx.checked_sub(1)?;
            ppy = ppy.checked_sub(1)?;

            x_start /= 2;
            y_start /= 2;
        }

        let ppx_pow2 = 1_u32 << ppx;
        let ppy_pow2 = 1_u32 << ppy;

        let nl_minus_r = self
            .component_tile
            .component_info
            .num_decomposition_levels()
            - self.resolution;

        let x_stride = 
            1_u32.checked_shl(self.precinct_exponent_x().checked_add(nl_minus_r)? as u32)?;
        let y_stride = 
            1_u32.checked_shl(self.precinct_exponent_y().checked_add(nl_minus_r)? as u32)?;

        let precinct_x_step = (self
            .component_tile
            .component_info
            .size_info
            .horizontal_resolution as u32)
            .checked_mul(x_stride)?;

        let precinct_y_step = (self
            .component_tile
            .component_info
            .size_info
            .vertical_resolution as u32)
            .checked_mul(y_stride)?;

        // These variables are used to map the start coordinates of each
        // precinct _on the reference grid_. Remember that the first
        // precinct in each row/column is at the start position of the tile
        // which might not be a multiple of precinct exponent, but all subsequent
        // precincts are at a multiple of the exponent.
        let mut r_x = self.component_tile.tile.rect.x0;
        let mut r_y = self.component_tile.tile.rect.y0;

        // The second part of the condition in the formula in B.12.1.3. If it
        // is divisible, then we can't take the x/y position of the tile
        // as the start of the precinct, but instead have to advance to the
        // next multiple.
        if !r_x.is_multiple_of(precinct_x_step)
            && (self.rect.x0 * (1 << nl_minus_r)).is_multiple_of(precinct_x_step)
        {
            r_x = r_x.checked_next_multiple_of(precinct_x_step)?;
        }

        // Same as above.
        if !r_y.is_multiple_of(precinct_y_step)
            && (self.rect.y0 * (1 << nl_minus_r)).is_multiple_of(precinct_y_step)
        {
            r_y = r_y.checked_next_multiple_of(precinct_y_step)?;
        }

        let iter = (0..num_precincts_y).flat_map(move |y| {
            let y0 = y * ppy_pow2 + y_start;
            let mut r_x = r_x;

            let res = (0..num_precincts_x).map(move |x| {
                let x0 = x * ppx_pow2 + x_start;

                let data = PrecinctData {
                    r_x,
                    r_y,
                    rect: IntRect::from_xywh(x0, y0, ppx_pow2, ppy_pow2),
                    idx: num_precincts_x as u64 * y as u64 + x as u64,
                };

                // If r_x is already aligned, we simply step by `precinct_x_step`.
                // Otherwise (can only be the case for precincts in the first
                // row or column), align to the next multiple.
                r_x = (r_x + 1).next_multiple_of(precinct_x_step);

                data
            });

            // Same as for r_x.
            r_y = (r_y + 1).next_multiple_of(precinct_y_step);

            res
        });

        Some(iter)
    }

```

--------------------------------

### Iterating and Calculating Product with Result

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

This example demonstrates how to use the `product` method on an iterator of Results. If any element fails to parse, the entire operation returns an Err. Otherwise, it returns the Ok value of the product.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
```

```rust
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### JPEG2000 Standard Example B.4 Test Case

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tile.rs.html

Tests the calculation of image and tile dimensions based on JPEG2000 size data, as per standard example B.4. This includes setting up component size information and global coding style.

```rust
#[test]
fn test_jpeg2000_standard_example_b4() {
    let component_size_info_0 = ComponentSizeInfo {
        precision: 8,
        horizontal_resolution: 1,
        vertical_resolution: 1,
    };

    let dummy_component_coding_style = CodingStyleComponent {
        flags: CodingStyleFlags::default(),
        parameters: CodingStyleParameters {
            num_decomposition_levels: 0,
            num_resolution_levels: 0,
            code_block_width: 0,
            code_block_height: 0,
            code_block_style: CodeBlockStyle::default(),
            transformation: WaveletTransform::Irreversible97,
            precinct_exponents: vec![],
        },
    };

    let dummy_quantization_info = QuantizationInfo {
        quantization_style: QuantizationStyle::NoQuantization,
        guard_bits: 0,
        step_sizes: vec![],
    };

    let component_info_0 = ComponentInfo {
        size_info: component_size_info_0,
        coding_style: dummy_component_coding_style.clone(),
        quantization_info: dummy_quantization_info.clone(),
    };

    let component_size_info_1 = ComponentSizeInfo {
        precision: 8,
        horizontal_resolution: 2,
        vertical_resolution: 2,
    };

    let component_info_1 = ComponentInfo {
        size_info: component_size_info_1,
        coding_style: dummy_component_coding_style.clone(),
        quantization_info: dummy_quantization_info.clone(),
    };

    let size_data = SizeData {
        reference_grid_width: 1432,
        reference_grid_height: 954,
        image_area_x_offset: 152,
        image_area_y_offset: 234,
        tile_width: 396,
        tile_height: 297,
        tile_x_offset: 0,
        tile_y_offset: 0,
        component_sizes: vec![component_size_info_0, component_size_info_1],
        x_shrink_factor: 1,
        y_shrink_factor: 1,
        x_resolution_shrink_factor: 1,
        y_resolution_shrink_factor: 1,
    };

    assert_eq!(size_data.image_width(), 1280);
    assert_eq!(size_data.image_height(), 720);

    assert_eq!(size_data.num_x_tiles(), 4);
    assert_eq!(size_data.num_y_tiles(), 4);
    assert_eq!(size_data.num_tiles(), 16);

    let header = Header {
        size_data,
        // Just dummy values.
        global_coding_style: CodingStyleDefault {
            progression_order: ProgressionOrder::LayerResolutionComponentPosition,
            num_layers: 0,
            mct: false,
            component_parameters: CodingStyleComponent {
                flags: CodingStyleFlags::default(),
                parameters: CodingStyleParameters {
                    num_decomposition_levels: 0,
                    num_resolution_levels: 0,
                    code_block_width: 0,
                    code_block_height: 0,
                    code_block_style: CodeBlockStyle::default(),
                    transformation: WaveletTransform::Irreversible97,
                    precinct_exponents: vec![],
                },
            },
        },
    };
}
```

--------------------------------

### Iterating and Calculating Sum with Result

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

This example shows how to use the `sum` method on an iterator of Results. It includes a closure that returns an Err for negative numbers. If any element is negative, the sum operation returns that Err; otherwise, it returns the Ok sum.

```rust
let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };
let v = vec![1, 2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Ok(3));
```

```rust
let v = vec![1, -2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Err("Negative element found"));
```

--------------------------------

### Coefficient Value and Sign Handling

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/bitplane.rs.html

Provides methods to get the decoded integer value of a coefficient and to set or get its sign bit. The magnitude is stored in the lower 31 bits.

```rust
impl Coefficient {
    pub(crate) fn get(&self) -> i32 {
        let mut magnitude = (self.0 & !0x80000000) as i32;
        // Map sign (0 for positive, 1 for negative) to 1, -1.
        magnitude *= 1 - 2 * (self.sign() as i32);

        magnitude
    }

    fn set_sign(&mut self, sign: u8) {
        self.0 |= (sign as u32) << 31;
    }

    fn sign(&self) -> u32 {

```

--------------------------------

### Build Tile Decompositions

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/build.rs.html

Initiates the building process for tile decompositions, which involves setting up all necessary structures for processing code-blocks within a tile. This is the main entry point for the build process.

```rust
pub(crate) fn build(tile: &Tile<'_>, storage: &mut DecompositionStorage<'_>) -> Result<()> {
    build_decompositions(tile, storage)
}
```

--------------------------------

### Create ResolutionTile Instance

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tile.rs.html

Initializes a `ResolutionTile` with its resolution, decomposition level, and the underlying `ComponentTile`. It asserts that the specified resolution is valid for the component and calculates the tile's rectangle based on the resolution and decomposition levels.

```rust
pub(crate) fn new(component_tile: ComponentTile<'a>, resolution: u8) -> Self {
        assert!(
            component_tile
                .component_info
                .coding_style
                .parameters
                .num_resolution_levels
                > resolution
        );

        let rect = {
            // See formula B-14.
            let n_l = component_tile
                .component_info
                .coding_style
                .parameters
                .num_decomposition_levels;

            let tx0 = (component_tile.rect.x0 as u64)
                .div_ceil(2_u64.pow(n_l as u32 - resolution as u32)) as u32;
            let ty0 = (component_tile.rect.y0 as u64)
                .div_ceil(2_u64.pow(n_l as u32 - resolution as u32)) as u32;
            let tx1 = (component_tile.rect.x1 as u64)
                .div_ceil(2_u64.pow(n_l as u32 - resolution as u32)) as u32;
            
```

--------------------------------

### report(self) -> ExitCode

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Is called to get the representation of the value as status code. This status code is returned to the operating system.

```APIDOC
## fn report(self) -> ExitCode

### Description
Is called to get the representation of the value as status code. This status code is returned to the operating system.

### Response
- `ExitCode` - The status code representation of the Result.
```

--------------------------------

### Create ComponentTile Instance

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tile.rs.html

Initializes a `ComponentTile` with references to the parent `Tile` and `ComponentInfo`. It calculates the component's specific rectangle within the tile, adjusting for resolution differences.

```rust
pub(crate) fn new(tile: &'a Tile<'a>, component_info: &'a ComponentInfo) -> Self {
        let tile_rect = tile.rect;

        let rect = if component_info.size_info.horizontal_resolution == 1
            && component_info.size_info.vertical_resolution == 1
        {
            tile_rect
        } else {
            // As described in B-12.
            let t_x0 = tile_rect
                .x0
                .div_ceil(component_info.size_info.horizontal_resolution as u32);
            let t_y0 = tile_rect
                .y0
                .div_ceil(component_info.size_info.vertical_resolution as u32);
            let t_x1 = tile_rect
                .x1
                .div_ceil(component_info.size_info.horizontal_resolution as u32);
            let t_y1 = tile_rect
                .y1
                .div_ceil(component_info.size_info.vertical_resolution as u32);

            IntRect::from_ltrb(t_x0, t_y0, t_x1, t_y1)
        };

        ComponentTile {
            tile,
            component_info,
            rect,
        }
    }
```

--------------------------------

### Quantum Error (QE) Table Initialization

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/arithmetic_decoder.rs.html

Initializes the `QE_TABLE` static array with 47 entries of `QeData`, based on Table C.2 of the JPEG 2000 standard. This table is used for probability estimation during arithmetic decoding.

```rust
/// QE values and associated data from Table C.2.
#[rustfmt::skip]
static QE_TABLE: [QeData; 47] = qe!(
    0x5601, 1, 1, true,
    0x3401, 2, 6, false,
    0x1801, 3, 9, false,
    0x0AC1, 4, 12, false,
    0x0521, 5, 29, false,
    0x0221, 38, 33, false,
    0x5601, 7, 6, true,
    0x5401, 8, 14, false,
    0x4801, 9, 14, false,
    0x3801, 10, 14, false,
    0x3001, 11, 17, false,
    0x2401, 12, 18, false,
    0x1C01, 13, 20, false,
    0x1601, 29, 21, false,
    0x5601, 15, 14, true,
    0x5401, 16, 14, false,
    0x5101, 17, 15, false,
    0x4801, 18, 16, false,
    0x3801, 19, 17, false,
    0x3401, 20, 18, false,
    0x3001, 21, 19, false,
    0x2801, 22, 19, false,
    0x2401, 23, 20, false,
    0x2201, 24, 21, false,
    0x1C01, 25, 22, false,
    0x1801, 26, 23, false,
    0x1601, 27, 24, false,
    0x1401, 28, 25, false,
    0x1201, 29, 26, false,
    0x1101, 30, 27, false,
    0x0AC1, 31, 28, false,
    0x09C1, 32, 29, false,
    0x08A1, 33, 30, false,
    0x0521, 34, 31, false,
    0x0441, 35, 32, false,
    0x02A1, 36, 33, false,
    0x0221, 37, 34, false,
    0x0141, 38, 35, false,
    0x0111, 39, 36, false,
    0x0085, 40, 37, false,
    0x0049, 41, 38, false,
    0x0025, 42, 39, false,
    0x0015, 43, 40, false,
    0x0009, 44, 41, false,
    0x0005, 45, 42, false,
    0x0001, 45, 43, false,
    0x5601, 46, 46, false,
);
```

--------------------------------

### into_ok

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Returns the contained Ok value, never panics. This is an experimental nightly-only API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. This is a nightly-only experimental API. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Method
`into_ok()`

### Parameters
None

### Request Example
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

### Response
- Returns the contained `Ok` value.
```

--------------------------------

### Get Current Byte Offset

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/reader.rs.html

Returns the current position in the data as a byte offset (number of full bytes read).

```rust
pub(crate) fn offset(&self) -> usize {
        self.byte_pos()
    }
```

--------------------------------

### Get Current Bit Position within Byte

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/reader.rs.html

Calculates and returns the current bit offset within the current byte (0-7).

```rust
pub(crate) fn bit_pos(&self) -> usize {
        self.cur_pos % 8
    }
```

--------------------------------

### Get Current Byte Position

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/reader.rs.html

Calculates and returns the current byte position within the data based on the internal bit position.

```rust
pub(crate) fn byte_pos(&self) -> usize {
        self.cur_pos / 8
    }
```

--------------------------------

### Rust: Initialize Tile Structure

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tile.rs.html

Creates a new `Tile` instance based on the provided index and main header information. This function calculates the tile's rectangle boundaries.

```rust
impl<'a> Tile<'a> {
    fn new(idx: u32, header: &Header<'_>) -> Self {
        let rect = {
            let size_data = &header.size_data;

            let x_coord = size_data.tile_x_coord(idx);
            let y_coord = size_data.tile_y_coord(idx);

            // See B-7, B-8, B-9 and B-10.
            let x0 = u32::max(
                size_data.tile_x_offset + x_coord * size_data.tile_width,
                size_data.image_area_x_offset,
            );
            let y0 = u32::max(
                size_data.tile_y_offset + y_coord * size_data.tile_height,
                size_data.image_area_y_offset,
            );

            // Note that `x1` and `y1` are exclusive.
            let x1 = u32::min(
                size_data.tile_x_offset + (x_coord + 1) * size_data.tile_width,
                size_data.reference_grid_width,
            );
            let y1 = u32::min(
                size_data.tile_y_offset + (y_coord + 1) * size_data.tile_height,
                size_data.reference_grid_height,
            );

            IntRect::from_ltrb(x0, y0, x1, y1)
        };

        Tile {
            idx,
            // Will be filled once we start parsing.
            tile_parts: vec![],
            rect,
            // By default, each tile inherits the settings from the main
            // header. When parsing the tile parts, some of these settings
            // might be overridden.
            component_infos: header.component_infos.clone(),
            progression_order: header.global_coding_style.progression_order,
            mct: header.global_coding_style.mct,
            num_layers: header.global_coding_style.num_layers,
        }
    }

    pub(crate) fn component_tiles(&self) -> impl Iterator<Item = ComponentTile<'_>> {
        self.component_infos
            .iter()
            .map(|i| ComponentTile::new(self, i))
    }
}
```

--------------------------------

### Error::cause Implementation for DecodeError (Deprecated)

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/enum.DecodeError.html

Deprecated method for getting the underlying cause of the error. Use Error::source instead.

```rust
fn cause(&self) -> Option<&dyn Error> {
    // Implementation details
}
```

--------------------------------

### Default DecodeSettings

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/struct.DecodeSettings.html

Provides the default configuration for DecodeSettings, which is recommended for most use cases.

```rust
fn default() -> Self
```

--------------------------------

### Initialize BitReader

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/reader.rs.html

Creates a new `BitReader` instance from a byte slice. Ensure the data slice is valid.

```rust
pub(crate) fn new(data: &'a [u8]) -> Self {
        Self { data, cur_pos: 0 }
    }
```

--------------------------------

### Get truncated data slice

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/math.rs.html

Returns the original (non-padded) data as an immutable slice. Use this to access the data without the SIMD padding.

```rust
impl<const N: usize> SimdBuffer<N> {
    /// Returns only the original (non-padded) data as an immutable slice.
    pub(crate) fn truncated(&self) -> &[f32] {
        &self.data[..self.original_len]
    }
}
```

--------------------------------

### Get Color Space Enumeration

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/lib.rs.html

Determines the color space from the image boxes, defaulting to Unknown if not specified. Handles Enumerated color spaces.

```rust
fn get_color_space(boxes: &ImageBoxes, num_components: usize) -> Result<ColorSpace> {
    let cs = match boxes
        .color_specification
        .as_ref()
        .map(|c| &c.color_space)
        .unwrap_or(&jp2::colr::ColorSpace::Unknown)
    {
        jp2::colr::ColorSpace::Enumerated(e) => {
            match e {
                // ... (rest of the match arm for EnumeratedColorspace) ...
```

--------------------------------

### Error::description Implementation for DecodeError (Deprecated)

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/enum.DecodeError.html

Deprecated method for getting a string description of the error. Use the Display impl or to_string() instead.

```rust
fn description(&self) -> &str {
    // Implementation details
}
```

--------------------------------

### and Method Usage

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Demonstrates the `and` method, which returns the second `Result` if the first is `Ok`, otherwise returns the first `Result`'s `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### Get Number of Channels for ColorSpace

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/enum.ColorSpace.html

Returns the number of expected channels for a given color space. This is useful for understanding the data structure of an image.

```rust
pub fn num_channels(&self) -> u8
```

--------------------------------

### from_output(output: <Result<T, E> as Try>::Output) -> Result<T, E>

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Constructs the type from its `Output` type. This is an experimental API.

```APIDOC
## fn from_output(output: T) -> Result<T, E>

### Description
Constructs the type from its `Output` type. This is a nightly-only experimental API.

### Parameters
#### Path Parameters
- `output` (T) - Required - The output value to construct the Result from.

### Response
- `Result<T, E>` - The constructed Result type.
```

--------------------------------

### SimdBuffer Creation and Access

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/math.rs.html

Provides methods for creating SimdBuffer instances, either from existing data or with zeros, and accessing the original, non-padded data.

```APIDOC
## SimdBuffer<N>

### Description
Represents a buffer of floating-point numbers optimized for SIMD operations, automatically padding data to a multiple of `N`.

### Methods

#### `new(data: Vec<f32>) -> Self`
Creates a new `SimdBuffer` from a `Vec<f32>`, padding it to a multiple of `N`.

#### `zeros(original_len: usize) -> Self`
Creates a new `SimdBuffer` filled with zeros, with a specified original length.

#### `truncated(&self) -> &[f32]`
Returns only the original (non-padded) data as an immutable slice.

#### `padded_len(original_len: usize) -> usize`
Calculates the length padded to a multiple of `N`.

### Deref and DerefMut Implementations

`SimdBuffer<N>` implements `Deref` and `DerefMut` to allow treating it as a `&[f32]` or `&mut [f32]` respectively, accessing the padded data.
```

--------------------------------

### CoefficientState Bit Manipulation

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/bitplane.rs.html

Provides methods to set and get individual bits within the `CoefficientState` struct, which is used to track the state of a coefficient during decoding.

```rust
impl CoefficientState {
    #[inline(always)]
    fn set_bit(&mut self, shift: u8, value: u8) {
        debug_assert!(value < 2);

        self.0 &= !(1_u8 << shift);
        self.0 |= value << shift;
    }

    #[inline(always)]
    fn set_significant(&mut self) {
        self.set_bit(SIGNIFICANCE_SHIFT, 1);
    }

    #[inline(always)]
    fn set_zero_coded(&mut self, value: u8) {
        self.set_bit(HAS_ZERO_CODING_SHIFT, value & 1);
    }

    #[inline(always)]
    fn set_magnitude_refined(&mut self) {
        self.set_bit(HAS_MAGNITUDE_REFINEMENT_SHIFT, 1);
    }

    #[inline(always)]
    fn is_significant(&self) -> bool {
        self.significance() == 1
    }

    #[inline(always)]
    fn significance(&self) -> u8 {
        (self.0 >> SIGNIFICANCE_SHIFT) & 1
    }

    #[inline(always)]
    fn magnitude_refinement(&self) -> u8 {
        (self.0 >> HAS_MAGNITUDE_REFINEMENT_SHIFT) & 1
    }

    #[inline(always)]
    fn is_zero_coded(&self) -> bool {
        (self.0 >> HAS_ZERO_CODING_SHIFT) & 1 == 1
    }
}
```

--------------------------------

### Get Precinct Exponent Y

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tile.rs.html

Retrieves the vertical precinct size exponent (PPy) for the current resolution level from the component's coding style parameters.

```rust
self.component_tile
            .component_info
            .coding_style
            .parameters
            .precinct_exponents[self.resolution as usize]
            .1
```

--------------------------------

### CloneToUninit Trait Implementation (Nightly)

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/enum.ColorSpace.html

An experimental nightly-only API for performing copy-assignment from a `ColorSpace` value to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Get a reference to the contained value

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Use `as_ref()` to obtain a `Result<&T, &E>` from a `&Result<T, E>`. This allows inspecting the contents without consuming the original Result.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### ok

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Converts `Result<T, E>` to `Option<T>`, consuming the result.

```APIDOC
## ok

### Description
Converts `Result<T, E>` to `Option<T>`, consuming the result. If the result is `Ok`, it returns `Some(T)`. If the result is `Err`, it returns `None`.

### Method
`ok`

### Response
- `Option<T>`: `Some(T)` if the result was `Ok`, `None` otherwise.

### Request Example
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```
```

--------------------------------

### Get Precinct Exponent X

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tile.rs.html

Retrieves the horizontal precinct size exponent (PPx) for the current resolution level from the component's coding style parameters.

```rust
self.component_tile
            .component_info
            .coding_style
            .parameters
            .precinct_exponents[self.resolution as usize]
            .0
```

--------------------------------

### Clone Implementation for ColorSpace

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/enum.ColorSpace.html

Provides methods for cloning ColorSpace values. Use `clone` to create a duplicate and `clone_from` for efficient copy-assignment.

```rust
fn clone(&self) -> ColorSpace
```

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

--------------------------------

### Get Remaining Data Slice

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/reader.rs.html

Returns a slice of the remaining data from the current position to the end. Returns `None` if the current position is beyond the data length.

```rust
pub(crate) fn tail(&self) -> Option<&'a [u8]> {
        self.data.get(self.byte_pos()..)
    }
```

--------------------------------

### Get Current Byte

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/arithmetic_decoder.rs.html

Retrieves the current byte from the decoder's data buffer based on the base pointer. This is a utility function for accessing raw data.

```rust
fn current_byte(&self) -> u8 {
        self.data
            .get(self.base_pointer as usize)
            .copied()
    }
```

--------------------------------

### f32x8 Structure and Methods

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/math.rs.html

Provides documentation for the f32x8 struct, including methods for creating, manipulating, and performing operations on SIMD vectors of f32.

```APIDOC
## f32x8<S: Simd>

### Description
Represents a SIMD vector of 8 single-precision floating-point numbers, aligned to 32 bytes. It is generic over a `Simd` type `S`.

### Methods

#### `from_slice(_simd: S, slice: &[f32]) -> Self`
Creates an `f32x8` instance from the first 8 elements of a slice.

#### `splat(_simd: S, value: f32) -> Self`
Creates an `f32x8` instance where all elements are set to the given `value`.

#### `mul_add(self, mul: Self, addend: Self) -> Self`
Performs a fused multiply-add operation: `self * mul + addend`.

#### `floor(self) -> Self`
Applies the floor function to each element of the vector.

#### `store(self, slice: &mut [f32])`
Stores the elements of the `f32x8` vector into the provided mutable slice.

#### `zip_low(self, other: Self) -> Self`
Interleaves the lower 4 elements of `self` and `other`.

#### `zip_high(self, other: Self) -> Self`
Interleaves the upper 4 elements of `self` and `other`.

#### `min(self, other: Self) -> Self`
Computes the element-wise minimum of two `f32x8` vectors.

#### `max(self, other: Self) -> Self`
Computes the element-wise maximum of two `f32x8` vectors.

### Traits

#### `Add`
Implements the addition operator (`+`) for element-wise addition of two `f32x8` vectors.

#### `Sub`
Implements the subtraction operator (`-`) for element-wise subtraction of two `f32x8` vectors.

#### `Mul`
Implements the multiplication operator (`*`) for element-wise multiplication of two `f32x8` vectors.
```

--------------------------------

### TagTree Read Function

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tag_tree.rs.html

Reads a tag value from the TagTree at a specific coordinate (x, y). It initiates the recursive reading process by calling `read_tag_node` starting from the root.

```rust
    pub(crate) fn read(
        &mut self,
        x: u32,
        y: u32,
        reader: &mut BitReader<'_>,
        max_val: u32,
        nodes: &mut [TagNode],
    ) -> Option<u32> {
        debug_assert!(x < self.width && y < self.height);

        read_tag_node(self.root, x, y, reader, 0, max_val, nodes)
    }
}
```

--------------------------------

### Initialize Decoder State (INITDEC)

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/arithmetic_decoder.rs.html

Implements the INITDEC procedure from the JPEG2000 standard (Annex C.3.5). It initializes the C and A registers and performs initial bitstream reads.

```rust
fn initialize(&mut self) {
        self.c = ((self.current_byte() as u32) ^ 0xff) << 16;
        self.read_byte();

        self.c <<= 7;
        self.shift_count -= 7;
        self.a = 0x8000;
    }
```

--------------------------------

### Get a mutable reference to the contained value

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/error/type.Result.html

Use `as_mut()` to obtain a `Result<&mut T, &mut E>` from a `&mut Result<T, E>`. This enables in-place modification of the contained value.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Create SimdBuffer filled with zeros

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/math.rs.html

Creates a new SimdBuffer of a specified original length, filled with zeros and padded to a multiple of N. Use this for initializing buffers that will be populated later.

```rust
impl<const N: usize> SimdBuffer<N> {
    /// Create a new `SimdBuffer` filled with zeros.
    pub(crate) fn zeros(original_len: usize) -> Self {
        let padded_len = Self::padded_len(original_len);
        let data = vec![0.0; padded_len];
        Self { data, original_len }
    }

    /// Returns the length padded to a multiple of `N`
    fn padded_len(original_len: usize) -> usize {
        let remainder = original_len % N;
        let padding = N - remainder;
        original_len + padding
    }
}
```

--------------------------------

### Get Number of Components for ICCColorSpace

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/jp2/icc.rs.html

Implements a method to retrieve the number of color components for each variant of the ICCColorSpace enum. This is useful for understanding the data structure of a given color space.

```rust
impl ICCColorSpace {
    pub(crate) fn num_components(&self) -> u8 {
        match self {
            Self::Xyz => 3,
            Self::Lab => 3,
            Self::Luv => 3,
            Self::Ycbr => 3,
            Self::Yxy => 3,
            Self::Lms => 3,
            Self::Rgb => 3,
            Self::Gray => 1,
            Self::Hsv => 3,
            Self::Hls => 3,
            Self::Cmyk => 4,
            Self::Cmy => 3,
            Self::OneClr => 1,
            Self::ThreeClr => 3,
            Self::FourClr => 4,
        }
    }
}

```

--------------------------------

### From and Into Trait Implementations

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/enum.ColorSpace.html

Facilitates conversions to and from `ColorSpace` values, enabling seamless integration with other types.

```rust
fn from(t: T) -> T
```

```rust
fn into(self) -> U
```

--------------------------------

### Parse Raw JPEG2000 Codestream Header

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/mod.rs.html

Reads and parses the header information from a raw JPEG2000 codestream. It expects the stream to start with an SOC marker. This function is used internally for decoding.

```rust
pub(crate) fn parse_raw<'a>(
    stream: &'a [u8],
    settings: &DecodeSettings,
) -> Result<ParsedCodestream<'a>> {
    let mut reader = BitReader::new(stream);

    let marker = reader.read_marker()?;
    if marker != markers::SOC {
        bail!(MarkerError::Expected("SOC"));
    }

    let header = codestream::read_header(&mut reader, settings)?;
    let code_stream_data = reader.tail().ok_or(FormatError::MissingCodestream)?;

    Ok(ParsedCodestream {
        header,
        data: code_stream_data,
    })
}
```

--------------------------------

### Clone DecodeSettings

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/struct.DecodeSettings.html

Enables creating a copy of the DecodeSettings configuration.

```rust
fn clone(&self) -> DecodeSettings
```

--------------------------------

### Arithmetic Decoder Context Structure

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/arithmetic_decoder.rs.html

Defines the `ArithmeticDecoderContext` struct which stores decoding state using a bit-packed u8. It includes methods to get the index and most significant probability (mps), and to set or modify these values.

```rust
/// Bits 0-6 = index (0-46).
/// Bit 7 = mps (0 or 1).
#[derive(Copy, Clone, Debug, Default)]
pub(crate) struct ArithmeticDecoderContext(u8);

impl ArithmeticDecoderContext {
    #[inline(always)]
    pub(crate) fn index(self) -> u32 {
        (self.0 & 0x7F) as u32
    }

    #[inline(always)]
    pub(crate) fn mps(self) -> u32 {
        (self.0 >> 7) as u32
    }

    #[inline(always)]
    fn set_index(&mut self, index: u8) {
        self.0 = (self.0 & 0x80) | index;
    }

    #[inline(always)]
    fn xor_mps(&mut self, val: u32) {
        self.0 ^= ((val & 1) << 7) as u8;
    }

    #[inline(always)]
    pub(crate) fn reset(&mut self) {
        self.0 = 0;
    }

    #[inline(always)]
    pub(crate) fn reset_with_index(&mut self, index: u8) {
        self.0 = index;
    }
}
```

--------------------------------

### TagTree Initialization

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/tag_tree.rs.html

Constructor for the TagTree. It calculates the required levels for the tree based on width and height, builds the root TagNode, and stores its index along with dimensions.

```rust
impl TagTree {
    pub(crate) fn new(width: u32, height: u32, nodes: &mut Vec<TagNode>) -> Self {
        // Calculate how many levels the tree has in total.
        let level = u32::max(
            width.next_power_of_two().ilog2(),
            height.next_power_of_two().ilog2(),
        );

        let node = TagNode::build(width, height, level as u16, nodes);
        let idx = nodes.len();
        nodes.push(node);

        Self {
            root: idx,
            width,
            height,
        }
    }

```

--------------------------------

### Convert Color Space (Sycc and CIE Lab)

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/lib.rs.html

Converts the image's color space to RGB if it's enumerated as Sycc or CIE Lab. Requires the `dispatch` macro for SIMD acceleration.

```rust
fn convert_color_space(image: &mut DecodedImage<'_>, bit_depth: u8) -> Result<()> {
    if let Some(jp2::colr::ColorSpace::Enumerated(e)) = &image
        .boxes
        .color_specification
        .as_ref()
        .map(|i| &i.color_space)
    {
        match e {
            EnumeratedColorspace::Sycc => {
                dispatch!(Level::new(), simd => {
                    sycc_to_rgb(simd, image.decoded_components, bit_depth)
                })?;
            }
            EnumeratedColorspace::CieLab(cielab) => {
                dispatch!(Level::new(), simd => {
                    cielab_to_rgb(simd, image.decoded_components, bit_depth, cielab)
                })?;
            }
            _ => {} // Other enumerated color spaces are ignored for now.
        }
    }

    Ok(())
}
```

--------------------------------

### Implement ImageDecoder for Jp2Decoder

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/integration.rs.html

Implements the ImageDecoder trait for Jp2Decoder, providing methods to get image dimensions, color types, and read image data. This is essential for integrating Jp2Decoder with image processing crates.

```rust
impl ImageDecoder for Jp2Decoder {
    fn dimensions(&self) -> (u32, u32) {
        (self.width, self.height)
    }

    fn color_type(&self) -> ColorType {
        self.color_type
    }

    fn original_color_type(&self) -> ExtendedColorType {
        self.orig_color_type
    }

    fn read_image(self, buf: &mut [u8]) -> ImageResult<()> 
    where
        Self: Sized,
    {
        // we can safely .unwrap() because we've already done this on decoder creation and know this works
        let decoder = Image::new(&self.input, &DecodeSettings::default()).unwrap();
        decoder.read_image(buf)
    }

    fn read_image_boxed(self: Box<Self>, buf: &mut [u8]) -> ImageResult<()> {
        // we can safely .unwrap() because we've already done this on decoder creation and know this works
        let decoder = Image::new(&self.input, &DecodeSettings::default()).unwrap();
        decoder.read_image(buf)
    }
}
```

--------------------------------

### Get Exponent and Mantissa for JPEG2000 Sub-band

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/codestream.rs.html

Retrieves the exponent and mantissa for a specific sub-band and resolution level from the component's quantization information. Handles different quantization styles and ensures step sizes are available.

```rust
    pub(crate) fn exponent_mantissa(
        &self,
        sub_band_type: SubBandType,
        resolution: u8,
    ) -> Result<(u16, u16)> {
        let n_ll = self.coding_style.parameters.num_decomposition_levels;

        let sb_index = match sub_band_type {
            // TODO: Shouldn't be reached.
            SubBandType::LowLow => u16::MAX,
            SubBandType::HighLow => 0,
            SubBandType::LowHigh => 1,
            SubBandType::HighHigh => 2,
        };

        let step_sizes = &self.quantization_info.step_sizes;
        match self.quantization_info.quantization_style {
            QuantizationStyle::NoQuantization | QuantizationStyle::ScalarExpounded => {
                let entry = if resolution == 0 {
                    step_sizes.first()
                } else {
                    step_sizes.get(1 + (resolution as usize - 1) * 3 + sb_index as usize)
                };

                Ok(entry
                    .map(|s| (s.exponent, s.mantissa))
                    .ok_or(ValidationError::MissingStepSize)?)
            }
            QuantizationStyle::ScalarDerived => {
                let (e_0, mantissa) = step_sizes
                    .first()
                    .map(|s| (s.exponent, s.mantissa))
                    .ok_or(ValidationError::MissingStepSize)?;
                let n_b = if resolution == 0 {
                    n_ll as u16
                } else {
                    n_ll as u16 + 1 - resolution as u16
                };
                // TODO: Implement ScalarDerived logic
                Ok((e_0, mantissa))
            }
        }
    }
}
```

--------------------------------

### Decoder Context Initialization and Reset

Source: https://docs.rs/hayro-jpeg2000/0.3.5/src/hayro_jpeg2000/j2c/decode.rs.html

Manages the state required for decoding, including tile-specific contexts, raw channel data, and decomposition storage. The `reset` method prepares the context for decoding a new image or tile, initializing buffers and clearing previous data.

```rust
/// A decoder context for decoding JPEG2000 images.<br>#[derive(Default)]<br>pub struct DecoderContext<'a> {<br>    tile_decode_context: TileDecodeContext,<br>    /// The raw, decoded samples for each channel.<br>    pub(crate) channel_data: Vec<ComponentData>,<br>    storage: DecompositionStorage<'a>,<br>}<br><br>impl DecoderContext<'_> {<br>    fn reset(&mut self, header: &Header<'_>, initial_tile: &Tile<'_>) {<br>        self.tile_decode_context.reset();<br>        self.storage.reset();<br><br>        self.channel_data.clear();<br>        // TODO: SIMD Buffers should be reused across runs!<br>        for info in &initial_tile.component_infos {<br>            self.channel_data.push(ComponentData {<br>                container: SimdBuffer::zeros(<br>                    header.size_data.image_width() as usize<br>                        * header.size_data.image_height() as usize,<br>                ),<br>                bit_depth: info.size_info.precision,<br>            });<br>        }<br>    }<br>}
```

--------------------------------

### Borrow and BorrowMut Implementations

Source: https://docs.rs/hayro-jpeg2000/0.3.5/hayro_jpeg2000/enum.ColorSpace.html

Allows borrowing `ColorSpace` values immutably or mutably, enabling flexible data access patterns.

```rust
fn borrow(&self) -> &T
```

```rust
fn borrow_mut(&mut self) -> &mut T
```
Tokens:
Raw