Schemas

Every canonical CSV follows one of these schemas.

Each meta.yaml declares which schema its canonical.csv uses. Schemas live in the repo at schemas/<name>.yaml.

color_names

Color-naming dataset: each row maps a natural-language color name to a representative RGB swatch. Used for evaluating color appearance models on language/perceptual category boundaries, and as a sanity test for color-space hue uniformity (chips with similar names should be near each other in a uniform space).

ColumnTypeRequiredDescription
namestringyesColor name as collected from observers (free-form English).
hexstringyesRepresentative sRGB hex (e.g. '#acc2d9').
Rintyes
Gintyes
Bintyes
LfloatnoCIELAB L* under D65 (computed from hex).
afloatno
bfloatno

Invariants

compound_legacy

Compound legacy dataset — multiple original files with mixed per-file schemas that are not merged into a single canonical table. The `canonical.csv` is an INDEX of the raw files (filename, size, category) rather than a flat data table. Users read individual raw files from `raw/` according to their experimental needs. This schema exists because some classic color-appearance datasets (LUTCHI, certain CAM corpus data) ship as collections of small files whose per-file schemas only make sense in the context of the source paper. Merging them into one canonical CSV would erase the experimental structure that gives each file its meaning.

ColumnTypeRequiredDescription
filenamestringyes
size_bytesintyes
categorystringyesCoarse grouping (e.g. "mean appearance estimates", "colorimetric reference data").
linesintnoRow count of the raw file, if applicable.

Invariants

constant_hue

Standard schema for constant-hue datasets. Each row = one chip on a perceptually constant-hue line or surface. Used to test hue uniformity of a color space (chips with the same hue_id should fall on a straight line through the achromatic axis in a perceptually uniform space).

ColumnTypeRequiredDescription
chip_idstringyesStable identifier for the chip.
hue_idstringyesHue family label (e.g. "R", "Y", "10R" for Munsell-style).
Lfloatyes
afloatyes
bfloatyes
CfloatnoChroma. Computed sqrt(a^2 + b^2) if absent.
hfloatnoHue angle in degrees [0, 360). Computed if absent.
illuminantstringno

corresponding_colors

Corresponding-colors data for chromatic-adaptation research. Each row pairs a "test" stimulus (viewed under one illuminant) with the "matched" stimulus (viewed under another illuminant) that an observer reports as the same color. Optional fields carry observer scatter and per-observer deviations when reported in the source.

ColumnTypeRequiredDescription
pair_idstringyes
experiment_idstringyesIdentifier for the experimental condition (e.g. "Breneman_Exp_1").
color_namestringnoSample label (Illuminant, Gray, Red, Skin, etc.).
u_tfloatyesCIE u' chromaticity of the TEST stimulus (under test illuminant).
v_tfloatyesCIE v' chromaticity of the TEST stimulus.
u_mfloatyesCIE u' chromaticity of the MATCHED stimulus (under reference illuminant).
v_mfloatyesCIE v' chromaticity of the MATCHED stimulus.
sigma_ufloatnoInter-observer scatter on u', if reported.
sigma_vfloatnoInter-observer scatter on v', if reported.
illuminant_teststringnoIlluminant under which the test stimulus was viewed.
illuminant_referencestringnoIlluminant under which the matched stimulus was viewed.

Invariants

delta_only

Pair dataset where the source publication reports only Δ (delta) values between paired colors, without the endpoint Lab coordinates. Used when the underlying chip coordinates are not directly linkable to pair rows in the original source (e.g. He 2022 — chips and pair-Δ values live in separate sheets with no shared chip-pair index).

ColumnTypeRequiredDescription
pair_idstringyes
dvfloatnoVisual difference score. Column name may differ per dataset (e.g. dv_CLAB, dv_DE2000) — see meta.yaml for the canonical column.
DE_00floatnoCIEDE2000 between the two chips (often present).

Invariants

gamut_boundary

Standard schema for real-world gamut boundary datasets. Each row = one boundary point in CIELAB (or sometimes xyY) marking the outer surface of an empirical color volume (e.g. Pointer's real surface colors).

ColumnTypeRequiredDescription
point_idstringyes
Lfloatyes
afloatyes
bfloatyes
xfloatnoCIE xyY x chromaticity (if dataset is xyY-native).
yfloatno
Yfloatno
illuminantstringno

jnd_ellipses

Just-noticeable-difference (JND) discrimination-threshold ellipse data. Each row is one ellipse: a chromaticity center (x_c, y_c) plus the semi-major axis (a), semi-minor axis (b), and rotation angle (theta) of the discrimination ellipse around that center. Unlike pair_diff, the data is one ellipse per chromaticity, not one pair per row — the ellipse IS the JND distribution.

ColumnTypeRequiredDescription
center_idstringyesStable identifier for the chromaticity center.
x_cfloatyesCIE x chromaticity coordinate of the ellipse center.
y_cfloatyesCIE y chromaticity coordinate of the ellipse center.
afloatyesSemi-major axis length (in the same chromaticity units as x, y, typically ×10⁻³).
bfloatyesSemi-minor axis length.
theta_degfloatyesRotation angle of the semi-major axis from the +x direction, in degrees.
YfloatnoOptional reference luminance factor (Y).
illuminantstringno

Invariants

pair_diff

Standard schema for color-difference pair datasets. One row = one pair of colors with an associated visual-difference score from a psychophysical experiment. All colors are in CIELAB under the dataset's declared illuminant (see meta.yaml).

ColumnTypeRequiredDescription
pair_idstringyesStable identifier for the pair, unique within the dataset.
L1floatyesCIE L* of color 1.
a1floatyesCIE a* of color 1.
b1floatyesCIE b* of color 1.
L2floatyes
a2floatyes
b2floatyes
dvfloatyesVisual difference score reported by observers. Units and scale are dataset-specific (see meta.yaml `dv_units`). For most published datasets this is in DE units; for HumanFB it is a 0-100 slider scale.
weightfloatnoPer-pair weight. Typical sources: nstar (effective observer count) or raw observer count. NaN means unweighted. See meta.yaml `weight_meaning`.
sub_datasetstringnoSub-experiment label within a composite dataset, e.g. "BFD-P", "LEEDS", "RIT-DuPont", "WITT" for COMBVD; "table1"/"table2" for MacAdam 1974.
illuminantstringnoIlluminant for THIS pair if it differs from the dataset-level default (e.g. mixed-illuminant collections). Leave empty to inherit meta.yaml.

Invariants