jxl

    A JPEG XL decoder in pure MoonBit, ported from jxl-oxide

    jpeg-xl
    jxl
    image
    decoder
    Download zip
    Author
    Version
    0.1.1
    License
    MIT OR Apache-2.0
    Last updated
    12 hours ago
    Downloads
    11

    No dependencies

    #jxl.mbt

    A JPEG XL decoder written in pure MoonBit.

    This is a port of jxl-oxide by Wonwoo Choi and contributors (ported from jxl-oxide 0.12.6, commit c0cc4c7ea57c). The structure of the packages follows jxl-oxide's crates.

    Status: work in progress.

    #Known differences

    #alpha_premultiplied (libjxl conformance suite)

    Judged by the tolerance in its test.json (3.815e-6 peak and RMS for the whole frame, as scripts/conformance.py applies it), this case fails, so the official tally is 39/40. It is marked as an expected failure in tests/render_conformance.

    Our output has the same error as upstream jxl-oxide 0.12.6. We checked this by decoding alpha_premultiplied/input.jxl with the jxl-oxide 0.12.6 CLI (jxl-oxide input.jxl -f npy) and comparing it with reference_image.npy using the algorithm of libjxl/conformance scripts/conformance.py:

    channelpeak errorRMS
    R1.656e-42.82e-5
    G1.633e-42.22e-5
    B1.646e-42.22e-5
    alpha00

    The error is entirely in the three VarDCT colour channels (with Gabor-like and edge-preserving filters); the 16-bit modular alpha channel is exact. jxl-oxide's own test uses per-channel limits for this image (colour channels 0.004 peak / 1e-4 RMS, alpha 3.815e-6). A separate test compares our decode with jxl-oxide's output under those limits.

    #Not supported

    The colour management system in src/cms (a port of Little CMS 2.19's float transform path) does not support:

    • floating-point profile tags (mpet, D2Bx/B2Dx); profiles relying on them are rejected with NotSupported;
    • named-colour, device-link and abstract profiles as transform endpoints;
    • black-preserving rendering intents (10–15);
    • partial chromatic adaptation (the adaptation state is fixed at 1.0).

    None of these occur in the libjxl conformance suite or jxl-oxide's test images.

    The decoder API also leaves out two parts of jxl-oxide: the thread pool (decoding is sequential) and JxlImage::open(path) (the package does no file I/O; pass the bytes with read or feed_bytes). jxl-oxide's lcms2 and moxcms backends are replaced by the pure MoonBit CMS in src/cms.

    #License

    Like jxl-oxide, this project is dual-licensed under either of

    at your option. The copyright of the original jxl-oxide code belongs to Wonwoo Choi and the jxl-oxide contributors.

    #Third-party code

    • src/brotli is a port of Google's Brotli C decoder (google/brotli v1.1.0, c/dec and c/common), Copyright 2013 Google Inc., MIT License. Its test vectors come from google/brotli tests/testdata (MIT).

    AuxBoxData

    pub(all) enum AuxBoxData[T] {
    Data(T)
    Decoding
    NotFound
    }

    Auxiliary box data.

    AuxBoxData::has_data

    fn[T] AuxBoxData::has_data(self : AuxBoxData[T]) -> Bool

    AuxBoxData::is_decoding

    fn[T] AuxBoxData::is_decoding(self : AuxBoxData[T]) -> Bool

    AuxBoxData::is_not_found

    fn[T] AuxBoxData::is_not_found(self : AuxBoxData[T]) -> Bool

    AuxBoxData::map

    fn[T, U] AuxBoxData::map(self : AuxBoxData[T], f : (T) -> U raise?) -> AuxBoxData[U] raise?

    AuxBoxData::unwrap

    fn[T] AuxBoxData::unwrap(self : AuxBoxData[T]) -> T

    AuxBoxData::unwrap_or

    fn[T] AuxBoxData::unwrap_or(self : AuxBoxData[T], or : T) -> T

    AuxBoxList

    pub struct AuxBoxList {
    // private fields
    }

    Auxiliary box list of a JPEG XL container, which may contain Exif and/or XMP metadata.

    AuxBoxList::first_exif

    Returns the first Exif metadata, if any.

    AuxBoxList::first_xml

    fn AuxBoxList::first_xml(self : AuxBoxList) -> AuxBoxData[Bytes]

    Returns the first XML metadata, if any.

    AuxBoxReader

    pub struct AuxBoxReader {
    // private fields
    }

    AuxBoxReader::data

    fn AuxBoxReader::data(self : AuxBoxReader) -> AuxBoxData[Bytes]

    AuxBoxReader::feed_data

    fn AuxBoxReader::feed_data(self : AuxBoxReader, data : BytesView) -> Unit raise
    JxlError

    AuxBoxReader::finalize

    AuxBoxReader::is_done

    fn AuxBoxReader::is_done(self : AuxBoxReader) -> Bool

    ColorType

    pub(all) enum ColorType {
    L8
    La8
    Rgb8
    Rgba8
    L16
    La16
    Rgb16
    Rgba16
    Rgb32F
    Rgba32F
    } derive(Eq,
    Debug
    )

    Colour type of decoded images (the subset of image::ColorType used).

    CropInfo

    pub(all) struct CropInfo {
    width : Int
    height : Int
    left : Int
    top : Int
    } derive(Default, Eq,
    Debug
    )

    Cropping region information.

    CropInfo::from_region

    impl From<Region> for CropInfo.

    CropInfo::to_region

    impl From<CropInfo> for Region.

    DecodedSamples

    pub(all) enum DecodedSamples {
    U8(FixedArray[Byte])
    U16(FixedArray[Int])
    F32(FixedArray[Float])
    }

    Interleaved samples of a decoded image.

    ExtraChannel

    pub struct ExtraChannel {
    // private fields
    }

    Extra channel of the image.

    ExtraChannel::bit_depth

    Returns the bit depth of the channel.

    ExtraChannel::is_alpha

    fn ExtraChannel::is_alpha(self : ExtraChannel) -> Bool

    Returns true if the channel is an alpha channel.

    ExtraChannel::is_black

    fn ExtraChannel::is_black(self : ExtraChannel) -> Bool

    Returns true if the channel is a black channel of CMYK image.

    ExtraChannel::is_spot_colour

    fn ExtraChannel::is_spot_colour(self : ExtraChannel) -> Bool

    Returns true if the channel is a spot colour channel.

    ExtraChannel::name

    fn ExtraChannel::name(self : ExtraChannel) -> String

    Returns the name of the channel.

    ExtraChannel::ty

    Returns the type of the extra channel.

    FrameBuffer

    pub struct FrameBuffer {
    // private fields
    }

    Frame buffer representing a decoded image.

    FrameBuffer::buf

    fn FrameBuffer::buf(self : FrameBuffer) -> FixedArray[Float]

    Returns the contents of frame buffer.

    The buffer has length of width * height * channels, where n * channels + c-th sample belongs to the c-th channel. The array is shared with the frame buffer (upstream buf and buf_mut).

    FrameBuffer::buf_grouped

    fn FrameBuffer::buf_grouped(self : FrameBuffer, n : Int) -> Array[FixedArray[Float]]

    Returns the contents of frame buffer, grouped by pixels.

    Panics if n != self.channels().

    FrameBuffer::buf_mut

    fn FrameBuffer::buf_mut(self : FrameBuffer) -> FixedArray[Float]

    Returns the mutable contents of frame buffer (same array as buf).

    FrameBuffer::channels

    fn FrameBuffer::channels(self : FrameBuffer) -> Int

    Returns the number of channels of the frame buffer.

    FrameBuffer::from_grids

    For internal use only.

    FrameBuffer::height

    fn FrameBuffer::height(self : FrameBuffer) -> Int

    Returns the height of the frame buffer.

    FrameBuffer::new

    fn FrameBuffer::new(width : Int, height : Int, channels : Int) -> FrameBuffer

    Creates a new framebuffer with given dimension.

    Note that framebuffer allocations are not tracked.

    FrameBuffer::width

    fn FrameBuffer::width(self : FrameBuffer) -> Int

    Returns the width of the frame buffer.

    HdrType

    pub(all) enum HdrType {
    Pq
    Hlg
    } derive(Eq,
    Debug
    )

    HDR transfer function type, returned by JxlImage::hdr_type.

    ImageStream

    pub struct ImageStream {
    // private fields
    }

    Image stream that writes to a caller's buffer.

    ImageStream::channels

    fn ImageStream::channels(self : ImageStream) -> Int

    Returns the number of channels of the image.

    ImageStream::height

    fn ImageStream::height(self : ImageStream) -> Int

    Returns height of the image.

    ImageStream::width

    fn ImageStream::width(self : ImageStream) -> Int

    Returns width of the image.

    ImageStream::write_to_buffer_f32

    fn ImageStream::write_to_buffer_f32(self : ImageStream, buf : FixedArray[Float], start? : Int) -> Int

    Writes next samples as f32 to buf[start:], returning how many samples are written.

    ImageStream::write_to_buffer_u16

    fn ImageStream::write_to_buffer_u16(self : ImageStream, buf : FixedArray[Int], start? : Int) -> Int

    Writes next samples as u16 (stored in Int) to buf[start:], returning how many samples are written.

    ImageStream::write_to_buffer_u8

    fn ImageStream::write_to_buffer_u8(self : ImageStream, buf : FixedArray[Byte], start? : Int) -> Int

    Writes next samples as u8 to buf[start:], returning how many samples are written.

    InitializeResult

    pub enum InitializeResult {
    NeedMoreData(UninitializedJxlImage)
    Initialized(JxlImage)
    }

    Initialization result from UninitializedJxlImage::try_init.

    JpegReconstructionStatus

    pub(all) enum JpegReconstructionStatus {
    Available
    Invalid
    Unavailable
    NeedMoreData
    } derive(Eq,
    Debug
    )

    Availability and validity of JPEG bitstream reconstruction data.

    JxlDecoder

    pub struct JxlDecoder {
    // private fields
    }

    JPEG XL decoder in the role of jxl-oxide's integration::JxlDecoder.

    Supports:
    • returning images of 8-bit, 16-bit integer and 32-bit float samples
    • RGB or luma-only images, with or without alpha
    • returning ICC profiles via icc_profile
    • returning Exif metadata via exif_metadata
    • cropped decoding with read_rect
    • converting CMYK images to sRGB colour space

    It does no colour management by itself otherwise (consumers apply the returned ICC profile). Animations: only the first keyframe is returned.

    JxlDecoder::color_type

    fn JxlDecoder::color_type(self : JxlDecoder) -> ColorType

    Colour type of read_image's output.

    JxlDecoder::dimensions

    fn JxlDecoder::dimensions(self : JxlDecoder) -> (Int, Int)

    Width and height with orientation applied.

    JxlDecoder::exif_metadata

    fn JxlDecoder::exif_metadata(self : JxlDecoder) -> Bytes? raise
    JxlError

    The first Exif box's payload, if any.

    JxlDecoder::icc_profile

    fn JxlDecoder::icc_profile(self : JxlDecoder) -> Bytes?

    ICC profile of read_image's output (always present).

    JxlDecoder::image

    fn JxlDecoder::image(self : JxlDecoder) -> JxlImage

    The underlying image.

    JxlDecoder::new

    Initializes a decoder which reads the given image.

    JxlDecoder::read_image

    Decodes the first keyframe into interleaved samples of color_type().

    JxlDecoder::read_rect

    fn JxlDecoder::read_rect(self : JxlDecoder, x : Int, y : Int, width : Int, height : Int) -> DecodedSamples raise
    JxlError

    Decodes a region of the first keyframe (image::ImageDecoderRect), rows packed without padding.

    JxlImage

    pub struct JxlImage {
    // private fields
    }

    JPEG XL image.

    JxlImage::aux_boxes

    fn JxlImage::aux_boxes(self : JxlImage) -> AuxBoxList

    Returns the list of auxiliary boxes in the JPEG XL container.

    The list may contain Exif and XMP metadata.

    JxlImage::builder

    fn JxlImage::builder() -> JxlImageBuilder

    Creates a decoder builder with default options.

    JxlImage::current_image_region

    fn JxlImage::current_image_region(self : JxlImage) -> CropInfo

    Returns current cropping region (region of interest).

    JxlImage::feed_bytes

    fn JxlImage::feed_bytes(self : JxlImage, buf : BytesView) -> Int raise
    JxlError

    Feeds more data into the decoder.

    Returns total consumed bytes from the buffer.

    JxlImage::finalize

    fn JxlImage::finalize(self : JxlImage) -> Unit raise
    JxlError

    Signals the end of bitstream.

    This is automatically done if read() is used to decode the image.

    JxlImage::frame

    fn JxlImage::frame(self : JxlImage, frame_idx : Int) ->
    IndexedFrame
    ?

    Returns frame data by frame index, including frames that are not displayed directly.

    There are some situations where a frame is not displayed directly:
    • It may be marked as reference only, and meant to be only used by other frames.
    • It may contain LF image (which is 8x downsampled version) of another VarDCT frame.
    • Zero duration frame that is not the last frame of image is blended with following frames and displayed together.

    JxlImage::frame_by_keyframe

    fn JxlImage::frame_by_keyframe(self : JxlImage, keyframe_index : Int) ->
    IndexedFrame
    ?

    Returns frame data by keyframe index.

    JxlImage::frame_header

    fn JxlImage::frame_header(self : JxlImage, keyframe_index : Int) ->
    FrameHeader
    ?

    Returns the frame header for the given keyframe index, or None if the keyframe does not exist.

    JxlImage::frame_offset

    fn JxlImage::frame_offset(self : JxlImage, frame_index : Int) -> Int?

    Returns the offset of frame within codestream, in bytes.

    JxlImage::hdr_type

    fn JxlImage::hdr_type(self : JxlImage) -> HdrType?

    Returns what HDR transfer function the image uses, if there's any.

    Returns None if the image is not HDR one.

    JxlImage::height

    fn JxlImage::height(self : JxlImage) -> Int

    Returns the image height with orientation applied.

    JxlImage::image_header

    Returns the image header.

    JxlImage::is_loading_done

    fn JxlImage::is_loading_done(self : JxlImage) -> Bool

    Returns whether the image is loaded completely, without missing animation keyframes or partially loaded frames.

    JxlImage::jpeg_reconstruction_status

    fn JxlImage::jpeg_reconstruction_status(self : JxlImage) -> JpegReconstructionStatus

    Returns availability and validity of JPEG bitstream reconstruction data.

    JxlImage::num_loaded_frames

    fn JxlImage::num_loaded_frames(self : JxlImage) -> Int

    Returns the number of currently loaded frames, including frames that are not displayed directly.

    JxlImage::num_loaded_keyframes

    fn JxlImage::num_loaded_keyframes(self : JxlImage) -> Int

    Returns the number of currently loaded keyframes.

    JxlImage::original_icc

    fn JxlImage::original_icc(self : JxlImage) -> Bytes?

    Returns the original ICC profile embedded in the image.

    JxlImage::pixel_format

    fn JxlImage::pixel_format(self : JxlImage) -> PixelFormat

    Returns the pixel format of the rendered image.

    JxlImage::read_with_defaults

    fn JxlImage::read_with_defaults(data : Bytes) -> JxlImage raise
    JxlError

    Reads an image from the bytes with default options.

    JxlImage::reader

    Returns the internal reader.

    JxlImage::reconstruct_jpeg

    fn JxlImage::reconstruct_jpeg(self : JxlImage) -> Bytes raise
    JxlError

    Reconstructs JPEG bitstream and returns the JPEG file.

    Raises if the reconstruction data is not available, incomplete or invalid.

    Note that reconstruction may fail even if jpeg_reconstruction_status returned Available.

    JxlImage::render_frame

    fn JxlImage::render_frame(self : JxlImage, keyframe_index : Int) -> Render raise
    JxlError

    Renders the given keyframe.

    JxlImage::render_frame_cropped

    fn JxlImage::render_frame_cropped(self : JxlImage, keyframe_index : Int) -> Render raise
    JxlError

    Renders the given keyframe with optional cropping region.

    JxlImage::render_loading_frame

    fn JxlImage::render_loading_frame(self : JxlImage) -> Render raise
    JxlError

    Renders the currently loading keyframe.

    JxlImage::render_loading_frame_cropped

    fn JxlImage::render_loading_frame_cropped(self : JxlImage) -> Render raise
    JxlError

    Renders the currently loading keyframe with optional cropping region.

    JxlImage::render_spot_color

    fn JxlImage::render_spot_color(self : JxlImage) -> Bool

    Returns whether the spot color channels will be rendered.

    JxlImage::rendered_cicp

    fn JxlImage::rendered_cicp(self : JxlImage) -> FixedArray[Int]?

    Returns the CICP tag of the color encoding of rendered images, if there's any.

    JxlImage::rendered_icc

    fn JxlImage::rendered_icc(self : JxlImage) -> Bytes

    Returns the ICC profile that describes rendered images.

    The returned profile will change if different color encoding is specified using request_icc or request_color_encoding.

    JxlImage::request_color_encoding

    fn JxlImage::request_color_encoding(self : JxlImage, color_encoding :
    EnumColourEncoding
    ) -> Unit

    Requests the decoder to render in specific color encoding, described by EnumColourEncoding.

    JxlImage::request_icc

    fn JxlImage::request_icc(self : JxlImage, icc_profile : Bytes) -> Unit raise
    JxlError

    Requests the decoder to render in specific color encoding, described by an ICC profile.

    Raises if it cannot parse the ICC profile.

    JxlImage::set_cms

    Sets color management system implementation to be used by the renderer.

    JxlImage::set_image_region

    fn JxlImage::set_image_region(self : JxlImage, region : CropInfo) -> JxlImage

    Sets the cropping region (region of interest).

    Subsequent rendering methods will crop the image buffer according to the region.

    JxlImage::set_render_spot_color

    fn JxlImage::set_render_spot_color(self : JxlImage, render_spot_color : Bool) -> JxlImage

    Sets whether the spot colour channels will be rendered.

    JxlImage::width

    fn JxlImage::width(self : JxlImage) -> Int

    Returns the image width with orientation applied.

    JxlImageBuilder

    pub struct JxlImageBuilder {
    // private fields
    }

    JPEG XL image decoder builder.

    JxlImageBuilder::alloc_tracker

    Sets an allocation tracker.

    JxlImageBuilder::build_uninit

    Consumes the builder, and creates an empty, uninitialized JPEG XL image decoder.

    JxlImageBuilder::default

    JxlImageBuilder::force_wide_buffers

    fn JxlImageBuilder::force_wide_buffers(self : JxlImageBuilder, force_wide_buffers : Bool) -> JxlImageBuilder

    Force 32-bit Modular buffers when decoding.

    JxlImageBuilder::read

    Consumes the builder, and creates a JPEG XL image decoder by reading the whole image from data (upstream read, with the reader's contents given at once).

    LoadResult

    pub(all) enum LoadResult {
    Done(Int)
    NeedMoreData
    NoMoreFrames
    } derive(
    Debug
    )

    The result of loading the keyframe.

    PixelFormat

    pub(all) enum PixelFormat {
    Gray
    Graya
    Rgb
    Rgba
    Cmyk
    Cmyka
    } derive(Eq, Hash,
    Debug
    )

    Pixel format of the rendered image.

    PixelFormat::channels

    fn PixelFormat::channels(self : PixelFormat) -> Int

    Returns the number of channels of the image.

    PixelFormat::has_alpha

    fn PixelFormat::has_alpha(self : PixelFormat) -> Bool

    Returns whether the image has an alpha channel.

    PixelFormat::has_black

    fn PixelFormat::has_black(self : PixelFormat) -> Bool

    Returns whether the image has a black channel.

    PixelFormat::is_grayscale

    fn PixelFormat::is_grayscale(self : PixelFormat) -> Bool

    Returns whether the image is grayscale.

    RawExif

    pub struct RawExif {
    // private fields
    }

    Raw Exif metadata.

    RawExif::payload

    fn RawExif::payload(self : RawExif) -> BytesView

    Returns the payload.

    RawExif::tiff_header_offset

    fn RawExif::tiff_header_offset(self : RawExif) -> UInt

    Returns the offset of TIFF header within the payload.

    Render

    pub struct Render {
    // private fields
    }

    The result of rendering a keyframe.

    Render::color_channels

    Returns the color channels.

    Orientation is not applied.

    Render::duration

    fn Render::duration(self : Render) -> UInt

    Returns how many ticks this frame is presented.

    Render::extra_channels

    Returns the extra channels, potentially including alpha and black channels.

    Orientation is not applied.

    Render::image_all_channels

    fn Render::image_all_channels(self : Render) -> FrameBuffer

    Creates a buffer with interleaved channels, with orientation applied.

    All extra channels are included. Use stream if only color, black and alpha channels are needed.

    Render::image_planar

    fn Render::image_planar(self : Render) -> Array[FrameBuffer]

    Creates a separate buffer by channel, with orientation applied.

    All extra channels are included.

    Render::keyframe_index

    fn Render::keyframe_index(self : Render) -> Int

    Returns the keyframe index.

    Render::name

    fn Render::name(self : Render) -> String

    Returns the name of the frame.

    Render::orientation

    fn Render::orientation(self : Render) -> Int

    Returns the orientation of the image.

    Render::stream

    fn Render::stream(self : Render) -> ImageStream

    Creates a stream that writes to a buffer.

    The stream will include black and alpha channels, if exist, in addition to color channels. Orientation is applied.

    Render::stream_no_alpha

    fn Render::stream_no_alpha(self : Render) -> ImageStream

    Creates a stream that writes to a buffer.

    The stream will include black channels if exist, but not alpha channels. Orientation is applied.

    RenderResult

    pub(all) enum RenderResult {
    Done(Render)
    NeedMoreData
    NoMoreFrames
    }

    The result of loading and rendering the keyframe.

    SampleKind

    pub(all) enum SampleKind {
    F32
    U16
    U8
    } derive(Eq,
    Debug
    )

    Output sample type of ImageStream::write_to_buffer (upstream sealed trait FrameBufferSample, implemented by f32, u16 and u8).

    UninitializedJxlImage

    pub struct UninitializedJxlImage {
    // private fields
    }

    Empty, uninitialized JPEG XL image.

    let mut uninit_image = JxlImage::builder().build_uninit() let image = for { let buf = read_bytes() uninit_image.feed_bytes(buf) |> ignore match uninit_image.try_init() { NeedMoreData(uninit) => uninit_image = uninit Initialized(image) => break image } }

    UninitializedJxlImage::feed_bytes

    fn UninitializedJxlImage::feed_bytes(self : UninitializedJxlImage, buf : BytesView) -> Int raise
    JxlError

    Feeds more data into the decoder.

    Returns total consumed bytes from the buffer.

    UninitializedJxlImage::reader

    Returns the internal reader.

    UninitializedJxlImage::try_init

    Try to initialize an image with the data fed into so far.

    Returns
    • Initialized(_) if the initialization was successful,
    • NeedMoreData(_) if the data was not enough, and
    • raises if there was a decode error during the initialization, meaning invalid bitstream was given.

    decode_jxl

    fn decode_jxl(b : Bytes) -> (Int, Int, FixedArray[Byte])?

    The image's width, height and RGBA bytes (8 bits per sample, straight alpha, rows top to bottom, 4 bytes a pixel, sRGB), None where it is not a JPEG XL image this reads.

    The first keyframe of an animation; turned as its orientation says; grayscale spread to R, G and B; alpha 255 where the image has none, premultiplied alpha undone; colours converted to sRGB (CMYK and ICC-profiled images through the CMS).

    is_jxl

    fn is_jxl(b : Bytes) -> Bool

    Whether b starts as a JPEG XL file does: a bare codestream (FF 0A) or an ISOBMFF container whose first box is the JXL signature box.

    jxl_size

    fn jxl_size(b : Bytes) -> (Int, Int)?

    The width and height a JPEG XL image is shown at (orientation applied), from its SizeHeader and ImageMetadata, or None where b is not JPEG XL or is cut off before them. Reads only the first few bytes of the codestream.

    sample_f32_to_u16

    fn sample_f32_to_u16(val : Float) -> Int

    f32 as u16 conversion of (val * 65535 + 0.5).clamp(0, 65535).

    sample_f32_to_u8

    fn sample_f32_to_u8(val : Float) -> Int

    f32 as u8 conversion of (val * 255 + 0.5).clamp(0, 255).