Make convert a single-pass transform pipeline that composes container change, codec change, crop, and downsample in one decode→transform→encode pass, while keeping crop / downsample / transcode as simple single-axis convenience aliases. Chaining the verbs (crop | downsample | transcode) re-encodes the pixels once per stage — N× time and N× generational quality loss — whereas the unified path decodes the cropped region once and rebuilds the pyramid once.
Designed and planned, not yet executed.
Docs (on main)
Model
One axis per verb; convert is the union (ImageMagick-style — also covers the plain container case):
| Axis |
Single-op alias |
Flag(s) |
Status |
| space |
crop |
--rect X,Y,W,H |
exists |
| resolution |
downsample |
--factor / --target-mag |
exists |
| codec |
transcode (revive) |
--codec / --quality |
Plan 2 |
| container + all |
convert |
--to + the above |
Plan 1+2 |
| orientation |
rotate / flip |
--rotate / --flip |
deferred (slotted) |
| pyramid structure |
retile |
--tile-size / --level-ratio / --levels |
deferred (slotted) |
Plan 1 — engine convergence + convert --rect (11 tasks)
downscale.MaterializeWorkingL0 (crop∘downsample front-end).- Converge the duplicate
downsampleTo* (convert_factor.go) + cropTo* (crop_formats.go) per-format emitters into one shared transformTo* family fed by transformParams.
- Wire
convert --to X --rect … [--factor N] so crop + downsample + container fuse in one pass. crop / downsample unchanged.
- Behavior-preserving; guarded by each format's existing crop+downsample tests + a dciodvfy gate for DICOM ImageType.
Plan 2 — surface + safety rails (separate spec-driven plan, after Plan 1)
transcode alias (codec axis); --to defaults to source format (format-preserving default); arbitrary --codec on the transform path.- Three-tier conformance validation (impossible = hard error · non-conformant = error +
--allow-nonconformant + warn · valid-but-limited = warn) with a single codec×container capability table — designed to consume an upstream opentile-go validator if one lands.
- Lossless-regime generalization (auto-passthrough classifier);
--jobs/--workers reconciliation.
Deferred (slots reserved, separate future specs)
Orientation (rotate/flip — net-new raster rotation), pyramid structure (--tile-size/--level-ratio/--levels, retile), de-identification (label/PHI strip during convert), metadata policy (ICC/vendor preserve/strip), bit-depth/colorspace, multi-dim (Z/C) selection.
Execution
Execute Plan 1 task-by-task via subagent-driven-development (fresh subagent per task + two-stage review; controller runs the heavy integration/dciodvfy steps). Then brainstorm→spec→plan Plan 2 on the converged engine.
Make
converta single-pass transform pipeline that composes container change, codec change, crop, and downsample in one decode→transform→encode pass, while keepingcrop/downsample/transcodeas simple single-axis convenience aliases. Chaining the verbs (crop | downsample | transcode) re-encodes the pixels once per stage — N× time and N× generational quality loss — whereas the unified path decodes the cropped region once and rebuilds the pyramid once.Designed and planned, not yet executed.
Docs (on
main)docs/superpowers/specs/2026-06-14-unified-transform-convert-design.mddocs/superpowers/plans/2026-06-14-unified-transform-convert.mdModel
One axis per verb;
convertis the union (ImageMagick-style — also covers the plain container case):crop--rect X,Y,W,Hdownsample--factor/--target-magtranscode(revive)--codec/--qualityconvert--to+ the aboverotate/flip--rotate/--flipretile--tile-size/--level-ratio/--levelsPlan 1 — engine convergence +
convert --rect(11 tasks)downscale.MaterializeWorkingL0(crop∘downsample front-end).downsampleTo*(convert_factor.go) +cropTo*(crop_formats.go) per-format emitters into one sharedtransformTo*family fed bytransformParams.convert --to X --rect … [--factor N]so crop + downsample + container fuse in one pass.crop/downsampleunchanged.Plan 2 — surface + safety rails (separate spec-driven plan, after Plan 1)
transcodealias (codec axis);--todefaults to source format (format-preserving default); arbitrary--codecon the transform path.--allow-nonconformant+ warn · valid-but-limited = warn) with a single codec×container capability table — designed to consume an upstream opentile-go validator if one lands.--jobs/--workersreconciliation.Deferred (slots reserved, separate future specs)
Orientation (
rotate/flip— net-new raster rotation), pyramid structure (--tile-size/--level-ratio/--levels,retile), de-identification (label/PHI strip during convert), metadata policy (ICC/vendor preserve/strip), bit-depth/colorspace, multi-dim (Z/C) selection.Execution
Execute Plan 1 task-by-task via subagent-driven-development (fresh subagent per task + two-stage review; controller runs the heavy integration/dciodvfy steps). Then brainstorm→spec→plan Plan 2 on the converged engine.