How john-nagle/jpeg2000-decoder works
Purpose and Deliverables
This Rust project provides JPEG 2000 image fetching and decoding, primarily for Second Life/Open Simulator assets. It builds both a reusable library and a command-line executable that accepts local files or URLs and writes PNG output.
Entry Points
• CLI executable: src/bin/jpeg2000_decoder/main.rs
• Library root and public module surface: src/lib/lib.rs
• Cargo package/build definition: Cargo.toml
The executable is a thin consumer of the library rather than an independent decoder implementation.
CLI Orchestration
src/bin/jpeg2000_decoder/main.rs parses the input path/URL, output path, optional maximum pixel dimension, HTTP user-agent, and verbosity options. It coordinates fetch/decode work and emits the decoded image as PNG; PNG is the only documented output format.
The primary control flow is:
1. Receive -i/--input and -o/--output.
2. Obtain JPEG 2000 bytes from a local path or remote URL.
3. Decode, potentially at reduced resolution based on --maxsize.
4. Serialize decoded pixels to the requested PNG file.
Fetch Boundary
src/lib/fetch.rs owns input acquisition and separates caller-facing decoding from source transport. Its role is to support both filesystem inputs and HTTP URL inputs, including propagation of the CLI-configured user agent.
This is the principal external-service boundary: remote image retrieval over HTTP. Local file input follows the same downstream byte-oriented decode path.
JPEG 2000 Decode Pipeline
src/lib/decode.rs contains the image decoding stage, backed by OpenJPEG 2000 per the project description. It transforms fetched JPEG 2000 data into a usable decoded image representation and is responsible for resolution reduction needed to honor a maximum output dimension.
The decode layer is the native-code/image-codec boundary and should remain isolated from CLI argument handling and transport concerns.
Priority/Progressive Work Queue
src/lib/pvqueue.rs is an architecture-level scheduling component, likely supporting prioritized or progressive decode/fetch work. Its presence aligns with JPEG 2000’s scalable-resolution use case and the project’s ability to request reduced output sizes.
It should be treated as an internal coordination primitive, not as part of the executable interface.
Library Composition and Runtime
src/lib/lib.rs composes and exports the library modules:
• Fetching: src/lib/fetch.rs
• Decoding: src/lib/decode.rs
• Queueing/coordination: src/lib/pvqueue.rs
The runtime is a Rust native binary/library using the OpenJPEG codec dependency and HTTP networking for URL inputs. No server, browser, or persistent datastore is indicated. Sample asset-related input is present at samples/bugislanduuidlist.txt, consistent with the virtual-world asset focus.
Main entry points: fetch.rs Fetch · lib.rs Library surface · decode.rs Decode · main.rs jpeg2000_decoder
Components 12
CLI
- jpeg2000_decoder · Accepts input, output, max size, user agent, and verbosity options.
src/bin/jpeg2000_decoder/main.rs - PNG file · The documented output format.
Decoder Library
- Library surface · Composes and exports fetch, decode, and queue modules.
src/lib/lib.rs - Fetch · Normalizes local files and HTTP responses into JPEG 2000 bytes.
src/lib/fetch.rs - Decode · Decodes image bytes and applies requested resolution reduction.
src/lib/decode.rs - Priority queue · Internal scheduling primitive for prioritized or progressive work.
src/lib/pvqueue.rs
Input & Native Boundaries
- Local JPEG 2000
- Remote image URL
- HTTP service · Remote asset retrieval boundary; receives configured user agent.
- OpenJPEG · Native JPEG 2000 codec boundary.
Other components
- Cargo package
Cargo.toml - Asset UUID sample · Virtual-world asset-related sample data.
samples/bugislanduuidlist.txt
Connections 15
- Cargo package → jpeg2000_decoder: builds
- Cargo package → Library surface: builds
- jpeg2000_decoder → Library surface: uses
- jpeg2000_decoder → PNG file: writes decoded pixels
- Library surface → Fetch: exports
- Library surface → Decode: exports
- Library surface → Priority queue: exports
- Local JPEG 2000 → Fetch: reads bytes
- Remote image URL → Fetch: requests
- Fetch → HTTP service: HTTP with user agent
- Fetch → Decode: JPEG 2000 bytes
- Priority queue → Fetch: coordinates work
- Priority queue → Decode: coordinates work
- Decode → OpenJPEG: uses codec
- Asset UUID sample → Remote image URL: asset reference context