The current optimizer is useful, but it is also a fussy little parliament.
Too many portraits. Too many local trays. Too many side negotiations about adjacency, motif, line, handoff, guardrails, and whether the machine still trusts its own decisions.
This document is not a map of the code we have.
It is a map of the optimizer we should replace it with:
`infer one lattice -> attach one displacement vector to each output cell -> nudge those vectors toward solid source regions while keeping the field coherent -> sample once`
That is the whole dream. No watercolor portrait. No accountant's ledger. No snap religion and refine religion living in the same cathedral. Just one field, one objective, one final sample.
It is already the right kind of machine, and it now owns the main optimizer path. The remaining work is quality tuning, not architectural self-deception.
-`uv0[y, x]`: the base source-space center for each output cell
Meaning:
This is the unmoving graph paper.
Unlike the current optimizer, the new machine should be honest about what is fixed and what is variable:
-`uv0` is fixed
-`d` is the thing being optimized
There should be no fake "UV optimizer" language once that distinction exists.
### Metaphor
This is the empty skeleton of the machine.
The graph paper is nailed to the mural. Nothing clever has happened yet. Each cell is just a little pinned square waiting to decide how much to slide before it commits.
## Stage 2: Initialize one displacement vector per cell
New state:
-`d[y, x] = (0, 0)` initially
Meaning:
Every output cell starts by targeting the exact center of its inferred source cell.
That is the null hypothesis:
- maybe the inferred phase is already fine
- maybe some regions need to drift
The machine starts from stillness and earns every movement.
### Metaphor
Every cell begins with its feet planted under its shoulders.
No lunging. No mystical premonitions about where it "really wants" to go. Just a row of workers standing still on the scaffold until the foreman starts shouting.
## Stage 3: Sample the source at the displaced centers
Derived state:
-`uv = uv0 + d`
-`sampled_rgba[y, x]`
Meaning:
At any moment, each output cell points at one source location:
- start from the fixed center
- add the current displacement
- sample the source there
This is the only color the cell currently "believes in."
There should be no alternate portrait layer describing what the cell vaguely feels like. The sample is the truth of the current hypothesis.
### Metaphor
Each worker shines a laser pointer from the scaffold down onto the mural.
Where the dot lands, that is the color they are claiming. No watercolor sketch. No emotional support ledger. Just a dot on paint.
## Stage 4: Compute the local evidence term
New objective family:
- prefer displacement targets that land inside solid or internally coherent local regions
Candidate implementation options worth testing:
- low local variance in a tiny neighborhood around `uv`
- low edge energy in a tiny neighborhood around `uv`
- high agreement between the center sample and nearby samples inside a fractional cell window
Meaning:
This is the term that tries to make each cell land inside a fake-pixel interior instead of on a messy boundary.
The purpose is simple:
- solid colored areas are safe
- high-conflict mixed areas are dangerous
This term is the main answer to "why move at all?"
### Metaphor
The worker is probing the mural with a boot before putting full weight down.
Some spots are firm stone. Some are crumbling ledges. This term tells the field to step onto the stable bits instead of balancing on the edge of a crack like an idiot.
## Stage 5: Compute coherence and topology terms
New objective family:
- neighboring cells should have similar displacements unless a real edge justifies a break
- nearby output cells should not collapse onto the same source pixel
- the field should not fold, cross, or invert local order
- displacement magnitude should stay modest unless the data term really wants motion
Meaning:
This is where the optimizer stops being a mob of independent little boot-probes.
These terms are what make the displacement field a field:
- smoothness keeps neighboring cells moving together
- edge-aware gating prevents smoothness from smearing through sharp source boundaries
- anti-collapse / anti-fold constraints stop the grid from crumpling into duplicated samples
- magnitude regularization keeps the field from wandering off because one local patch looked briefly tempting
This is the actual home for the design goal that `relax` only half fulfilled.
### Metaphor
Now imagine the workers are connected by springs, but the springs are smart enough to loosen at real cracks in the wall.
They can drift together like a sheet, but they are not allowed to pile into the same footprint or climb over each other like rats in a drain.
## Stage 6: Update the displacement field directly
New core operation:
- optimize `d` itself, not a tray of discrete local candidate picks
Candidate solver shapes worth trying:
- gradient descent or Adam on a differentiable approximation
- projected gradient steps with explicit clamp / anti-fold projection
- alternating local smoothing plus data-term descent
Hard invariants:
-`d` remains bounded
- local topology constraints are enforced every iteration
- edge-aware coherence remains part of the update, not a decorative afterthought
But the supervision should judge one coherent pipeline, not referee a knife fight between three subsolvers. The important diagnostics for this machine are:
The lean optimizer is now the live optimizer. The job is no longer to justify its existence. The job is to improve it without letting it mutate back into a tray cult.
