Color Spaces (clrviz)

Color Spaces is a modern web tool that helps cinematographers, colorists, DI and VFX teams compare color gamuts with real-world data. The interface layers selectable color-space triangles over an interactive chromaticity diagram—defaulting to CIE 1931 xy with an optional CIE 1976 u'v' projection—making it easy to see overlaps, out-of-gamut risks, and white-point offsets at a glance.

Highlights

• Interactive chromaticity viewer implemented in-house with WebGL canvas + SVG overlays, custom zoom/pan, hover outlines, and tone-curve-aware tooltips, plus a quick toggle between CIE 1931 xy and CIE 1976 u'v'.
• GPU-accelerated LUT preview lives at /lut, applying .cube 3D LUTs to local stills with a WebGL2 pipeline (and a packed WebGL fallback) entirely client-side.
• Curated catalog of 70+ color spaces generated from the colour-science dataset with manual aliases and tone-curve metadata.
• Fast multi-select & search sorted by industry adoption, complete with disabled entries for profiles that lack primaries (e.g. PQ, HLG). A clear button empties the active list instantly.
• Adaptive theming keeps the middle-grey aesthetic by default while offering a light-mode toggle for bright environments.
• Responsive layout introduces a tablet-first (768px) breakpoint so the sidebar, diagram, and detail cards collapse gracefully on smaller viewports while maintaining balanced gutters.
• Gamut quick-reference cards showing high-precision xy pairs plus linked tone curve information for each active space.
• ACES AP naming clarifies gamuts as AP0/AP1 with the original encodings noted in brackets (e.g. ACES AP1 (ACEScct)).
• Legend-aware exports so downloaded diagrams match the viewport clipping and include a colour-space key for offline sharing.
• Feedback workflow that captures product notes via a modal, ready to persist to Azure Table Storage.
• Performance-focused UI with Next.js 15, Tailwind 4, and subtle transitions on a cinematic middle-grey palette. The Planckian locus is opt-in to keep the default view clean.
• Session persistence remembers your active colour spaces, Planckian locus preference, and diagram zoom across reloads.
• Configurable chromaticity zoom starts two steps out from the base scale; adjust DEFAULT_ZOOM_SCALE in src/components/chromaticity/chromaticityDiagram.tsx to change the initial framing.

Tech Stack

• Next.js 15 (App Router, Turbopack)
• React 19 with Tailwind CSS 4
• Custom chromaticity renderer (WebGL + SVG) inspired by react-cie-1931
• Auto-generated color-space data via colour-science Python package
• Vitest + Testing Library for unit tests
• Azure Static Web Apps workflow, optional Azure Table Storage persistence, optional Docker image
• Deployment runtime locked to Node.js 20 via staticwebapp.config.json

Getting Started

Prerequisites

• Node.js 20+
• npm 10+

Installation & local development

npm install
npm run generate:color-spaces   # refresh the catalogue (idempotent)
npm run dev

The dev server runs on http://localhost:3000 with hot refresh. The chromaticity viewer needs a browser that supports WebGL.

Useful scripts

Command	Description
npm run dev	Start the Next.js dev server with Turbopack
npm run build	Production build with standalone output (used by Azure & Docker)
npm run start	Start the production server (after npm run build)
npm run lint	ESLint over the full project
npm run test	Run Vitest in CI mode
npm run test:watch	Run Vitest in watch mode
npm run generate:color-spaces	Rebuild src/data/generatedColorSpaces.ts from colour_rgb_colourspaces.json

LUT preview workspace

• Navigate to /lut to load a still image (PNG, JPEG, etc.) alongside a .cube 3D LUT. All processing stays on-device; files are never uploaded.
• WebGL2 is preferred and stores the LUT in a 3D texture. Browsers without WebGL2 fall back to a packed 2D layout with manual slice interpolation so the preview still functions.
• A background Web Worker parses .cube files (supporting LUT_3D_SIZE, DOMAIN_MIN, and DOMAIN_MAX) to keep the UI responsive. Large images are automatically resized so the longer edge is at most 2048px.
• The preview currently assumes uploaded images are already linear / scene-referred. Prep grabs in your grading tool before loading them so the LUT sees the same values you expect; sRGB conversion will return in a future update.

