tangkii/jxs

Purpose and Build Surface

This is the ISO/IEC 21122 JPEG XS reference implementation: a C library plus command-line encoder/decoder used as a conformance and validation anchor. CMake builds the core library and programs on Linux, Windows, and macOS. Top-level build orchestration is in CMakeLists.txt, with library and executable targets defined by libjxs/CMakeLists.txt and programs/CMakeLists.txt.

Public API and Core Codec Boundary

libjxs owns JPEG XS codestream generation and reconstruction. Its public integration boundary is libjxs/public/libjxs.h; internal codec orchestration is split between libjxs/src/xs_enc.c and libjxs/src/xs_dec.c. Callers provide image/configuration data to the library and receive a JPEG XS codestream or decoded image representation.

Encoder Pipeline

Encoding transforms source image samples through configurable coding stages: optional nonlinear and multi-component transforms, wavelet decomposition, quantization, precinct formation, rate allocation, and entropy/bit packing. Key stages are implemented in:

• Transforms: libjxs/src/nlt.c, libjxs/src/mct.c, libjxs/src/dwt.c

• Coefficient coding: libjxs/src/quant.c, libjxs/src/gcli_methods.c, libjxs/src/bitpacking.c

• Precinct/codestream assembly: libjxs/src/precinct.c, libjxs/src/packing.c, libjxs/src/xs_enc.c

Rate Control and Allocation

The encoder’s primary optimization boundary is rate control: configuration may specify target bits-per-pixel or total codestream size, while rate-control modules assign budgets across precincts, subbands, and coding data. This layer is centered in libjxs/src/rate_control.c, libjxs/src/precinct_budget.c, and libjxs/src/data_budget.c. Gain/priority choices and subband weighting influence allocation through libjxs/src/sb_weighting.c and the static gain definitions in libjxs/src/xs_gains.h.

Decoder and Codestream Syntax

The decoder parses JPEG XS markers and packed precinct payloads, reconstructs quantized coefficients, applies inverse transforms, and emits image samples. Syntax-marker handling is isolated in libjxs/src/xs_markers.c; packed payload interpretation and precinct reconstruction use libjxs/src/packing.c and libjxs/src/precinct.c; top-level decode control is libjxs/src/xs_dec.c. This forms the trust boundary for externally supplied .jxs data.

Configuration and Validation

A shared configuration model drives both encoding and decoder configuration dumps. It parses the semicolon-separated CLI/API syntax, resolves profiles/levels/defaults, and validates constraints before codec execution. The defining paths are libjxs/src/xs_config.h, libjxs/src/xs_config.c, and libjxs/src/xs_config_parser.c.

CLI, Image I/O, and Runtime Dependencies

jxs_encoder and jxs_decoder are native command-line entry points in programs/xs_enc_main.c and programs/xs_dec_main.c; a reduced encoder variant is programs/xs_enc_main_lite.c. The programs adapt files to/from library image buffers via programs/image_open.c, programs/file_io.c, and format converters under programs/converters/. No network services, databases, or managed infrastructure are indicated; runtime dependencies are the host C runtime, filesystem, and CMake-supported C toolchains.