Trim victory-lap docs language

This commit is contained in:
Meta Vens 2026-04-29 11:43:17 +01:00
commit f2b62bc25c
12 changed files with 73 additions and 103 deletions

View file

@ -10,8 +10,7 @@ Repixelizer-specific binding:
- `E:\Projects\Heimdall\docs\app-profiles\repixelizer.md`
This local file remains only as a redirect stub so old notes and links do not
pretend the shared access plan still lives inside Repixelizer.
This local file remains as a redirect stub for existing notes and links.
Current repo truth is unchanged:

View file

@ -8,8 +8,7 @@ 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 instead of hand-waving about
intent.
algorithm map and the source, then fix this plan.
## Current machine
@ -38,7 +37,7 @@ The hosted web shell has an auth seam:
- `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.
- The repo reports both `source_fidelity` and `source_structure` because lattice-only scoring can slander better-looking output.
- 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
@ -86,14 +85,12 @@ 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
- do not revive the old pixel-walk / change-interval spacing path
- do not revive the projected edge-energy spectral pass
- treat candidate rerank as optional scaffolding, not sacred machinery
- 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, not from the old
wide-radius geometry.
The next solver pass should begin from the current live config and its narrow
search geometry.
Recommended order:
@ -122,9 +119,6 @@ Knobs still underexplored in the new basin:
- 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.
- Do not reintroduce lattice phase, portrait layers, candidate trays, or solver-stage religions casually.
- 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.
- If a result looks better and the metrics disagree, fix the metrics rather than worshipping them.
This repo already spent enough time as a Jenga tower of maybe-useful cleverness.
The machine has to deserve every part.
- Treat metrics as evidence about the output, not as a replacement for visual inspection.

View file

@ -34,7 +34,8 @@ These are the pieces that actually matter:
- `disp = pos - uv0_px`: reported displacement field derived from live positions
- `target_rgba`: final output grid after nearest-source sampling
Everything else is support scaffolding.
The remaining helpers load inputs, write diagnostics, or carry this state across
the CLI, GUI, and comparison harness.
## Diagram
@ -61,7 +62,7 @@ flowchart TD
- one lattice relaxation pass to keep spacing coherent
- honest final nearest-source sampling
The current live solver is not projected Adam anymore. The old differentiable loss scaffolding has been removed; `optimize_phase_field(...)` is the explicit NumPy local-search path.
`optimize_phase_field(...)` is the explicit NumPy local-search path.
## Stage 0: The pipeline chooses the ruler
@ -148,13 +149,7 @@ The current signal path is intentionally simple:
- invert it so low-gradient / low-curvature regions become attractive flatness
- sharpen the flatness map with `phase_field_signal_peak_power`
What no longer happens:
- no boundary-context reward
- no wall mask
- no distance transform
- no ring/context/self-penalty signal knobs
- no lattice phase concept
The live signal is the flatness map described above; diagnostic edge preview remains separate from solver steering.
### Metaphor
@ -247,7 +242,7 @@ grid_alignment * phase_field_grid_alignment_weight
- local_signal * phase_field_signal_weight
```
This is feedback for the GUI and logs. It is not a differentiable Adam objective.
This is feedback for the GUI and logs.
### Metaphor
@ -268,7 +263,7 @@ After the loop:
2. Index the original source RGBA.
3. Report `final_disp = pos - uv0_px` and normalized `uv_field`.
The emitted image is made of actual source pixels, not bilinear soup.
The emitted image is made of actual source pixels.
### Metaphor
@ -327,15 +322,7 @@ The important tuning lesson:
## Guardrails
These categories of complexity should not come back casually:
- lattice phase search or explicit lattice phase controls
- per-cell candidate trays that persist across stages
- extra source-derived reference rasters steering the field directly
- multiple sequential solver religions with separate objectives
- cleanup pretending to be the real reconstruction engine
The point of this machine is still one ruler, one position field, one local signal, one lattice relaxation, and one final source sample.
Future solver changes should preserve the current model unless the design map is updated first: one ruler, one position field, one local signal, one lattice relaxation, and one final source sample.
## Documentation boundaries

View file

@ -10,8 +10,7 @@ Shared architecture note:
- `E:\Projects\Heimdall\docs\architecture.md`
This local file remains only as a redirect stub so Repixelizer does not keep a
second copy of the same future auth plan fermenting in a corner.
This local file remains as a redirect stub for existing notes and links.
Current repo truth is unchanged:

View file

