Project documentation

J2K Codec Project

Safe public Rust APIs for JPEG 2000 Part 1 and HTJ2K Part 15 inspection, decode, encode, recode, and coefficient-domain JPEG-to-HTJ2K transcode workflows. CPU is the correctness baseline; CUDA and Apple Metal adapters accelerate supported paths without becoming the public API.

crates.io API docs Repository

Release status: j2k 0.8.0 is published on crates.io; see the release policy for support details.

Why J2K exists

Safe public Rust APIs

The public codec surface is safe Rust. Audited unsafe code is isolated at FFI, GPU integration, architecture-specific SIMD/intrinsic, allocation, and bounded pointer or buffer boundaries; the unsafe audit is authoritative.

Vendor-independent backends

Applications can keep a portable CPU path while routing supported workloads to CUDA or Apple Metal under explicit backend policy.

Permissive integration

The workspace is dual-licensed MIT or Apache-2.0, with benchmark claims gated by reproducible evidence instead of broad speed marketing.

J2K pipeline: JPEG 2000, HTJ2K, and JPEG inputs flow through the j2k crate, which routes to CPU baseline, CUDA, and Metal backends. — One public crate, still-image J2K/JP2 and HTJ2K/JPH surfaces, and three backends. CPU is the baseline; CUDA and Metal accelerate supported shapes.

Support boundary

JPEG 2000 Part 1

Raw J2K/J2C codestream parse, inspect, decode, encode, ROI, progression, tile-part, packet-marker, signed, high-bit, and component-plane surfaces are tracked by the public support matrix.

HTJ2K Part 15

HT cleanup and refinement decode/encode, quality layers, rate behavior, raw HT codestreams, and JPH still-image wrapping are in scope.

Wrappers and limits

JP2 and JPH still-image metadata paths are covered. JPX / JPEG 2000 Part 2 extensions and public speed claims require separate evidence.

Exact row-by-row support status lives in docs/public-support.md. Published benchmark notes live in docs/benchmark-evidence.md; broader adoption reports require pinned external corpora and comparator evidence.

Install

Most applications should start with the public facade crate.

cargo add j2k

CLI smoke tests

Use the CLI for inspection and conservative JPEG-to-HTJ2K transcode checks.

cargo install j2k-cli
j2k inspect input.jp2
j2k transcode input.jpg output.j2k --htj2k --lossless-53

Package map

Crate	Use
`j2k`	Public API for JPEG 2000 Part 1 / HTJ2K Part 15 inspection, decode, encode, recode, JP2, and JPH.
`j2k-cuda`	NVIDIA CUDA adapter for supported JPEG 2000 and HTJ2K backend paths.
`j2k-metal`	Apple Metal adapter for supported macOS GPU paths.
`j2k-transcode`	JPEG-to-HTJ2K coefficient-domain transcode primitives and shared transcode contracts.
`j2k-cli`	Command-line inspection and JPEG-to-HTJ2K transcode smoke tests.

Topic pages

Pure-Rust JPEG 2000 CodecPart 1 decode, encode, JP2/J2K codestreams, and crate selection.
GPU BackendsBackend behavior, CPU fallback, CUDA, Metal, and strict device requests.
CUDA JPEG2000 RustNVIDIA adapter crates and runtime feature boundaries.
Metal JPEG2000 RustApple Metal adapter crates for macOS GPU-backed paths.
HTJ2K RustPart 15 HT block coding, JPH wrapping, recode, and transcode routes.

Backend behavior

CPU output is the correctness baseline. BackendRequest::Auto may return CPU output when a device path is unavailable, unsupported, or not benchmarked for the requested shape.

Explicit CUDA and Metal requests are strict. Unsupported shapes return errors instead of silently changing backend.

Benchmark claims should cite host hardware, operating system, input source, exact command, comparator availability, and comparator versions.