127 lines
5.2 KiB
Markdown
127 lines
5.2 KiB
Markdown
# Repixelizer Implementation Plan
|
|
|
|
## What this file is
|
|
|
|
This file is the forward plan for Repixelizer.
|
|
|
|
It is not the authoritative stage-by-stage control-flow map. That lives in
|
|
`docs/lean-optimizer-algorithm-map.md`.
|
|
|
|
If these two notes disagree about what the code does right now, trust the
|
|
algorithm map and the source, then fix this plan.
|
|
|
|
## Current machine
|
|
|
|
Repixelizer has one live reconstruction engine:
|
|
|
|
- `phase-field`: the canonical reconstruction engine in `src/repixelizer/phase_field.py`
|
|
|
|
The live pipeline is:
|
|
|
|
`source image -> lattice inference -> diagnostic edge preview -> fixed lattice centers -> hierarchical flatness signal -> explicit local search + lattice relaxation -> nearest source sample -> cleanup -> optional palette fit -> diagnostics`
|
|
|
|
Inference splits two ways:
|
|
|
|
- fixed lattice when the caller pins size explicitly
|
|
- autocorr lattice when size is inferred automatically; autocorr can surface multiple candidates, and low-confidence candidates can be preview-reranked
|
|
|
|
The hosted web shell has an auth seam:
|
|
|
|
- `src/repixelizer/access.py` owns the app-local access boundary and local ownership checks
|
|
- `src/repixelizer/gui.py` owns hosted route policy, landing-page behavior, and queue/job stamping
|
|
- `GC_ACCESS_MODE=heimdall` supports provider start, backend callback receipt, local JWT verification, and httpOnly session adoption
|
|
- Heimdall mode also keeps a separate httpOnly refresh cookie and asks
|
|
Heimdall to reissue short-lived app claims before restarting provider OAuth
|
|
- self-host and local runs stay permissive by default unless `GC_ACCESS_*` turns the seam on
|
|
|
|
## What is working
|
|
|
|
- `phase-field` is the only canonical reconstruction path.
|
|
- The current explicit solver is fast enough for hosted interaction.
|
|
- Compare mode, benchmark mode, diagnostics writing, GUI observer previews, and tuning harnesses exist.
|
|
- Spritesheet CLI mode detects separated foreground regions, runs the live pipeline per region, and packs the per-sprite outputs back into sheet order.
|
|
- The repo reports both `source_fidelity` and `source_structure` so lattice agreement and visible structure can be inspected separately.
|
|
- Hosted landing/app flow is in place and should be the immediate product path.
|
|
|
|
## Current solver shipping state
|
|
|
|
The current solver config is shippable, not final.
|
|
|
|
Useful current values:
|
|
|
|
- `phase_field_grid_alignment_weight=4.75`
|
|
- `phase_field_local_search_radius_ratio=0.215`
|
|
- `phase_field_local_search_blend=0.24`
|
|
- `phase_field_local_search_move_weight=0.09`
|
|
- `phase_field_signal_energy_power=1.4`
|
|
- `phase_field_signal_peak_power=3.25`
|
|
|
|
Tuning lesson:
|
|
|
|
- broad local-search radius caused samples to poach neighboring features
|
|
- the focused useful radius basin is around `0.20-0.22`
|
|
- at that tighter radius, stronger blend became useful
|
|
- signal knobs were not fully explored around the new basin
|
|
|
|
Detailed tuning notes live in `docs/solver-tuning-lessons-2026-04-29.md`.
|
|
|
|
## Current priorities
|
|
|
|
### 1. Ship the hosted experiment
|
|
|
|
Goal:
|
|
|
|
- get Repixelizer online
|
|
- stop blocking Heimdall
|
|
- stop Heimdall from blocking StreamPixels
|
|
|
|
Practical stance:
|
|
|
|
- do not spend more time polishing solver knobs before hosted launch unless a blocking quality regression appears
|
|
- keep hosted auth and access work isolated to `src/repixelizer/access.py` and `src/repixelizer/gui.py`
|
|
- keep solver and pipeline code out of auth work
|
|
|
|
### 2. Keep lattice inference honest
|
|
|
|
Current stance:
|
|
|
|
- keep automatic inference grounded in autocorrelation
|
|
- let autocorr keep a small near-best lag plateau and use cross-axis consensus before collapsing to one lattice family
|
|
- keep hosted demo inference on the autocorr path with candidate rerank available when confidence is low
|
|
- keep candidate rerank as optional support for low-confidence autocorr choices
|
|
|
|
### 3. Later: retune the phase-field solver deliberately
|
|
|
|
The next solver pass should begin from the current live config and its narrow
|
|
search geometry.
|
|
|
|
Recommended order:
|
|
|
|
1. Sweep signal knobs around `radius=0.215, blend=0.24`.
|
|
2. Sweep movement/coherence knobs around the best signal candidate.
|
|
3. Test combinations only after single-knob effects are understood.
|
|
4. Validate on focused artificial cases, real character glint/symbol cases, and the badge fixture.
|
|
5. Run full-corpus validation at the end, not during every exploratory twitch.
|
|
|
|
Knobs still underexplored in the new basin:
|
|
|
|
- `phase_field_signal_weight`
|
|
- `phase_field_signal_gradient_weight`
|
|
- `phase_field_signal_curvature_weight`
|
|
- `phase_field_signal_level_decay`
|
|
- `phase_field_signal_pyramid_levels`
|
|
- `phase_field_signal_energy_power`
|
|
- `phase_field_signal_peak_power`
|
|
- `phase_field_local_search_move_weight`
|
|
- `phase_field_grid_alignment_weight`
|
|
- `phase_field_local_search_grid_weight`
|
|
|
|
## Guardrails
|
|
|
|
- Prefer one clear hypothesis per pass.
|
|
- Show the output after every real reconstruction run when doing visual tuning.
|
|
- Keep maps updated after code changes.
|
|
- Revert or delete machinery that does not visibly earn its keep.
|
|
- Keep solver changes inside the one-field / one-signal / one-relaxation model unless the design map changes first.
|
|
- If a new term lands, it must belong cleanly in the one-field / one-signal / one-relaxation model.
|
|
- Treat metrics as evidence about the output, not as a replacement for visual inspection.
|