oxideav-cli-convert

The engine behind oxideav convert: an ImageMagick-style CLI that works on images, video, audio, PDFs, vector content, and synthetic sources, implemented on top of oxideav-pipeline.

A one-frame PNG → JPG, a 90-minute MP4 → MKV with -resize, and a multi-page PDF → page-numbered PNG sequence go through related code paths — convert's job is to translate IM-style args into work the rest of the workspace already knows how to do.

Supported ops

The geometry / negate / tonal ops above all wire through to the matching oxideav-image-filter factory on the regular pipeline path (video.rotate, video.sharpen, video.gamma, …). The PDF side-channel keeps its inline pixel_xform implementation for the five geometry / negate ops; the new tonal ops are pipeline-only on the PDF path today (a follow-up will route them through the same inline pre-encode hook).

Anything else reports unsupported: convert: -<op> is not yet implemented and exits cleanly — no silent misbehaviour.

Arg ordering

Ops can appear anywhere — before AND after the input. The first non-flag positional is the input; the last is the output. Multiple inputs (convert in1.pdf in2.pdf out.gif) is a documented round-3 follow-up; today it errors with a clear message.

Inputs

[N] / [N-M] / [A,B,…] page selectors

ImageMagick-style suffix on PDF inputs:

Negative atoms -k resolve to total_pages - k (-1 = last page). Comma lists preserve source order, so [2,0] writes page 2 first then page 0; duplicates are retained (IM convention — [0,0,0] writes the same page three times).

Out-of-range indices error with a precise count: page index 5 out of range (input has 3 page(s)) (or, for a negative atom that overshoots the document, negative page index -5 out of range (input has 3 page(s); valid: -1..=-3)).

Outputs

The output extension chooses the encoder. Three classes drive the routing:

Codec lookup goes through the caller's RuntimeContext — ContainerRegistry::container_for_extension is consulted first, so any sibling crate that registers itself (e.g. oxideav_qoi::register, oxideav_dds::register) extends the supported output set automatically. A small fallback table inside plan_to_job covers the aliasing cases where the canonical encoder name differs from the container name (jpg → mjpeg, wav → pcm_s16le, ogg → vorbis, avif → av1, ico/cur → png).

Printf templates

When the output filename contains a single %[0-9]*d token (e.g. page-%03d.png), convert fans out to one file per selected page, substituting the index. Multiple %ds, %s, %x, etc. are rejected with a precise error.

Routing matrix (3D-asset input)

The mesh3d cargo feature (default-on) wires oxideav-mesh3d plus the format codecs (stl/obj/gltf/usdz) through oxideav-meta's populate_mesh3d_registry helper. With the feature off the side-channel disappears and 3D inputs fall through to the regular pipeline path.

USDZ now round-trips both ways (encoder ships in oxideav-usdz 0.0.1). 3D→raster rendering uses a tiny built-in software rasteriser with flat / wireframe / Gouraud / Phong shading, two debug visualisations (normal-debug, depth-debug), an N×N supersampling anti-aliasing pass (-aa N), and full camera/light/projection/FOV/background controls. Texture sampling and PBR are documented follow-ups.

Raster ops (-rotate, -flip, -crop, -negate, …) ARE honoured on the 3D→raster path — they run after rasterisation, sharing the same pixel-transform chain as the PDF runner. -resize WxH seeds the canvas dimensions before rasterisation (default 1024×1024); -background COLOR paints the canvas (default opaque white).

Per-format encoder option flags

These flags override the encoder choice the registry would make from the output extension alone. They're accepted on every input shape but only honoured when the 3D side-channel fires; the runner errors cleanly if a flag is paired with an extension it doesn't apply to (e.g. -stl-format ascii out.obj).

Routing matrix (PDF input)

Examples

# Image transcode (works exactly like before)
oxideav convert in.png -resize 800x600 -blur 0x2 out.jpg
oxideav convert movie.mp4 -resize 640x360 movie.mkv

# Synthetic sources (xc / gradient / pattern / synth / label / …)
oxideav convert "xc:red" red.png
oxideav convert "label:Hello world" greeting.png
oxideav convert "gradient:red-blue" gradient.png

# PDF rendering — the user's original ask
oxideav convert -density 300 input.pdf -background white \
                -alpha remove -alpha off page-%03d.png

