Skip to content

perf(color): solve the balanced color assignment as a transportation problem - #73

Merged
wstein merged 3 commits into
mainfrom
feat/color-pass-speedup
Nov 18, 2026
Merged

wstein merged 3 commits into
mainfrom
feat/color-pass-speedup

Conversation

@wstein

@wstein wstein commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

Speeds up the six-face color pass (classifyAcrossFaces) for large cubes. Per-face color reading is untouched.

Cause: balancedAssign expanded each of the six colors into capacity slots and solved an M x M matching (M = 6 n^2) with the O(M^3) Hungarian algorithm, 20 times in kMeansCluster plus 17 more calls. The farthest-pair search in splitMixedPairs converted both colors to Oklab on every distance call.

Changes:

  • balancedAssign is a transportation problem over the six clusters (cheapest augmenting paths, O(m^2 k)). Same objective (sum of clusterDistance), capacities and pin rules; hungarianAssignment stays.
  • Points and centroids are converted to Oklab once (balancedAssign, splitMixedPairs); values are unchanged.

Tests: test/balancedAssign.test.ts keeps the old slot expansion as a reference: equal minimum, capacities, pins, equal assignment for unique optima (2..10), speed budgets at n=12/15.

Equivalence: classifyAcrossFaces on synthetic cubes (random, solved, checker; real and clean presets) returns a byte-identical result before and after for n=2..12 (72 of 72 cases).
Time, median of two cubes under load 25-35: 7x7 913 -> 197 ms, 9x9 1.9 s -> 0.31 s, 12x12 11.0 s -> 0.34 s, 15x15 51.8 s -> 0.50 s.
Tie behavior: with exactly equal costs (coarse color grids) the minimum is equal but another equal-cost assignment can be chosen (the reference differs in about two thirds of 400 such cases); real captures and the synthetic cubes above are not affected.

Checks: typecheck, lint, format:check, build, typos, git diff --check, vitest (47 known LFS failures; nothing else fails when the load allows the 5 s timeout).

Blocker: none.

🤖 Generated with Claude Code

wstein and others added 3 commits November 18, 2026 14:22
Adds the old slot-expansion implementation as a test-only reference and
checks equal minimum cost, capacities, pins and (for unique optima) equal
assignments for sizes 2..10, plus exact-tie cases and a speed budget at
n=12 and n=15. The vision adapters now re-export balancedAssign and
clusterDistance for it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The slot expansion made an M x M matrix with M = 6 n^2 and solved it in
O(M^3), so the six-face pass took 2.3 s at 7x7 and 74 s at 15x15. Points
now enter one by one along the cheapest augmenting path over the six
clusters, which keeps the same minimum cost and capacities at O(m^2 k).
Equal costs resolve by the lowest cluster and member index.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
clusterDistance converts both colors on every call. balancedAssign now
converts points and centroids once, and splitMixedPairs converts the
members once for its farthest-pair search (the distance is symmetric, so
only pairs at or after the diagonal are visited). Values and the pair
chosen are unchanged. Adds a learning-pass budget at 15x15.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@wstein

wstein commented Nov 18, 2026

Copy link
Copy Markdown
Owner Author

Review: CLEAR head=b51190e4eab643ce3e213c92227ab87d12d345e5 patch-id=6df60e408b0f6fad4b2e2c4364b162e106f8c4f9 pr=73
Round 1, independent. Old d4d4463 vs head, own inputs: classifyAcrossFaces 327/328 byte-identical (n=2..9, 11; random, solved, checker, exact duplicate colors, with and without reference pins); 26 saved fixture readings 52/52 identical. The one difference (7x7, exact duplicate colors, two equal centers) swaps one cell confidence between two identical stickers; labels equal.
balancedAssign direct: 342/352 identical, all 10 others have the same per-point cost multiset; 0 capacity, pin or range violations; brute force 150/150 at the minimum. splitMixedPairs seed pair is equal (distance is bitwise symmetric).
Tie decision (deterministic new rule instead of the slot order) is sound; old ties were unspecified.
1 low nit StickerLearning.res:93-95,146,195: the documented tie rule is untested; <= at move or target survives all tests. Open.
2 low nit StickerLearning.res:286-296: the Oklab cache in splitMixedPairs has no test; a wrong member index and a swapped seed order survive 75 + 242 related tests (my old/new harness catches the index one in 2/96). Open.
3 low nit test/balancedAssign.test.ts:362-374: the 10 s budget exceeds the default 5 s test timeout; pass an explicit timeout. Open.
4 low nit PR text: "real captures ... are not affected" is shown for the 26 saved captures only; say so. Open.
Mutations: 13 run; edge cost, capacity off-by-one, capacity ignored (line 118), pin room, pins ignored, Oklab row index, no displacement, one BF round killed; tie x2 and split x2 survive (nits 1-2); dirty[from] is equivalent.
Runs: typecheck, lint, format:check, build, typos, git diff --check rc 0; balancedAssign.test.ts 75/75; vitest head 1618 pass / 47 fail, base 1543 / 47, same 47 LFS "SOI not found".
CI on head: CI (pull_request) success. Commits Conventional with Co-Authored-By, identity matches, no CRLF, no session links (0).
Not checked: e2e locally, tests on a merge with current main (9ecef3e, no PR files touched, merge-tree clean).

@wstein
wstein marked this pull request as ready for review November 18, 2026 15:32
@wstein
wstein merged commit 7ec5b12 into main Nov 18, 2026
2 checks passed
@wstein
wstein deleted the feat/color-pass-speedup branch November 18, 2026 15:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant