gamut convert now has two PNG effort flags whose names promise the same kind of thing and
deliver different kinds of thing, and the same word means the whole ladder for every sibling
codec in the same command.
What is inconsistent
| flag |
what the word names |
shape |
--webp-effort |
the whole WebP size/time ladder (gamut_webp::Effort) |
0..=6 |
--jxl-effort |
the whole JPEG XL size/time ladder (gamut_jxl::Effort) |
1..=10 |
--png-preset |
the whole PNG size/time ladder (gamut_png::Preset) |
fast|balanced|small|smallest |
--png-effort |
one knob of the five that ladder composes — the DEFLATE optimal-parse refinement budget (gamut_deflate::DeflateEncoder::with_effort) |
0..=255 |
So --webp-effort 6 and --png-effort 15 read alike and are not alike: the first selects a rung,
the second overrides one field of a rung. And --png-effort does nothing at all unless the
selected rung is at Level::Best, because that is the only level the refinement budget reaches —
a user who reaches for the flag with the obvious intent ("make the PNG smaller") under
--png-preset fast or balanced gets silence.
Where it is
crates/gamut-cli/src/commands/convert.rs — the png_preset and png_effort fields of
ConvertArgs, and their two sibling webp_effort / jxl_effort fields a few lines above.
Why it is not fixed in place
Both candidate repairs rename a user-visible flag:
- rename
--png-preset to --png-effort (taking the siblings' numeric 0..=3 form) and the
present --png-effort to something that names what it actually is, e.g.
--png-refinement-passes; or
- keep both names and make
--png-effort's help text say that it is one knob inside the rung
rather than the rung.
The first is the consistent one and is a breaking change to the command line. Neither is what
issue #484 asked for, which was a composed dial in gamut-png plus a way to reach it from the
command line. Filed rather than taken so the rename is decided on its own terms, alongside
whatever else gamut convert's flag surface owes.
Found while reviewing the effort dial delivered in #625.
gamut convertnow has two PNG effort flags whose names promise the same kind of thing anddeliver different kinds of thing, and the same word means the whole ladder for every sibling
codec in the same command.
What is inconsistent
--webp-effortgamut_webp::Effort)0..=6--jxl-effortgamut_jxl::Effort)1..=10--png-presetgamut_png::Preset)fast|balanced|small|smallest--png-effortgamut_deflate::DeflateEncoder::with_effort)0..=255So
--webp-effort 6and--png-effort 15read alike and are not alike: the first selects a rung,the second overrides one field of a rung. And
--png-effortdoes nothing at all unless theselected rung is at
Level::Best, because that is the only level the refinement budget reaches —a user who reaches for the flag with the obvious intent ("make the PNG smaller") under
--png-preset fastorbalancedgets silence.Where it is
crates/gamut-cli/src/commands/convert.rs— thepng_presetandpng_effortfields ofConvertArgs, and their two siblingwebp_effort/jxl_effortfields a few lines above.Why it is not fixed in place
Both candidate repairs rename a user-visible flag:
--png-presetto--png-effort(taking the siblings' numeric0..=3form) and thepresent
--png-effortto something that names what it actually is, e.g.--png-refinement-passes; or--png-effort's help text say that it is one knob inside the rungrather than the rung.
The first is the consistent one and is a breaking change to the command line. Neither is what
issue #484 asked for, which was a composed dial in
gamut-pngplus a way to reach it from thecommand line. Filed rather than taken so the rename is decided on its own terms, alongside
whatever else
gamut convert's flag surface owes.Found while reviewing the effort dial delivered in #625.