Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CubeAssembler

Scan a physical 2×2–7×7 puzzle cube from six photos and assemble its state in
Scan a physical 2×2–15×15 puzzle cube from six photos and assemble its state in
your browser.

[Open the scanner](https://wstein.github.io/cube-assembler/) ·
Expand All @@ -19,7 +19,7 @@ with no model download or production server.

## Scan a cube in five steps

1. **Choose a cube and colors.** Select a size from 2×2 to 7×7. Automatic
1. **Choose a cube and colors.** Select a size from 2×2 to 15×15. Automatic
colors compares the live face with built-in and saved palettes, or you can
choose a palette yourself.
2. **Capture six faces.** Show four sides while turning the cube, then its top
Expand All @@ -40,7 +40,7 @@ capture, since different faces can look identical on even cubes.
## What works

- Camera capture or six uploaded photos, cropped or uncropped.
- Cube sizes 2×2–7×7, with manual color correction when needed.
- Cube sizes 2×2–15×15, with manual color correction when needed.
- Physical-validity checks and an unfolded net plus 3D view.
- WRG/URF facelets and Orbit64 compact state tokens.
- Local, browser-only scanning; an optional development server saves fixtures.
Expand Down
2 changes: 1 addition & 1 deletion docs/color-profiles.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**Cube** and **Colors** are separate settings. A cube records its name, size,
and sticker gap. A color profile records six sticker colors and can be reused
across sizes. The Generic cube offers each size from 2×2 to 7×7 with a 60%
across sizes. The Generic cube offers each size from 2×2 to 15×15 with a 60%
sticker core and a 40% total gap. **New cube** copies the selected size and gap
so you can name and adjust a variant. Built-in cubes are read-only.

Expand Down
4 changes: 2 additions & 2 deletions docs/parity.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,12 @@ For a 3×3, four conditions are necessary and sufficient:
4. Corner and edge permutation parity agree.

All cube sizes have eight corner cubies, so the corner color-triplet and
orientation checks apply from 2×2 through 7×7. A 2×2 has no edges or centers;
orientation checks apply on every size from 2×2 up. A 2×2 has no edges or centers;
its complete model comes from corner checks alone.

## Larger cubes

On 4×4–7×7, each edge has N−2 wing pieces. Every wing's two colors must be
On cubes of 4×4 and larger, each edge has N−2 wing pieces. Every wing's two colors must be
one of the 12 canonical neighboring color pairs, and each pair must occur
exactly N−2 times. Wings are counted across depths; the validator does not
yet check the distinct depth orbits or generalize full edge permutation parity
Expand Down
4 changes: 2 additions & 2 deletions docs/scanner.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ it. [`gridAlignment.ts`](../src/client/vision/gridAlignment.ts) estimates an out
before its fine seam search, or searches around the centered guide when an
outline is unclear. The outline scan covers faces 0.7–1.3 times guide size
with centers up to 22% of a guide width away. The seam search stays within
half a cell of that estimate to avoid slipping a row on 5×5–7×7 faces.
For 6×6 and 7×7, an additional outer-edge check rejects seam fits whose
half a cell of that estimate to avoid slipping a row on faces of 5×5 and larger.
For 6×6 and larger, an additional outer-edge check rejects seam fits whose
grid lines miss the face. The live view then asks you to move the face toward
the center instead of accepting the shifted reading.

Expand Down
10 changes: 7 additions & 3 deletions docs/user-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@

[Open CubeAssembler](https://wstein.github.io/cube-assembler/). Scanning, review,
assembly, and ZIP import/export run in the browser. Choose a cube size from 2×2
through 7×7 before taking photos.
through 15×15 before taking photos. Face detection has been tested on real camera
photos of 2×2, 3×3, 4×4, 5×5 and 7×7 cubes. Sizes 6 and 8 to 15 have only
synthetic images, and only sizes 8, 9, 10, 12 and 15 were measured. Upright
faces are mostly found and read correctly; from 9×9 on, a tilted face often
loses the grid or shifts it, which gives wrong colors. Hold the face upright.

## Scan a cube

Expand Down Expand Up @@ -106,7 +110,7 @@ Turns snap into place like a magnetic cube: while you drag a layer or the whole
softly when capture **Sound** is on. Layer turns update the 2D net,
facelet notation, and Orbit64 token. The move list records completed turns;
**Undo** reverses the last one, and **Reset** returns to the captured state.
**Scramble** uses more moves for larger cubes and turns inner layers on 4×4–7×7,
**Scramble** uses more moves for larger cubes and turns inner layers on cubes of 4×4 and larger,
while leaving the fixed middle layer alone on odd cubes.
**Random State** mixes the cube at once into a random valid state, as speed
cubers do for practice: the cube spins once and its stickers change at the
Expand All @@ -133,7 +137,7 @@ face images are read directly. In Guide grid mode, select **Cropped face** for
an image that is already cropped but does not use a `face-*.jpg` filename.

**One picture of a cube net** works too: a screenshot or export of the cross
(U above F, L F R B in a row, D below) of a 2×2 to 7×7 cube, on a dark or
(U above F, L F R B in a row, D below) of a 2×2 to 15×15 cube, on a dark or
light background, with or without gaps, lines or face titles. The app finds the
stickers and the size, cuts the picture into six face images and goes on as with
six photos, so you see the order preview and the cube check as usual. Odd cubes
Expand Down
2 changes: 1 addition & 1 deletion index.html
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="CubeAssembler — read a physical 2x2 to 7x7 puzzle cube from six camera photos and check the result." />
<meta name="description" content="CubeAssembler — read a physical 2x2 to 15x15 puzzle cube from six camera photos and check the result." />
<meta name="cubelab-fingerprint" content="spec=1;app=cube-assembler@%APP_VERSION%" />
<title>CubeAssembler — NxN Cube State Assembler</title>
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "cube-assembler",
"version": "0.1.0",
"description": "Puzzle cube scanner: reads a physical 2x2-7x7 cube from six camera photos and checks the result (Preact + Vite, runs entirely in the browser).",
"description": "Puzzle cube scanner: reads a physical 2x2-15x15 cube from six camera photos and checks the result (Preact + Vite, runs entirely in the browser).",
"type": "module",
"scripts": {
"dev": "npm run rescript:build && node scripts/dev.mjs",
Expand Down
2 changes: 1 addition & 1 deletion src/cube/Parity.res
Original file line number Diff line number Diff line change
Expand Up @@ -417,7 +417,7 @@ let runFullParity = (cube: cubeIR): parityResult => {
// permutation, so there is nothing further to check.
{valid: true, result: validResult, checks}
} else if n != 3 {
// 4x4-7x7: wings are validated by counting, then by identity per
// 4x4 and larger: wings are validated by counting, then by identity per
// orbit, then an odd cube's middle edges like a 3x3's edges. Centers need no check:
// color balance plus the exact corner and wing counts leave each
// color's center count no choice, and center pieces of one color
Expand Down
60 changes: 60 additions & 0 deletions test/docSizeRange.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import { readFileSync } from 'node:fs'
import { describe, expect, it } from 'vitest'
import { CUBE_SIZES } from '../src/client/profiles/profileSettings'

const read = (path: string): string =>
readFileSync(new URL(`../${path}`, import.meta.url), 'utf8')

const maxSize = Math.max(...CUBE_SIZES)

// Files whose text states the supported cube size range.
const RANGE_FILES = [
'README.md',
'index.html',
'package.json',
'docs/color-profiles.md',
'docs/user-guide.md',
'docs/parity.md',
'docs/scanner.md',
]

const SIZE = String.raw`(\d+)\s*[x×]\s*\d+`

// Upper bounds below the maximum, in the forms the docs use:
// "2×2–7×7", "4x4 to 7x7", "5×5 through 7×7"
const RANGE_END = new RegExp(
String.raw`\b${SIZE}\s*(?:–|-|to|through)\s*${SIZE}`,
'gi',
)
// "a cube up to 7×7"
const UP_TO = new RegExp(String.raw`\bup to\s*${SIZE}`, 'gi')
// "sizes 2 to 7", "sizes 2..7", "2 to 7 cubes"
const NUMBER_RANGE =
/\b(?:sizes?\s+)?2\s*(?:–|-|to|through|\.\.)\s*(\d+)\b(?!\s*[x×])/gi
// "6×6 and 7×7" (a pair, not a list item after a comma)
const PAIR = new RegExp(String.raw`(?<!,\s)\b${SIZE}\s+and\s+${SIZE}`, 'gi')

const upperBounds = (text: string): number[] => [
...[...text.matchAll(RANGE_END)].map((m) => Number(m[2])),
...[...text.matchAll(UP_TO)].map((m) => Number(m[1])),
...[...text.matchAll(NUMBER_RANGE)].map((m) => Number(m[1])),
...[...text.matchAll(PAIR)].map((m) => Number(m[2])),
]

describe('documented cube size range', () => {
it('uses the supported maximum', () => {
expect(maxSize).toBe(15)
})

for (const file of RANGE_FILES) {
it(`${file} states no range that ends below ${maxSize}`, () => {
const ends = upperBounds(read(file))
expect(ends.filter((end) => end !== maxSize)).toEqual([])
})
}

it('names the maximum in the README and the page description', () => {
expect(read('README.md')).toContain(`${maxSize}×${maxSize}`)
expect(read('index.html')).toContain(`${maxSize}x${maxSize}`)
})
})
2 changes: 1 addition & 1 deletion test/fixtures/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ directly rather than adding duplicate individual JPEGs outside Git LFS. See its
[provenance and verification boundary](orientation-recovery-7x7.md). New
`capture.faceRecovery` metadata preserves exact manual photo assignments,
rotations, and display pose; [the contract](../../docs/orientation-recovery.md)
also describes imported 8×8 correction and validation limits.
also describes imported capture correction and validation limits.

## Photo identity: patterned 4×4 capture

Expand Down
Loading