Fliiifenleger

Optional Software

• libjxl: To enable support for JPEG XL (.jxl) images, the native libjxl library must be installed on your system. This is required for the JxlImageSource to function correctly.
  • On Debian/Ubuntu: sudo apt-get install libjxl-dev or sudo apt-get install libjxl-tools
  • On Alpine Linux: apk add libjxl
  • On macOS (with Homebrew): brew install jpeg-xl

Global Options

These options can be used with any command.

generate

Generates IIIF tiles from one or more local image files.

Usage: fliiifenleger generate [OPTIONS] <file1> <file2> ...

Example:

java -jar cli/target/fliiifenleger-cli.jar generate --output ./my-iiif-images /path/to/image1.jpg /path/to/image2.png

validate

Validates a IIIF endpoint by reassembling the image from its tiles and saving it to a file.

HDR endpoints are detected automatically from the profile constant in info.json (the https://christianmahnke.de/iiif/hdr/ feature/service the tiler writes): their tiles are gain-map JPEGs, so the reassembled output is a full-resolution UltraHDR JPEG (primary + stitched gain map + metadata), not a tone-mapped SDR image. Non-HDR endpoints reassemble to the plain SDR image as before. --format applies to SDR output; HDR output is always JPEG (any --format value is ignored with a warning).

Any tile that cannot be fetched or decoded is now reported and fails the validation (exit code 1) instead of silently producing a black region.

Usage: fliiifenleger validate [OPTIONS] <info.json-url>

Example:

java -jar cli/target/fliiifenleger-cli.jar validate --output reassembled.jpg https://example.com/iiif/2/my-image/info.json

info

Displays information about available components. Sources, sinks and validators are discovered via ServiceLoader (@AutoService), so every module on the classpath appears automatically.

Usage: java -jar cli/target/fliiifenleger-cli.jar info <subcommand>

• list-sources [-v]: Lists all available image source implementations.
• list-sinks [-v]: Lists all available image sink implementations.
• list-validators [-v]: Lists all available info.json validators.
• describe-source <name>: Shows the description and available options of one image source (set via --source-opt key=value).
• describe-sink <name>: Shows the description and available options of one image sink (set via --sink-opt key=value).
• describe-validator <name>: Shows the description and available options of one validator.

With -v/--verbose, the list commands also print each entry's description and options. Every option is described by name and description, plus its default value, required flag and type hint (e.g. string, int, uri, path).

Examples:

java -jar cli/target/fliiifenleger-cli.jar info list-sources
java -jar cli/target/fliiifenleger-cli.jar info describe-source stacked
java -jar cli/target/fliiifenleger-cli.jar info describe-sink c2pa

runtime

Shows the used WASM runtime and JXL backend: JVM version, whether this is a GraalVM native image, Chicory/GraalWasm availability, the effective -Dwasm.engine/-Dwasm.lanes selection, the imageio-jxl reader and the jxl-wasm module presence, and which jxl source is registered.

Example:

java -jar cli/target/fliiifenleger-cli.jar runtime

info.json validation

generate --validate-info validates each generated info.json against the JSON Schema for the requested IIIF version and fails the generation on mismatch. validate checks the remote info.json against its schema (--schema auto|2|3|off, default auto) before reassembling the tiles.

The base schemas live in core/src/main/resources/schema/: image-api-2-info.json and image-api-3-info.json (JSON Schema draft 2020-12). They cover the required IIIF properties; service extensions ship their own schema fragments in their modules (jc2pa/src/main/resources/schema/c2pa-service.json, ultrahdr/src/main/resources/schema/hdr-service.json), which the validator composes with the V3 base schema via allOf (discovered through the ServiceExtension SPI, so core never names an extension). The V3 fragments constrain only service entries claiming their profile (https://christianmahnke.de/iiif/c2pa/, with optional trustAnchor, and https://christianmahnke.de/iiif/hdr/); the V2 schema models extensions as plain URIs in the embedded profile supports list and rejects namespaced properties such as trustAnchor. The matching JSON-LD contexts live next to the fragments (jc2pa / ultrahdr src/main/resources/context/). Validation is implemented in InfoJsonValidator (core), which composes the JSON Schema check with every discovered Validator: core ships the generic IIIF rules (a V3 @context array must end with the IIIF context; Image API 2 rejects namespaced properties and enforces the profile level), while the jc2pa module validates C2PA service entries (context presence, trustAnchor URI) and the ultrahdr module validates HDR gain-map service entries (completeness, context presence). On a core-only classpath (no extension modules), extension service entries validate as generic services.

HDR content transport

BufferedImage stays the pixel type of the ImageSource / TileSink interfaces, but it can only carry 8-bit SDR (java.awt cannot express PQ/HLG transfers, and every imaging library reads image contents as SDR). Full-range HDR therefore travels alongside, never inside, the image:

• Sources that can provide HDR implement the HdrSource capability (getHdrFrame() → interleaved f32 pixels plus transfer/primaries, e.g. the jxl-wasm bridge decoding JXL PQ/HLG codestreams, or the ultrahdr source exposing its split gain map at native resolution inside the frame). A null frame means no HDR content.
• Sinks opt in with supportsHdr() (default false); the Tiler materializes and attaches the hdr.* metadata keys only then, so unaware sinks neither see nor pay for HDR — plain SDR tiles, byte for byte as before. The attached frame is shared by reference across a source image's tile tasks (built once, read-only).
• The ultrahdr sink consumes the frame per tile: carried gain maps are cropped to the tile region (see above); true-HDR frames without one get a gain map derived in-sink (HdrGainMapDeriver: linearize per transfer with a 100-nit diffuse anchor, per-channel ratio against the delegate-rendered SDR base, log-domain normalize, quarter-resolution RGB plane, synthesized ISO metadata following the ultrahdr-core convention) before WASM assembly. Gain maps are therefore an UltraHDR-sink-only concern — transparent to sources.
• getImage() always yields the SDR rendition (clamp + sRGB, TwelveMonkeys-style), which is also what validation and reassembly operate on.

There is no standard Java HDR raster type to adopt instead (BoofCV, ImgLib2 and OpenCV were evaluated: SDR-range conventions, generic overkill, and JNI natives respectively — the latter unshippable in the GraalVM-native build this transport targets).

Signing with your own certificate

java -jar cli/target/fliiifenleger-cli.jar generate \
  --sink c2pa \
  --sink-opt cert=chain.pem \
  --sink-opt key=key.pem \
  --sink-opt alg=es256 \
  -o ./signed-iiif /path/to/image.jpg

Requirements for cert / key (checked at signing time — a mismatch fails with the certificate is invalid):

• cert is a PEM file holding the certificate chain with the end-entity certificate first, followed by the intermediate/CA certificate(s).
• key is the PEM-encoded (PKCS#8) private key matching the end-entity certificate.
• alg must match the key type: es256 for EC P-256 keys (default), ps256 for RSA keys (at least 2048 bit), ed25519 for Ed25519 keys.
• The end-entity certificate must be X.509v3, currently valid, carry the digitalSignature key usage and an allowed extended key usage (e.g. emailProtection), plus subject/authority key identifiers, and its subject must contain an organization (O) attribute — without it, validation misleadingly reports claimSignature.mismatch. A bare self-signed certificate without this structure is rejected.
• tsa optionally adds a trusted timestamp (timestamp authority URL).

A throwaway test chain with openssl (EC P-256, test use only — production credentials come from a CA on the C2PA trust list):

# Certificate authority (self-signed).
openssl ecparam -name prime256v1 -genkey -noout -out ca-key.pem
openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 365 \
  -subj "/CN=fliiifenleger-test-ca/O=fliiifenleger-test" \
  -addext "basicConstraints=critical,CA:true" \
  -addext "keyUsage=critical,keyCertSign,digitalSignature,cRLSign" \
  -addext "subjectKeyIdentifier=hash" \
  -addext "authorityKeyIdentifier=keyid:always" \
  -out ca-cert.pem

# End-entity certificate, signed by the CA (key converted to PKCS#8,
# the format the signer expects).
openssl ecparam -name prime256v1 -genkey -noout -out ee-sec1.pem
openssl pkcs8 -topk8 -nocrypt -in ee-sec1.pem -out key.pem
openssl req -new -key key.pem -subj "/CN=fliiifenleger-test/O=fliiifenleger-test" -out ee.csr
printf "basicConstraints=critical,CA:false\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=emailProtection\nsubjectKeyIdentifier=hash\nauthorityKeyIdentifier=keyid,issuer\n" > ee-ext.cnf
openssl x509 -req -in ee.csr -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial \
  -days 365 -sha256 -extfile ee-ext.cnf -out ee-cert.pem

# Chain file: end-entity first, then CA.
cat ee-cert.pem ca-cert.pem > chain.pem

Then check the result — a single tile with the standalone jar, or a whole endpoint with validate --check-c2pa:

java -jar jc2pa/target/jc2pa-*-standalone.jar validate image/jpeg <tile>.jpg
java -jar cli/target/fliiifenleger-cli.jar validate --check-c2pa \
  -o reassembled.jpg https://example.com/iiif/2/my-image/info.json

Self-signed test chains validate structurally (the manifest is present and parses) but not against the C2PA trust list. The C2paSignWithKeysRoundTripTest in the jc2pa module demonstrates the same flow programmatically (runtime-generated CA + end-entity, signWithKeys, read back with C2paReader).

To validate against your own anchor instead of just checking presence, pass its PEM bundle — every tile must then report Trusted (exit code 2 otherwise):

java -jar cli/target/fliiifenleger-cli.jar validate --check-c2pa \
  --trust-anchor chain.pem \
  -o reassembled.jpg https://example.com/iiif/2/my-image/info.json

Anchors are process-global in the WASM module (like all c2pa-rs settings): the CLI installs them for the validation run and clears them afterwards, so repeated validations in one JVM never leak trust between runs. C2paTrustAnchorTest / ValidateTrustAnchorTest cover the trusted, foreign-anchor, and malformed-bundle cases.

Technical notes:

• The C2PA functionality lives in the jc2pa module: the Rust c2pa-rs SDK is compiled to a WebAssembly module (wasm32-wasip1) and executed on the pure-JVM Chicory runtime — no native dependencies.
• On a GraalVM runtime, --sink-opt runtime=graalvm (or -Dwasm.engine=graalvm) switches to GraalWasm; auto (default) picks it only when running on a GraalVM with the polyglot artifacts present and falls back to Chicory otherwise. The same option exists on the ultrahdr side (--source-opt runtime=… / --sink-opt runtime=…).
• All WASM access is routed through a lane pool with strict thread-instance affinity (see Parallel WASM lanes); a single lane behaves exactly like the previous dedicated signing thread.
• Known limitation: signing assets that already carry a C2PA manifest store can trip a Chicory interpreter edge case (fresh tiles are unaffected).
• The jc2pa module is self-contained: jc2pa-*-standalone.jar embeds the compiled WASM module and offers the same operations from the command line (version, read, label, manifest, validate, sign, sign-ephemeral).

Parallel WASM lanes

WASM work (C2PA signing, UltraHDR assembly) runs on one lane per available processor capped at 4 by default; threads=1 (or -Dwasm.lanes=1) selects serial execution:

java -jar cli/target/fliiifenleger-cli.jar generate \
  --sink c2pa \
  --sink-opt threads=2 \
  -o ./signed-iiif /path/to/image.jpg

--sink-opt threads=N exists on both the c2pa and ultrahdr sinks; -Dwasm.lanes=N sets the default when unset. Each lane pairs one interpreter instance with its own thread (instances are fully isolated, so manifests can't leak across tiles); requests are clamped to the available processors (and to 2 lanes for GraalWasm).

Tiles themselves are generated per-tile tasks over a worker pool sized by --jobs/-j (-Dtiler.workers, default: available processors), so slow tiles no longer pin a whole scale level behind them.

Measured on a 10-core laptop (page011.jpg, 105 tiles, ephemeral C2PA signatures): serial (threads=1) ~26s, threads=2 ~14–19s at near-equal CPU, default (4 lanes here) ~12–13s. Isolated signing throughput scales near-linearly: 12 distinct 512px tiles 2.6s → 0.7s (3.8×), one 1.4MB full-size tile 20.4s → 5.7s (3.6×). Your mileage varies with tile-size mix (a few huge tiles dominate the tail) and hardware; beyond ~4 lanes oversubscription burns CPU and memory without wall gains on this machine (6 lanes: ~13.4s at +38% CPU), hence the default cap — raise it explicitly for server hardware.

Chaining Image Processors with stacked

The stacked source type allows you to chain multiple image sources and manipulators together. This is powerful for applying a sequence of operations, such as applying a filter to a base image before tiling.

Configuration is best done via a YAML file, which you pass to the generate command using the --source-opt option.

Usage:

java -jar cli/target/fliiifenleger-cli.jar generate \
  -s stacked \
  --source-opt config=path/to/your/config.yaml

sources:
  - type: default
    path: /path/to/your/image.jpg
  - type: filter
    options:
      type: sepia

Re-tiling a remote IIIF image (iiif)

The iiif source fetches an existing IIIF image by its info.json URL and re-tiles it locally — useful to mirror or re-generate tiles from a remote endpoint:

java -jar cli/target/fliiifenleger-cli.jar generate \
  --source iiif -o ./my-iiif \
  https://example.org/iiif/2/my-image/info.json

Standalone filter source (filter)

The filters documented below can also be used directly as an image source instead of inside a stacked chain:

java -jar cli/target/fliiifenleger-cli.jar generate \
  --source filter --source-opt type=sepia \
  -o ./filtered /path/to/image.jpg

Available Filters

The filter source type can be used within a stacked configuration to apply various image effects.

sources:
  - type: default
    path: /path/to/your/image.jpg
  - type: filter
    options:
      type: blur
      blurRadius: 5

Changing the project version

The version lives literally in the parent pom plus the <parent><version> reference of every module. The versions-maven-plugin updates all of them in one pass:

mvn --batch-mode org.codehaus.mojo:versions-maven-plugin:2.17.1:set -DnewVersion=0.5.0-SNAPSHOT -DgenerateBackupPoms=false

This is the same mechanism the release.yml workflow uses (with the tag version as -DnewVersion) before testing and deploying a release. Snapshot deploys on main need no version change — they publish the current 0.x-SNAPSHOT artifacts.

Re-running a release for the same version works out of the box: GitHub Packages treats release versions as immutable (re-deploying returns 409 Conflict), so release.yml deletes previously published package versions of the release before deploying.

Homebrew

End-user install once a release is published:

brew tap cmahnke/fliiifenleger
brew install fliiifenleger
fliiifenleger --version

The formula installs the shaded CLI JAR into libexec with a wrapper pinned to openjdk@21 (matching the release 21 bytecode target) that keeps --enable-native-access=ALL-UNNAMED for the JXL imageio plugin, and depends on jpeg-xl so the jxl image source works without extra setup. A direct (non-Homebrew) install is the attached fliiifenleger.tar.gz: extract it anywhere and run bin/fliiifenleger (requires Java 21+ on the PATH).

Each v* release then updates Formula/fliiifenleger.rb in the tap automatically (checksum + URL); no per-release manual steps.

Native binaries

mvn -Pnative package (requires GraalVM 25.3+ as the build JDK — the enforcer fails fast otherwise, and builder/polyglot versions must match the pinned 25.3.x artifacts) produces a self-contained cli/target/fliiifenleger binary: no JDK needed at runtime, JXL decodes through the bundled jxl-wasm module (functional but ~5× slower than the native lib), and Chicory is excluded from the image entirely.

CI builds Linux amd64/arm64 binaries on every v* tag (see above); macOS is served by the JVM artifacts (Homebrew formula), which work on both Apple Silicon and Intel Macs.

Native Docker image

Dockerfile.native ships the GraalVM native binary instead of the JVM (see docker.yml, tags with a -native suffix):

docker build -f Dockerfile.native -t fliiifenleger:native .
docker run --rm fliiifenleger:native --version
docker run --rm fliiifenleger:native runtime

Like the local -Pnative build it needs no JDK and no system libjxl at runtime (JXL decodes via the bundled jxl-wasm module, WASM runs on GraalWasm). The binary is linked against musl (-H:UseLibC=musl, built with the GraalVM -muslib toolchain image — fully-static --static fails this Truffle/GraalWasm workload at image init time), so the final image is a bare alpine:3 with just the binary — no JDK, no glibc. The regular Dockerfile stays JVM-based and remains the default.