Trim victory-lap docs language
This commit is contained in:
parent
f89d6ed49d
commit
f2b62bc25c
12 changed files with 73 additions and 103 deletions
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
10
docs/spec.md
10
docs/spec.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue