Color Atlas Gen User Guide

Color Atlas Gen creates an atlas object with meta, samples and optional top-level scientific layers such as spectral, lighting, time_cycle, atmosphere and astronomy. The generated JSON can power Auric Artisan Color Library, which loads a compact index and detail files built from /data/color-atlas/color-atlas.json.

The folder name is spelled color-altas-gen in the repository. The package name is cosmic-color-engine, and the CLI command name is cosmic-engine.

Use it when you need repeatable color research fixtures, design-system color datasets, accessibility-enriched palettes, ML label examples, or a refreshed Color Library data source.

Work from the package directory:

cd tool/color-altas-gen
npm install

Generate from a config file:

node src/cli.js generate --config examples/library-full.json --output ../../data/color-atlas

Generate with CLI flags:

node src/cli.js generate --samples 5000 --spectral --accessibility --formats JSON,CSV --output output

Useful CLI options include --config, --output, --samples, --dimension, --spectral, --lighting, --time-cycle, --atmosphere, --astronomy, --accessibility, --art, --ai-labels, --formats, --compression, --workers and --gpu.

The master config is called ColorUniverseConfig. The loader merges configuration layers in this order:

1. Defaults: src/config/defaults.js.
2. Config file: JSON, YAML or YML loaded from --config.
3. CLI flags: values produced by parseCLIOverrides().
4. API options: direct programmatic overrides.

Nested objects are deep-merged. Arrays are replaced, not concatenated. Validation uses Ajv and src/config/schema.js, so invalid dimensions, unknown export formats and invalid scattering models fail before generation begins.

dataset.sample_count controls how many random RGB samples are generated. dimension, spatial_resolution, time_steps and include_neighbors are accepted in config and logged by the dataset engine; the current generator produces random RGB samples with id, r, g and b.

The color-space engine can add:

• hex: 6-digit web hex.
• hsl: hue, saturation and lightness.
• xyz: CIE XYZ using D65 sRGB matrices.
• lab: CIE Lab from XYZ.
• oklab and oklch: perceptual OKLab and polar OKLCH values.
• cmyk: subtractive CMYK approximation when enabled.

The repository Color Library dataset at data/color-atlas/color-atlas.json uses 8,192 samples with color spaces, perception, accessibility, art and AI labels enabled.

These layers are top-level atlas sections, not per-sample fields. They are useful when the atlas should teach or compare physical color phenomena alongside generated color samples.

Sample enrichment happens after color spaces are attached.

• Perception: luminance, OKLab chroma, vividness, Delta E 1976, 1994, 2000 and a rough perceptual-uniformity score.
• Accessibility: contrast on white, contrast on black, AA and AAA booleans and optional color blindness simulations.
• Art: emotion label, art movement, complementary, analogous and triadic hue relationships and design tag.
• AI labels: arousal and valence, mood category and design usage category.

Perception needs the required upstream color-space values. For example, Delta E requires Lab, OKLab chroma requires OKLab, and vividness requires HSL.

Start small. The generator allocates an array of samples, so very large sample counts require serious memory planning. Do not run the billion-sample example casually on a development laptop.

Use createColorUniverse() for the shortest path:

import { createColorUniverse } from "./src/index.js";

const atlas = await createColorUniverse(
  {
    dataset: { sample_count: 1000 },
    accessibility: {
      wcag_contrast: true,
      simulate_color_blindness: true,
      types: ["Protanopia", "Deuteranopia", "Tritanopia"]
    },
    export: { formats: ["JSON"] }
  },
  { outputDir: "./output" }
);

Use the lower-level flow when you want explicit config control:

import { resolveConfig, validateConfig, generateColorUniverse } from "./src/index.js";

const config = resolveConfig({
  filePath: "examples/researcher.yaml",
  cliOverrides: { dataset: { sample_count: 500 } },
  apiOptions: { export: { formats: ["JSON", "CSV"] } }
});

validateConfig(config);
const atlas = await generateColorUniverse(config, { outputDir: "./output" });

Export formats are controlled by export.formats.

• JSON: writes color-atlas.json with streaming sample output.
• CSV: writes color-atlas.csv from flattened sample rows.
• Parquet: writes color-atlas.parquet.stub until native dependencies are added.
• Arrow: writes color-atlas.arrow.stub until Arrow IPC support is added.

export.compression accepts none, gzip, zstd and lz4, but the current exporter logs the setting and does not compress the output. Plan storage and transfer size accordingly.

• Use small sample counts while testing config shape and export fields.
• Enable only the engines needed for the downstream viewer or research task.
• Keep Lab, OKLab and HSL enabled when you depend on perception, art or AI labels.
• Regenerate data/color-atlas/color-atlas.json deliberately, then rerun scripts/generate-color-atlas-index.mjs, because the Color Library reads the index and detail files built from it.
• Remember that the base dataset is random RGB, so outputs are not deterministic unless a future seed option is added.
• Treat performance settings as config metadata in the current implementation; GPU, workers and clusters are not yet wired into generation.
• Run the package tests and the site validation suite before committing a regenerated atlas.

For implementation details, see the Color Atlas Gen Developer Reference.