Color Atlas Gen Developer Reference

tool/color-altas-gen/package.json defines cosmic-color-engine, version 1.0.0, ESM type: module, with src/index.js as the main entry and cosmic-engine mapped to src/cli.js.

Dependencies are intentionally small: commander for CLI parsing, js-yaml for YAML config files and ajv for JSON Schema validation. The package has no build step.

Public exports from src/index.js are DEFAULT_CONFIG, CONFIG_SCHEMA, resolveConfig, loadConfigFile, deepMerge, validateConfig, generateColorUniverse and createColorUniverse.

src/cli.js defines the cosmic-engine generate command with Commander. parseCLIOverrides(opts) converts flags into partial config objects.

The action resolves config from file plus CLI overrides, validates it and calls generateColorUniverse(config, { outputDir: opts.output }). Errors are printed and exit with status 1.

DEFAULT_CONFIG defines the baseline: one million samples, 3D dataset metadata, RGB, HEX, HSL, Lab, OKLab, OKLCH and XYZ enabled, perception brightness/chroma/Delta E 2000 enabled and JSON export.

loadConfigFile(filePath) reads JSON, YAML or YML. deepMerge(target, source) recursively merges objects, replaces arrays and leaves the target object untouched. resolveConfig() applies defaults, file config, CLI overrides and API options in that priority order.

CONFIG_SCHEMA rejects unknown top-level keys and unknown nested keys because each section uses additionalProperties: false. It validates dimensions, wavelength ranges, scattering model names, CVD type names, export formats and compression labels.

generateColorUniverse(config, { outputDir }) in src/orchestrator.js is the central pipeline:

1. Generate base samples with generateDataset().
2. Attach requested color spaces with computeColorSpaces().
3. Optionally compute spectral data.
4. Optionally compute lighting data.
5. Optionally compute time-cycle data.
6. Optionally compute atmosphere data.
7. Optionally compute astronomy data.
8. Optionally enrich samples with perception metrics.
9. Optionally enrich samples with accessibility metrics.
10. Optionally enrich samples with art metadata.
11. Optionally enrich samples with AI labels.
12. Assemble the atlas and export results.

The returned atlas always includes meta and samples. Optional top-level sections are attached only when their engines run.

generateDataset(config) creates sample_count random RGB records shaped as { id, r, g, b }. The current generator does not seed randomness and does not yet use dimension, spatial resolution, time steps or neighbor metadata beyond logging.

computeColorSpaces(samples, config) shallow-copies each sample and conditionally adds HEX, HSL, XYZ, CIE Lab, OKLab, OKLCH and CMYK. Important helpers include sRGB inverse companding, the D65 RGB-to-XYZ matrix, CIE Lab f(t) conversion, OKLab LMS matrices and basic CMYK decomposition.

Downstream engines assume their upstream color spaces exist. For example, Delta E metrics need Lab, OKLab chroma needs OKLab and art or AI label selection uses HSL hue and lightness.

perception.js can add relative luminance, OKLab chroma, HSL vividness, Delta E 1976, Delta E 1994, simplified Delta E 2000 and a rough perceptual-uniformity score based on distance from the L* 50 midpoint.

accessibility.js adds WCAG contrast against white and black, AA and AAA booleans and optional Protanopia, Deuteranopia and Tritanopia simulation matrices.

art.js deterministically maps hue and lightness to emotion, art movement, design tags and palette harmony hue relationships. aiLabels.js adds arousal/valence, mood categories and design usage labels from deterministic hue/lightness formulas.

exportResults(atlas, config, outputDir) creates the output directory and writes every requested format.

compression and chunk_size are logged and validated. Actual gzip, zstd and lz4 compression is not implemented in the current exporter.

The browser Color Library (library/color/color-library.js) loads /data/color-atlas/atlas-index.json and sharded /data/color-atlas/detail/ files, which scripts/generate-color-atlas-index.mjs builds from /data/color-atlas/color-atlas.json. That JSON currently contains 8,192 generated samples with color spaces, perception, accessibility, art metadata and AI labels. If the generated schema changes, regenerate the index and update the browser viewer and docs together.

The package test suite uses Node's built-in node:test. It covers config merge, schema validation, engine behavior and integration generation. The integration tests write to test_output_integration and clean it up afterward.

cd tool/color-altas-gen
npm test

• Keep README.md, examples, schema and this documentation aligned when config fields change.
• When adding an engine, export it from src/engines/index.js, wire it in the orchestrator and add config schema fields.
• When adding a per-sample field, update CSV flattening expectations and the Color Library viewer if it displays that field.
• When making dataset generation deterministic, document seed behavior and treat it as a data-version change.
• When implementing real compression, update exporter docs and tests for gzip, zstd and lz4 artifacts.
• When implementing Parquet or Arrow, replace stub tests with real file validation.
• Run npm test in tool/color-altas-gen and the root site validation after docs or generated discovery files change.

For workflow-level usage, see the Color Atlas Gen User Guide.