# john-nagle/jpeg2000-decoder architecture

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

- Interactive diagram: https://gitdiagram.com/john-nagle/jpeg2000-decoder
- Repository: https://github.com/john-nagle/jpeg2000-decoder

## Overview

#### 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: [`src/lib/fetch.rs`](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/fetch.rs) (Fetch), [`src/lib/lib.rs`](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/lib.rs) (Library surface), [`src/lib/decode.rs`](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/decode.rs) (Decode), [`src/bin/jpeg2000_decoder/main.rs`](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/bin/jpeg2000_decoder/main.rs) (jpeg2000_decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_main["jpeg2000_decoder<br/>Rust CLI executable<br/>[main.rs]"]
  node_png_output["PNG file<br/>output artifact"]
end

subgraph group_library["Decoder Library"]
  node_library_root["Library surface<br/>Rust library root<br/>[lib.rs]"]
  node_fetch["Fetch<br/>input acquisition<br/>[fetch.rs]"]
  node_decode["Decode<br/>JPEG 2000 pipeline<br/>[decode.rs]"]
  node_pvqueue["Priority queue<br/>progressive coordination<br/>[pvqueue.rs]"]
end

subgraph group_external["Input &amp; Native Boundaries"]
  node_local_input["Local JPEG 2000<br/>filesystem input"]
  node_remote_url(("Remote image URL<br/>HTTP input"))
  node_http_service(("HTTP service<br/>external service"))
  node_openjpeg{{"OpenJPEG<br/>native codec dependency"}}
end

node_cargo["Cargo package<br/>Rust build definition<br/>[Cargo.toml]"]
node_sample_assets["Asset UUID sample<br/>sample input reference"]

node_cargo -->|"builds"| node_cli_main
node_cargo -->|"builds"| node_library_root
node_cli_main -->|"uses"| node_library_root
node_cli_main -->|"writes decoded pixels"| node_png_output
node_library_root -->|"exports"| node_fetch
node_library_root -->|"exports"| node_decode
node_library_root -->|"exports"| node_pvqueue
node_local_input -->|"reads bytes"| node_fetch
node_remote_url -->|"requests"| node_fetch
node_fetch -->|"HTTP with user agent"| node_http_service
node_fetch -->|"JPEG 2000 bytes"| node_decode
node_pvqueue -.->|"coordinates work"| node_fetch
node_pvqueue -.->|"coordinates work"| node_decode
node_decode -->|"uses codec"| node_openjpeg
node_sample_assets -.->|"asset reference context"| node_remote_url

click node_cargo "https://github.com/john-nagle/jpeg2000-decoder/blob/main/Cargo.toml"
click node_cli_main "https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/bin/jpeg2000_decoder/main.rs"
click node_library_root "https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/lib.rs"
click node_fetch "https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/fetch.rs"
click node_decode "https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/decode.rs"
click node_pvqueue "https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/pvqueue.rs"
click node_sample_assets "https://github.com/john-nagle/jpeg2000-decoder/blob/main/samples/bugislanduuidlist.txt"

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_cli_main,node_png_output toneBlue
class node_library_root,node_fetch,node_decode,node_pvqueue toneAmber
class node_local_input,node_remote_url,node_http_service,node_openjpeg toneMint
class node_cargo,node_sample_assets toneNeutral
```

## Components

### CLI

- [jpeg2000_decoder](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/bin/jpeg2000_decoder/main.rs): Rust CLI executable · Accepts input, output, max size, user agent, and verbosity options. · `src/bin/jpeg2000_decoder/main.rs`
- **PNG file**: output artifact · The documented output format.

### Decoder Library

- [Library surface](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/lib.rs): Rust library root · Composes and exports fetch, decode, and queue modules. · `src/lib/lib.rs`
- [Fetch](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/fetch.rs): input acquisition · Normalizes local files and HTTP responses into JPEG 2000 bytes. · `src/lib/fetch.rs`
- [Decode](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/decode.rs): JPEG 2000 pipeline · Decodes image bytes and applies requested resolution reduction. · `src/lib/decode.rs`
- [Priority queue](https://github.com/john-nagle/jpeg2000-decoder/blob/main/src/lib/pvqueue.rs): progressive coordination · Internal scheduling primitive for prioritized or progressive work. · `src/lib/pvqueue.rs`

### Input & Native Boundaries

- **Local JPEG 2000**: filesystem input
- **Remote image URL**: HTTP input
- **HTTP service**: external service · Remote asset retrieval boundary; receives configured user agent.
- **OpenJPEG**: native codec dependency · Native JPEG 2000 codec boundary.

### Other components

- [Cargo package](https://github.com/john-nagle/jpeg2000-decoder/blob/main/Cargo.toml): Rust build definition · `Cargo.toml`
- [Asset UUID sample](https://github.com/john-nagle/jpeg2000-decoder/blob/main/samples/bugislanduuidlist.txt): sample input reference · Virtual-world asset-related sample data. · `samples/bugislanduuidlist.txt`

## Connections

- 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
