oxideav-cli-convert

The engine behind oxideav convert: a flag-driven image/media conversion 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 the conversion flags 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 convert: unknown flag '-<op>' (with a "did you mean?" hint when the token is a close edit of a real flag) 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 follow-up; today it errors with a clear message.

A -- marker ends flag parsing: everything after it is a positional even when it starts with a dash, so files literally named -weird.png are expressible (convert -- -weird.png out.jpg). Empty arguments (usually an unset shell variable) are rejected at parse time with an actionable message.

--help (or IM-style -help) prints a usage synopsis whose flag list is generated from the parser's own flag table — the same table that powers "did you mean?" hints and is sync-tested against the parser — so the help text cannot drift from what actually parses.

Inputs

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

Bracket-suffix page selectors 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 ([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 the single source of truth, so any sibling crate that registers itself (e.g. oxideav_qoi::register, oxideav_dds::register) extends the supported output set automatically, aliasing included (each registering crate owns its extension aliases, e.g. oxideav-mjpeg claims both jpg and jpeg). Extensions nobody registered resolve to no codec: the pipeline then infers per-track (the right answer for video containers like MP4/MKV that don't pin a single codec) or prompts for an explicit -format CODEC.

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 (PDF inputs) or per frame (everything else — image sequences, animations, video; indices are 0-based), substituting the index. Multiple %ds, %s, %x, etc. are rejected with a precise error.

Still-image outputs

When the output resolves to an image encoder (png, ppm/pgm/ pbm/pam, heic, avif, tga, jpg, …) the planner reads the input's container header (no decode) and plans three things the pipeline's generic defaults get wrong:

• Which stream. HEIF / AVIF files with an image-sequence track open as stream 0 = the primary still plus one stream per track. convert seq.heics out.png writes the primary still (with a stderr note); convert seq.heics frame-%03d.png writes every frame of the first image-sequence track. Single-video inputs are unaffected.
• Which encoder input layout. For a plain conversion the encoder gets the accepted layout that loses nothing the source carries (colour, alpha, bit depth) at the fewest bits per pixel — YUV → PNG is RGB (the pipeline default was RGBA with a synthetic opaque alpha: 33% more data through deflate), 10-bit YUV → PNG is 16-bit RGB, and YUV → Netpbm is a real pixmap instead of a thresholded 1-bit bitmap. The Netpbm extensions pick their family (.pbm bilevel, .pgm gray, .ppm colour without alpha; .pam any); -depth 8|16 caps or raises the depth.
• Which codec + options. .jpg resolves to the mjpeg codec; .avif writes AV1 (codec=av1 on the heif encoder), .heic HEVC; --opt KEY=VALUE sets any option the encoder declares, e.g. convert in.png --opt qp=30 --opt tiles=2x2 out.heic or convert in.png --opt quality=90 out.avif.

Encoder options and %d fan-out run through convert's own encode + mux stage (frame_tap), fed decoded frames by the executor through the reserved @out sink; everything else stays a plain pipeline job. Both paths produce byte-identical files for the same encoder settings. OXIDEAV_CONVERT_TIMING=1 prints per-stage timings.

Where the time goes: 12 MP HEIC → PNG

Measured 2026-09-28 on an M4 Max (release build, sips-produced 4032×3024 HEIC from a plasma-fractal PNG; CPU seconds via getrusage so a loaded machine does not skew the split; each stage timed in isolation through the crates' public APIs, then cross-checked with sample on the CLI and OXIDEAV_CONVERT_TIMING=1).

So the "≈ 4.6 s the PNG route spends that the PPM route does not" was the PNG encoder's deflate on a 48.8 MB RGBA buffer, and the PPM route was fast because it wrote a 1-bit thresholded bitmap (the pipeline's default target for the Netpbm encoder), which is also why re-encoding that PPM to PNG took 0.15 s. Nothing in this crate's own code was on the hot path; what this crate could fix was the target layout.

End-to-end CLI CPU time, same sibling-crate snapshot, before → after this round's planning changes:

With the sibling crates at their 2026-09-28 tips (multi-threaded HEVC item decode) the 8-bit HEIC → PNG conversion takes 2.9 s wall / 3.9 s CPU, the 10-bit one 3.8 s wall (2.2 s with -depth 8), and either PPM route well under a second wall.

Remaining cost is owned elsewhere: deflate speed / compression level in oxideav-png (no level option is declared; filter=none is the only knob), the encoder's two full-frame copies (send_frame buffering + video_frame_to_png_image), and the pipeline's own copy into the convert stage.

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.

Planning guarantees

convert separates deciding from doing, and the deciding half carries test-pinned guarantees:

• Routing is pure. route::decide(&plan) classifies every invocation (help / ping / probe / PDF side-channel / 3D→3D / 3D→raster / ico / pipeline) without doing any work; the media-kind × media-kind dispatch matrix is pinned by IO-free unit tests, including precedence (input classification outranks output classification — in.pdf out.ico is PDF-runner business).
• Every emitted job validates. plan_to_job and plan_to_render3d_job run oxideav_pipeline::Job::validate() before returning, so a planner bug is a typed error at plan time.
• Every emitted job is JSON-stable. Serialise → re-parse → re-serialise is byte-identical, and f32 flag values serialise as the decimal the user typed (no f64-widening noise), so planned jobs are storable / replayable / snapshot-testable oxideav run documents. Golden snapshots pin representative argv lines.
• Unplannable input is a typed error, never silence or a panic — 3D input × non-3D/non-raster output, %d templates or --opt on outputs that are not still images, unknown / ill-typed encoder options, empty arguments, malformed value grammars (pinned by an adversarial-argv corpus).

Known follow-ups

• Multi-input (convert in1.pdf in2.pdf out.gif).
• 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).
• -quality / -define on the pipeline route land in the job's codec_params, which the pipeline does not forward to encoders; --opt quality=N is the working channel for encoders that declare a quality option.
• The planned encoder layout applies to plain conversions (and to the frame-tap path); with filter ops in between the pipeline's own running-layout assumption decides.
• Registering PDF as a real Demuxer so oxideav probe / transcode / run see it. Today this side-channels through convert only.

License

MIT. Copyright © 2026 Karpelès Lab Inc.