@ -1,8 +1,7 @@
# Solver tuning lessons - 2026-04-29
This note records what the tuning pass actually taught us, what it did not
teach us, and how the next pass should be run without constructing another
beautiful little swamp.
This note records what the tuning pass showed, what remains untested, and how
the next tuning pass should be run.
## Shipping state
@ -19,7 +18,7 @@ The current shipped trial config is intentionally usable, not final:
}
```
Everything else in `config/solver_params.json` remains as previously configured.
Other solver parameters remain as configured in `config/solver_params.json`.
The important caveat: this is a motion-geometry win, not a full signal-shape
optimum. It is acceptable for shipping the hosted experiment, but it should not
@ -28,9 +27,8 @@ be treated as the final form of the phase-field solver.
## What the pass proved
The most useful discovery was that the local-search radius was much too large.
The solver was not merely underpowered; it was letting samples inspect too much
neighboring territory. Adjacent samples could chase the same feature, which
looked like feature attraction but behaved like poaching.
At larger radii, adjacent samples could inspect overlapping neighborhoods and
chase the same feature.
Recent focused artificial results, all with:
@ -59,7 +57,7 @@ The model this supports:
- `radius` is the gatekeeper for whether samples solve locally or poach.
- Very small radius eventually starves movement, as seen at `0.16`.
- The useful basin is narrow, roughly `0.20-0.22`, with `0.215` best in the focused pass.
- Once the search window is tight, stronger blend becomes useful because samples can move without wandering into the neighbor's lunch.
- Once the search window is tight, stronger blend becomes useful because samples move within a more local neighborhood.
Blend sweep at `radius=0.215`:
@ -74,7 +72,7 @@ Blend sweep at `radius=0.215`:
The model this supports:
- After radius is tightened, blend must be retuned.
- Low blend was compensating for an over-wide search area.
- Low blend performed best in the wider search regime.
- At the new radius, `0.24` is better than `0.18` on focused metrics.
- We did not yet find the upper blend cliff. `0.24` won the tested set, but values above it still need bracketing later.
@ -96,18 +94,16 @@ not sweep:
- `phase_field_grid_alignment_weight` around the new basin
- `phase_field_local_search_grid_weight` around the new basin
Earlier experiments touched some of these in older regimes, but those results
should not be treated as final because they were gathered before the current
motion geometry was discovered. A signal knob can look useless when the solver
cannot move into the signal correctly. That is exactly how we wasted time
before.
Earlier experiments touched some of these in previous regimes, but those
results should not be treated as final because they were gathered before the
current motion geometry was selected.
The correct summary is:
- Current config is shippable.
- Motion geometry is much better understood.
- Signal shape remains underexplored in the new basin.
- The next tuning pass should start from `radius=0.215, blend=0.24`, not from the old wide-radius config.
- The next tuning pass should start from `radius=0.215, blend=0.24`.
## Current mental model
@ -126,9 +122,7 @@ The important part is the scale separation:
- The blend says how fast the sample moves toward the chosen position.
- The lattice coherence force says how much the grid resists local deformation.
The mistake was treating signal strength as the main issue while the search
window was still too broad. A broad search window turns a good signal into a
poaching contest.
Signal tuning should be evaluated against the current search window.
## Config intents we can currently generate

View file

@ -10,7 +10,7 @@ The project exists because generated imagery often creates appealing pixel-like
- noisy highlights and outlines
- fake micro-detail that collapses when downsampled
Repixelizer treats this as lattice inference plus reconstruction rather than a resize problem.
Repixelizer treats this as a lattice-inference and reconstruction problem.
## Goals
@ -108,7 +108,7 @@ The tool must estimate the resolution of the fake lattice being mimicked.
Requirements:
- infer candidate target sizes from autocorrelation hints
- use canonical cell centers for each candidate
- score candidates using coherence-oriented metrics rather than reconstruction alone
- score candidates using coherence-oriented metrics and source-derived periodicity priors
- expose the top-ranked alternatives in diagnostics
- if `--target-size`, `--target-width`, or `--target-height` is provided, skip automatic inference
@ -141,7 +141,7 @@ Requirements:
- relax row and column springs so the sample field stays coherent
- nearest-sample the original source pixels for final output
The current implementation is explicit NumPy local search plus spring relaxation. It is not the old PyTorch autograd / projected-Adam displacement solver.
The current implementation is explicit NumPy local search plus spring relaxation.
### 4. Discrete projection and cleanup
@ -150,9 +150,9 @@ After the phase-field stage, the result must be treated as a true pixel grid.
The discrete stage should:
- preserve source-sampled RGBA values
- snap alpha to an opaque/transparent mask
- leave structural repair to the solver rather than hiding confusion with a cleanup pass
- keep structural repair in the solver
Cleanup is intentionally small in v1. It should not become a second solver wearing a trench coat.
Cleanup is intentionally small in v1.
### 5. Baselines and comparison mode