Color Sensitivity slider has no preview — user picks blind, waits ~3s per attempt to see the result #121

New issue

Closed

opened 2026-10-02 23:40:02 +00:00 by Mark · 0 comments

Mark commented

2026-10-02 23:40:02 +00:00

Owner

Finding

The Workspace's "Color Sensitivity" slider (in the right panel, under Auto-Digitize Settings) maps to a maxColors: 1–10 parameter sent to the digitize service. The service quantizes the uploaded image server-side. There is no client-side preview of what the quantized result will look like before the user commits to "Run Auto-Digitize" — they have to wait ~3 seconds for the API call, see the result, and if it's wrong, change the slider and re-digitize the whole image.

Where

Slider source: src/components/workspace/RightPanel.tsx (the Auto-Digitize Settings section, somewhere around line 200 — the existing test RightPanel.test.tsx:200+ references colorSensitivity).
Service call: src/lib/digitize-adapters.ts:32 (the maxColors mapping is documented in the file's comment).
Service: POST /v1/digitize on the easystitch-service.

The relationship colorSensitivity 0–100 → maxColors 1–10 is a linear map (verified in src/lib/digitize-adapters.test.ts:119).

Why now

Every other "see before you commit" surface in the app is live:

Hoop size dropdown changes the hoop outline on the canvas immediately
Fabric / stabilizer dropdowns update labels
Render scale changes the canvas resolution immediately

But color sensitivity requires a full API roundtrip and a re-quantization. The user is picking blind.

This is also the entry point to a missing capability: there's no way to constrain the design to "use only the colors I have on my spool rack." A user with 5 spools who wants to digitize a 12-color design has no UI to say "use only these 5 colors and find the closest match."

Suggested fix shape

Add a client-side quantization preview that runs synchronously on slider change:

Implementation: client-side color quantization of the uploaded image's pixels. A simple approach:
- Downsample the image to ~100×100 max (so the quantization is fast, <50ms)
- K-means with k = maxColors (1-10) in RGB or Lab space
- Render the quantized result to a small preview canvas (e.g. 200×200) inside the right panel, next to the slider
Preview canvas: shows the quantized result live as the slider moves. ~50ms re-quantize on every slider change is acceptable.
Commit: only when the user clicks "Run Auto-Digitize" does the actual API call fire, with the same maxColors value the preview used.
Optional — palette constraint: add a checkbox row "Limit to my thread library" that, when checked, restricts the quantization centroids to the closest match in the user's BROTHER_PR10_COLORS (or custom library, once the thread-library-CRUD issue is implemented).
Performance: cache the downsampled source bitmap; only re-run k-means on slider change. Reuse the canvas's existing imageSmoothingEnabled for the downsample.

Suggested file structure

New helper: src/lib/color-quantize.ts — quantizeImage(imageData: ImageData, k: number): { centroids: string[], assignments: Uint8Array }
New component: src/components/workspace/ColorPreview.tsx — renders the preview canvas
New tests: src/lib/color-quantize.test.ts, src/components/workspace/ColorPreview.test.tsx

Severity

Medium. Not a bug — the digitize flow works. But it's a real UX gap that affects every digitize attempt. The user wastes 3-5 seconds per "wrong sensitivity" attempt; a power user iterating to find the right level could waste 30+ seconds.

Discovered by

User-story walkthrough (round 4) — observing the Auto-Digitize flow as a user.

#115 / #117 / #118 (closed) — Auto-Digitize Settings panel half-wired; not the same as preview, but adjacent (the panel where this preview would live).
#99 (closed) — paletteIndexForColor coverage; the round-trip logic that a palette-constrained quantizer would need.
#98 (closed) — paletteIndexForColor returns wrong index for non-adjacent duplicate-color regions; the quantizer would call into this.

## Finding The Workspace's "Color Sensitivity" slider (in the right panel, under Auto-Digitize Settings) maps to a `maxColors: 1–10` parameter sent to the digitize service. The service quantizes the uploaded image server-side. **There is no client-side preview of what the quantized result will look like before the user commits to "Run Auto-Digitize"** — they have to wait ~3 seconds for the API call, see the result, and if it's wrong, change the slider and re-digitize the whole image. ## Where - Slider source: `src/components/workspace/RightPanel.tsx` (the Auto-Digitize Settings section, somewhere around line 200 — the existing test `RightPanel.test.tsx:200+` references `colorSensitivity`). - Service call: `src/lib/digitize-adapters.ts:32` (the `maxColors` mapping is documented in the file's comment). - Service: `POST /v1/digitize` on the easystitch-service. The relationship `colorSensitivity 0–100 → maxColors 1–10` is a linear map (verified in `src/lib/digitize-adapters.test.ts:119`). ## Why now Every other "see before you commit" surface in the app is live: - Hoop size dropdown changes the hoop outline on the canvas immediately - Fabric / stabilizer dropdowns update labels - Render scale changes the canvas resolution immediately But color sensitivity requires a full API roundtrip and a re-quantization. The user is picking blind. This is also the entry point to a missing capability: there's no way to constrain the design to "use only the colors I have on my spool rack." A user with 5 spools who wants to digitize a 12-color design has no UI to say "use only these 5 colors and find the closest match." ## Suggested fix shape Add a client-side quantization preview that runs synchronously on slider change: 1. **Implementation**: client-side color quantization of the uploaded image's pixels. A simple approach: - Downsample the image to ~100×100 max (so the quantization is fast, <50ms) - K-means with `k = maxColors` (1-10) in RGB or Lab space - Render the quantized result to a small preview canvas (e.g. 200×200) inside the right panel, next to the slider 2. **Preview canvas**: shows the quantized result live as the slider moves. ~50ms re-quantize on every slider change is acceptable. 3. **Commit**: only when the user clicks "Run Auto-Digitize" does the actual API call fire, with the same `maxColors` value the preview used. 4. **Optional — palette constraint**: add a checkbox row "Limit to my thread library" that, when checked, restricts the quantization centroids to the closest match in the user's `BROTHER_PR10_COLORS` (or custom library, once the thread-library-CRUD issue is implemented). 5. **Performance**: cache the downsampled source bitmap; only re-run k-means on slider change. Reuse the canvas's existing `imageSmoothingEnabled` for the downsample. ## Suggested file structure - New helper: `src/lib/color-quantize.ts` — `quantizeImage(imageData: ImageData, k: number): { centroids: string[], assignments: Uint8Array }` - New component: `src/components/workspace/ColorPreview.tsx` — renders the preview canvas - New tests: `src/lib/color-quantize.test.ts`, `src/components/workspace/ColorPreview.test.tsx` ## Severity Medium. Not a bug — the digitize flow works. But it's a real UX gap that affects every digitize attempt. The user wastes 3-5 seconds per "wrong sensitivity" attempt; a power user iterating to find the right level could waste 30+ seconds. ## Discovered by User-story walkthrough (round 4) — observing the Auto-Digitize flow as a user. ## Related - #115 / #117 / #118 (closed) — Auto-Digitize Settings panel half-wired; not the same as preview, but adjacent (the panel where this preview would live). - #99 (closed) — `paletteIndexForColor` coverage; the round-trip logic that a palette-constrained quantizer would need. - #98 (closed) — `paletteIndexForColor` returns wrong index for non-adjacent duplicate-color regions; the quantizer would call into this.