Optimize Small Icons

Optimize Small Icons

Preserve the visual meaning of tiny features while retaining antialiased boundaries. Treat each important color as a semantic layer, then inherit a solid core pixel only when an important source component otherwise loses every core pixel.

Workflow

1. Preserve the source artwork and write outputs to a separate directory during tuning.
2. Identify the background and the exact anchor colors whose identity must survive at 16, 24, 32, and 48px.
3. Read references/algorithm.md before choosing matte layers or core inheritance thresholds.
4. Read references/recipe-schema.md when creating or editing the JSON recipe. Read references/platform-assets.md before producing Windows, macOS, Linux, Android, or iOS release assets.
5. Validate the invocation without writes:

python scripts/icon_resampler.py build \
  --input logo.png \
  --config icon-recipe.json \
  --output-dir icon-output \
  --dry-run

6. Build the family:

python scripts/icon_resampler.py build \
  --input logo.png \
  --config icon-recipe.json \
  --preset windows-full \
  --output-dir icon-output \
  --json

7. Inspect the actual-size row and nearest-neighbor detail row in preview.png. Do not judge only a smooth zoomed preview.
8. Confirm report.json says verification.all_frames_exact: true, then inspect anchor counts and any promoted core pixels.
9. Inspect the embedded ICO independently when replacing a production asset:

python scripts/icon_resampler.py inspect --input icon-output/icon.ico --json

Stable CLI contract

Keep algorithm revisions internal through --strategy; the current strategy is core-inheritance-v4. Always keep these external outputs stable:

• icon.ico
• preview.png
• report.json
• frames/<size>x<size>.png

Rerunning the same build is safe and replaces only these owned outputs. Use --sizes only for deliberate frame-set overrides.

Use the built-in windows-full preset for 16/20/24/30/32/36/40/48/60/64/72/80/96/128/256px. Use windows-minimum only when a constrained toolchain cannot carry the full set.

For multi-platform projects, expose one project command that regenerates every platform from the same canonical high-resolution source. Never make one platform consume another platform's already-resized output.

Tuning order

Tune in this order to avoid compensating for one defect with another:

1. Crop and corner radius.
2. Background and exact semantic anchors.
3. Broad core strengthening for already-visible colors.
4. Chroma mattes for saturated subpixel details.
5. Projection mattes for neutral or low-chroma details.
6. Protected ownership so later layers cannot overwrite earlier colors.
7. Contrast-weighted core inheritance for disconnected components that still lack a solid core.

Prefer the lowest thresholds that restore identity without thickening shapes. A component that already retains a core must remain untouched.

Dependencies

Run with Python 3.10+ and install Pillow, numpy, and scipy. If imports fail, report the exact missing package and use the environment's normal dependency manager rather than silently changing the algorithm.