# tangkii/jxs architecture

> Architecture diagram of the GitHub repository tangkii/jxs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tangkii/jxs
- Repository: https://github.com/tangkii/jxs

## Overview

#### 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.

Main entry points: [`libjxs/public/libjxs.h`](https://github.com/tangkii/jxs/blob/main/libjxs/public/libjxs.h) (Public libjxs API), [`libjxs/src/xs_enc.c`](https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_enc.c) (Encoder orchestration), [`programs/CMakeLists.txt`](https://github.com/tangkii/jxs/blob/main/programs/CMakeLists.txt) (Program targets), [`programs/xs_enc_main.c`](https://github.com/tangkii/jxs/blob/main/programs/xs_enc_main.c) (jxs_encoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_root_cmake["Top-level CMake<br/>build orchestration<br/>[CMakeLists.txt]"]
  node_lib_cmake["Library target<br/>CMake target<br/>[CMakeLists.txt]"]
  node_programs_cmake["Program targets<br/>CMake target<br/>[CMakeLists.txt]"]
end

subgraph group_cli["CLI and I/O"]
  node_encoder_cli["jxs_encoder<br/>CLI entry point<br/>[xs_enc_main.c]"]
  node_decoder_cli["jxs_decoder<br/>CLI entry point<br/>[xs_dec_main.c]"]
  node_image_io["Image file adapter<br/>image I/O<br/>[image_open.c]"]
end

subgraph group_codec["libjxs codec"]
  node_public_api{{"Public libjxs API<br/>C API<br/>[libjxs.h]"}}
  node_config["Configuration validation<br/>config model<br/>[xs_config.c]"]
end

subgraph group_encoder["Encoder pipeline"]
  node_encoder_control["Encoder orchestration<br/>encoder control<br/>[xs_enc.c]"]
  node_transforms["Sample transforms<br/>NLM/MCT/DWT<br/>[dwt.c]"]
  node_coeff_coding["Coefficient coding<br/>quantization and entropy<br/>[quant.c]"]
  node_precinct_assembly["Precinct assembly<br/>codestream packing<br/>[packing.c]"]
  node_rate_control["Rate control<br/>allocation engine<br/>[rate_control.c]"]
end

subgraph group_decoder["Decoder pipeline"]
  node_decoder_control["Decoder orchestration<br/>decoder control<br/>[xs_dec.c]"]
  node_marker_parser{{"Marker parser<br/>codestream syntax<br/>[xs_markers.c]"}}
  node_precinct_reconstruction["Precinct reconstruction<br/>payload decoding<br/>[precinct.c]"]
  node_inverse_transforms["Inverse transforms<br/>sample reconstruction<br/>[mct.c]"]
end

node_codestream["JPEG XS codestream<br/>binary .jxs data"]

node_root_cmake -->|"includes"| node_lib_cmake
node_root_cmake -->|"includes"| node_programs_cmake
node_lib_cmake -->|"builds"| node_public_api
node_programs_cmake -->|"builds"| node_encoder_cli
node_programs_cmake -->|"builds"| node_decoder_cli
node_encoder_cli -->|"reads source image"| node_image_io
node_encoder_cli -->|"calls"| node_public_api
node_decoder_cli -->|"calls"| node_public_api
node_decoder_cli -->|"writes image"| node_image_io
node_public_api -->|"validates settings"| node_config
node_public_api -->|"encodes"| node_encoder_control
node_public_api -->|"decodes"| node_decoder_control
node_config -->|"codec parameters"| node_encoder_control
node_encoder_control -->|"transforms samples"| node_transforms
node_transforms -->|"wavelet coefficients"| node_coeff_coding
node_encoder_control -->|"target budget"| node_rate_control
node_rate_control -->|"coding allocation"| node_coeff_coding
node_coeff_coding -->|"coded data"| node_precinct_assembly
node_precinct_assembly -->|"emits"| node_codestream
node_codestream -->|"untrusted input"| node_marker_parser
node_marker_parser -->|"syntax metadata"| node_decoder_control
node_decoder_control -->|"decodes payloads"| node_precinct_reconstruction
node_precinct_reconstruction -->|"quantized coefficients"| node_inverse_transforms
node_inverse_transforms -->|"output samples"| node_image_io

click node_root_cmake "https://github.com/tangkii/jxs/blob/main/CMakeLists.txt"
click node_lib_cmake "https://github.com/tangkii/jxs/blob/main/libjxs/CMakeLists.txt"
click node_programs_cmake "https://github.com/tangkii/jxs/blob/main/programs/CMakeLists.txt"
click node_encoder_cli "https://github.com/tangkii/jxs/blob/main/programs/xs_enc_main.c"
click node_decoder_cli "https://github.com/tangkii/jxs/blob/main/programs/xs_dec_main.c"
click node_image_io "https://github.com/tangkii/jxs/blob/main/programs/image_open.c"
click node_public_api "https://github.com/tangkii/jxs/blob/main/libjxs/public/libjxs.h"
click node_config "https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_config.c"
click node_encoder_control "https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_enc.c"
click node_transforms "https://github.com/tangkii/jxs/blob/main/libjxs/src/dwt.c"
click node_coeff_coding "https://github.com/tangkii/jxs/blob/main/libjxs/src/quant.c"
click node_precinct_assembly "https://github.com/tangkii/jxs/blob/main/libjxs/src/packing.c"
click node_rate_control "https://github.com/tangkii/jxs/blob/main/libjxs/src/rate_control.c"
click node_decoder_control "https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_dec.c"
click node_marker_parser "https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_markers.c"
click node_precinct_reconstruction "https://github.com/tangkii/jxs/blob/main/libjxs/src/precinct.c"
click node_inverse_transforms "https://github.com/tangkii/jxs/blob/main/libjxs/src/mct.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_cmake,node_lib_cmake,node_programs_cmake toneBlue
class node_encoder_cli,node_decoder_cli,node_image_io toneAmber
class node_public_api,node_config toneMint
class node_encoder_control,node_transforms,node_coeff_coding,node_precinct_assembly,node_rate_control toneRose
class node_decoder_control,node_marker_parser,node_precinct_reconstruction,node_inverse_transforms toneIndigo
class node_codestream toneNeutral
```

## Components

### Build

- [Top-level CMake](https://github.com/tangkii/jxs/blob/main/CMakeLists.txt): build orchestration · `CMakeLists.txt`
- [Library target](https://github.com/tangkii/jxs/blob/main/libjxs/CMakeLists.txt): CMake target · `libjxs/CMakeLists.txt`
- [Program targets](https://github.com/tangkii/jxs/blob/main/programs/CMakeLists.txt): CMake target · `programs/CMakeLists.txt`

### CLI and I/O

- [jxs_encoder](https://github.com/tangkii/jxs/blob/main/programs/xs_enc_main.c): CLI entry point · `programs/xs_enc_main.c`
- [jxs_decoder](https://github.com/tangkii/jxs/blob/main/programs/xs_dec_main.c): CLI entry point · `programs/xs_dec_main.c`
- [Image file adapter](https://github.com/tangkii/jxs/blob/main/programs/image_open.c): image I/O · Reads and writes image buffers through file and format adapters. · `programs/image_open.c`

### libjxs codec

- [Public libjxs API](https://github.com/tangkii/jxs/blob/main/libjxs/public/libjxs.h): C API · Integration boundary for image, configuration, and codestream operations. · `libjxs/public/libjxs.h`
- [Configuration validation](https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_config.c): config model · Parses CLI/API syntax and resolves profiles, levels, defaults, and constraints. · `libjxs/src/xs_config.c`

### Encoder pipeline

- [Encoder orchestration](https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_enc.c): encoder control · `libjxs/src/xs_enc.c`
- [Sample transforms](https://github.com/tangkii/jxs/blob/main/libjxs/src/dwt.c): NLM/MCT/DWT · Applies optional nonlinear and multi-component transforms before wavelet coding. · `libjxs/src/dwt.c`
- [Coefficient coding](https://github.com/tangkii/jxs/blob/main/libjxs/src/quant.c): quantization and entropy · Quantizes coefficients and encodes GCLI and packed bits. · `libjxs/src/quant.c`
- [Precinct assembly](https://github.com/tangkii/jxs/blob/main/libjxs/src/packing.c): codestream packing · Forms precinct payloads and assembles the JPEG XS codestream. · `libjxs/src/packing.c`
- [Rate control](https://github.com/tangkii/jxs/blob/main/libjxs/src/rate_control.c): allocation engine · Allocates target bitrate budgets across precincts, subbands, and coding data. · `libjxs/src/rate_control.c`

### Decoder pipeline

- [Decoder orchestration](https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_dec.c): decoder control · `libjxs/src/xs_dec.c`
- [Marker parser](https://github.com/tangkii/jxs/blob/main/libjxs/src/xs_markers.c): codestream syntax · Trust boundary for externally supplied JPEG XS marker syntax. · `libjxs/src/xs_markers.c`
- [Precinct reconstruction](https://github.com/tangkii/jxs/blob/main/libjxs/src/precinct.c): payload decoding · Interprets packed precinct payloads and reconstructs quantized coefficients. · `libjxs/src/precinct.c`
- [Inverse transforms](https://github.com/tangkii/jxs/blob/main/libjxs/src/mct.c): sample reconstruction · Converts reconstructed coefficients into output image samples. · `libjxs/src/mct.c`

### Other components

- **JPEG XS codestream**: binary .jxs data

## Connections

- Top-level CMake → Library target: includes
- Top-level CMake → Program targets: includes
- Library target → Public libjxs API: builds
- Program targets → jxs_encoder: builds
- Program targets → jxs_decoder: builds
- jxs_encoder → Image file adapter: reads source image
- jxs_encoder → Public libjxs API: calls
- jxs_decoder → Public libjxs API: calls
- jxs_decoder → Image file adapter: writes image
- Public libjxs API → Configuration validation: validates settings
- Public libjxs API → Encoder orchestration: encodes
- Public libjxs API → Decoder orchestration: decodes
- Configuration validation → Encoder orchestration: codec parameters
- Encoder orchestration → Sample transforms: transforms samples
- Sample transforms → Coefficient coding: wavelet coefficients
- Encoder orchestration → Rate control: target budget
- Rate control → Coefficient coding: coding allocation
- Coefficient coding → Precinct assembly: coded data
- Precinct assembly → JPEG XS codestream: emits
- JPEG XS codestream → Marker parser: untrusted input
- Marker parser → Decoder orchestration: syntax metadata
- Decoder orchestration → Precinct reconstruction: decodes payloads
- Precinct reconstruction → Inverse transforms: quantized coefficients
- Inverse transforms → Image file adapter: output samples