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).
| Column | Type | Required | Description |
|---|---|---|---|
name | string | yes | Color name as collected from observers (free-form English). |
hex | string | yes | Representative sRGB hex (e.g. '#acc2d9'). |
R | int | yes | |
G | int | yes | |
B | int | yes | |
L | float | no | CIELAB L* under D65 (computed from hex). |
a | float | no | |
b | float | no |
Invariants
- hex must parse to (R,G,B); R,G,B values must match.
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.
| Column | Type | Required | Description |
|---|---|---|---|
filename | string | yes | |
size_bytes | int | yes | |
category | string | yes | Coarse grouping (e.g. "mean appearance estimates", "colorimetric reference data"). |
lines | int | no | Row count of the raw file, if applicable. |
Invariants
- Every listed filename must exist in raw/.
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).
| Column | Type | Required | Description |
|---|---|---|---|
chip_id | string | yes | Stable identifier for the chip. |
hue_id | string | yes | Hue family label (e.g. "R", "Y", "10R" for Munsell-style). |
L | float | yes | |
a | float | yes | |
b | float | yes | |
C | float | no | Chroma. Computed sqrt(a^2 + b^2) if absent. |
h | float | no | Hue angle in degrees [0, 360). Computed if absent. |
illuminant | string | no |
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.
| Column | Type | Required | Description |
|---|---|---|---|
pair_id | string | yes | |
experiment_id | string | yes | Identifier for the experimental condition (e.g. "Breneman_Exp_1"). |
color_name | string | no | Sample label (Illuminant, Gray, Red, Skin, etc.). |
u_t | float | yes | CIE u' chromaticity of the TEST stimulus (under test illuminant). |
v_t | float | yes | CIE v' chromaticity of the TEST stimulus. |
u_m | float | yes | CIE u' chromaticity of the MATCHED stimulus (under reference illuminant). |
v_m | float | yes | CIE v' chromaticity of the MATCHED stimulus. |
sigma_u | float | no | Inter-observer scatter on u', if reported. |
sigma_v | float | no | Inter-observer scatter on v', if reported. |
illuminant_test | string | no | Illuminant under which the test stimulus was viewed. |
illuminant_reference | string | no | Illuminant under which the matched stimulus was viewed. |
Invariants
- A perfectly accurate chromatic adaptation transform maps (u_t, v_t) → (u_m, v_m) under the given illuminant change.
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).
| Column | Type | Required | Description |
|---|---|---|---|
pair_id | string | yes | |
dv | float | no | Visual difference score. Column name may differ per dataset (e.g. dv_CLAB, dv_DE2000) — see meta.yaml for the canonical column. |
DE_00 | float | no | CIEDE2000 between the two chips (often present). |
Invariants
- All delta values should be non-negative.
- If multiple dv conventions are reported (CLAB vs DE2000), they should be within a few percent of each other.
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).
| Column | Type | Required | Description |
|---|---|---|---|
point_id | string | yes | |
L | float | yes | |
a | float | yes | |
b | float | yes | |
x | float | no | CIE xyY x chromaticity (if dataset is xyY-native). |
y | float | no | |
Y | float | no | |
illuminant | string | no |
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.
| Column | Type | Required | Description |
|---|---|---|---|
center_id | string | yes | Stable identifier for the chromaticity center. |
x_c | float | yes | CIE x chromaticity coordinate of the ellipse center. |
y_c | float | yes | CIE y chromaticity coordinate of the ellipse center. |
a | float | yes | Semi-major axis length (in the same chromaticity units as x, y, typically ×10⁻³). |
b | float | yes | Semi-minor axis length. |
theta_deg | float | yes | Rotation angle of the semi-major axis from the +x direction, in degrees. |
Y | float | no | Optional reference luminance factor (Y). |
illuminant | string | no |
Invariants
- a >= b > 0
- 0 <= theta_deg < 180 (modulo 180 — ellipse orientation is rotation-symmetric)
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).
| Column | Type | Required | Description |
|---|---|---|---|
pair_id | string | yes | Stable identifier for the pair, unique within the dataset. |
L1 | float | yes | CIE L* of color 1. |
a1 | float | yes | CIE a* of color 1. |
b1 | float | yes | CIE b* of color 1. |
L2 | float | yes | |
a2 | float | yes | |
b2 | float | yes | |
dv | float | yes | Visual 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. |
weight | float | no | Per-pair weight. Typical sources: nstar (effective observer count) or raw observer count. NaN means unweighted. See meta.yaml `weight_meaning`. |
sub_dataset | string | no | Sub-experiment label within a composite dataset, e.g. "BFD-P", "LEEDS", "RIT-DuPont", "WITT" for COMBVD; "table1"/"table2" for MacAdam 1974. |
illuminant | string | no | Illuminant for THIS pair if it differs from the dataset-level default (e.g. mixed-illuminant collections). Leave empty to inherit meta.yaml. |
Invariants
- If dv is reported in ΔE units, |dv| should be within a few DE units for threshold experiments and within ~50 DE for suprathreshold.
- Catch trials (identical colors) should have dv ≈ 0; pairs with L1==L2 and a1==a2 and b1==b2 but dv > 0 indicate sentinel issues.