# Single page extraction
oxideav convert input.pdf[0] cover.png
oxideav convert input.pdf[2-5] -density 150 page-%02d.jpg

# PDF → other vector formats (vector preserved, no rasterisation)
oxideav convert input.pdf[0] cover.svg
oxideav convert input.pdf       page-%d.svg

# PDF → smaller PDF (page extraction, vector preserved)
oxideav convert input.pdf[0] just-the-cover.pdf
oxideav convert input.pdf[10-20] excerpt.pdf

# 3D-asset format conversion (mesh3d feature; default-on)
oxideav convert cube.stl cube.obj
oxideav convert model.obj model.gltf
oxideav convert scene.gltf scene.glb
oxideav convert archive.usdz extracted.gltf

# 3D-asset per-format encoder options
oxideav convert cube.stl  -stl-format ascii  cube-readable.stl
oxideav convert model.obj -gltf-format glb   model.gltf  # binary container, .gltf extension
oxideav convert scene.gltf -gltf-format embedded scene.glb # JSON+data URI, .glb extension

--probe (structural inspection)

--probe INPUT decodes the input far enough to extract structural metadata, prints a compact summary to stdout, and skips any output write. Pair with --json for a single-line machine-readable object instead of the default pretty-printed key: value block.

The flag is mutually exclusive with an output positional: oxideav convert --probe in.gltf is the supported shape; passing both --probe and an output errors with a clear message rather than silently picking one.

Embedded font count for PDF / SVG is reported as unknown today — the producer crates don't surface a font-resource census, and counting unique font names from the text-extraction layer would over-count synthetic encoding splits. Documented as a cross-crate follow-up.

--watch paired with --probe re-runs the probe whenever the input file's mtime changes, polling once a second. Each fresh report goes to stdout in the same format the one-shot mode would have used; in --json form each report is its own line so the output is well-formed JSON-lines (convert --probe --json --watch in.png | jq works). The loop runs forever and exits only on Ctrl+C / SIGINT — useful for live-monitoring a render-in-progress.

# Pretty-printed summary (default)
oxideav convert --probe input.pdf
oxideav convert --probe scene.gltf
oxideav convert --probe sound.mp3

# Single-line JSON (machine-readable)
oxideav convert --probe --json input.pdf
oxideav convert --probe --json movie.mp4 | jq .streams[0].codec_id

# Live-monitor a render-in-progress (re-probes on mtime change)
oxideav convert --probe --watch  rendering.png
oxideav convert --probe --json --watch rendering.png | jq -c .file_size_bytes

"Did you mean?" suggestions

Unrecognised extensions on 3D-asset inputs / outputs trigger a Levenshtein-distance hint:

$ oxideav convert model.gtlf out.obj
convert: no 3D decoder registered for input extension '.gtlf' (did you mean '.gltf'?) (known: .stl, .obj, .gltf, .glb, .usdz, .mtl)

The same helper now also fires on unknown-flag errors, so a mistyped op (-quailty, -reszie, --prbe) gets a copy-paste correct suggestion instead of a bare "unknown flag" message:

$ oxideav convert a.png -quailty 90 b.jpg
convert: unknown flag '-quailty' (did you mean '-quality'?)

$ oxideav convert --prbe in.png
convert: unknown flag '--prbe' (did you mean '--probe'?)

The lead the user typed (single vs double dash) is preserved on the suggestion so it works without further edit. Distant tokens (-fnord, --xyzzy) get the bare unknown-flag error with no misleading hint.

The hint fires when the bad extension / flag is within max(2, len/3) edits of one of the supported set; unrelated typos (.png vs the 3D set) get the base error with no misleading suggestion.

Round-3 follow-ups

• Multi-input (convert in1.pdf in2.pdf out.gif) — IM allows it.
• GIF + TIFF raster outputs (need palette quantisation / multi-image TIFF encoder respectively; both are crate-side work).
• -density applied to raster inputs (silently dropped today).
• Registering PDF as a real Demuxer so oxideav probe / transcode / run see it. Today this side-channels through convert only.

Completed previously: [0,2,4] comma-separated and [-1] negative page selectors (round 77).

License

MIT. Copyright © 2026 Karpelès Lab Inc.