Colour-space data pipeline

• colour_rgb_colourspaces.json is a JSON export produced via the Python colour-science package (see scripts/generate-color-spaces.mjs).
• The generator script normalises names, attaches popularity heuristics, aliases, tone curves, and manually adds descriptive records for transfer-only standards.
• Run npm run generate:color-spaces whenever updating the JSON source or the generator logic.

Testing & quality gates

npm run lint
npm run test

Vitest is configured with Testing Library + JSDOM. GitHub Actions runs both linting and tests on every push/PR before deploying.

Deployment on Azure Static Web Apps

1. Provision an Azure Static Web App (Standard or Free) with Node 20 runtime.
2. In GitHub, set the secret AZURE_STATIC_WEB_APPS_API_TOKEN with the deployment token from the Azure portal.
3. (Optional) Create an Azure Storage account + Table named ColorSpaceRequests, then set:
   • AZURE_TABLE_CONNECTION_STRING (connection string for the storage account)
   • AZURE_TABLE_NAME (optional override, defaults to ColorSpaceRequests) Add them as GitHub secrets or Static Web Apps application settings.
4. Push to main – .github/workflows/deploy.yml will run quality checks, build the Next.js app, and upload artefacts via Azure/static-web-apps-deploy@v1. The default worker runtime is pinned to Node.js 20 through staticwebapp.config.json (platform.apiRuntime).

Feedback submission persistence

The API route app/api/request-color-space stores feedback submissions in Azure Table Storage when AZURE_TABLE_CONNECTION_STRING is provided. Without it, submissions still succeed but are only logged to the server console. Extend this route to push to Logic Apps, SendGrid, or Teams as needed.

Container image (optional)

A production-ready Dockerfile is included for Azure Container Apps, App Service, or local orchestration:

docker build -t clrviz .
docker run -p 3000:3000 clrviz

The build stage generates the color-space catalog and produces the Next.js standalone output, so the runtime image is slim and quick to start.

Architecture notes

• Data lives in src/data/generatedColorSpaces.ts and is consumed through src/lib/colorSpaces.ts.
• UI centres around ColorSpacesExperience, which handles search, selection, palette assignment, the chromaticity diagram, and the feedback modal.
• API is a single route for request submissions; any additional backend integrations can sit alongside it.
• Styling leans on Tailwind tokens and CSS variables to drive the middle-grey default, optional light theme, and shared accent states via --color-accent + per-theme variants (--color-accent-dark/--color-accent-light, default #A47864).

Telemetry & analytics

• Google Analytics loads in production builds via the root layout when NEXT_PUBLIC_GOOGLE_ANALYTICS_ID is set.
• Add a .env.local file with NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-CHMJYHNN47 (or your property ID) for local testing.
• CI builds the site before deploying (skip_app_build: true), so expose the same variable to GitHub Actions (e.g. repository secret or environment variable) and mirror it in Azure Static Web Apps configuration for runtime parity.
• Update src/app/layout.tsx if additional event tracking is required.

TODO & future enhancements

• Add opt-in UX and event-level telemetry around gamut comparisons for privacy-friendly analytics.
• Offer gamut-volume comparisons and intersection metrics.
• Support importing user-defined color spaces via JSON or OCIO files.
• Add localisation & unit tests for the feedback modal behaviour.
• Provide a public roadmap page instead of the placeholder Trello link.

Credits

• Color primaries sourced via colour-science (MIT).
• Chromaticity rendering adapted from react-cie-1931.
• Middle-grey inspiration from the Kodak 18% reference card.

---

Maintained with care for the color community. Contributions welcome – please open an issue or PR with ideas.