christian/smk-playground
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
smk-playground/docs/IMPLEMENTATION_PLAN.md

4.8 KiB
Raw Permalink Blame History

Implementation Plan

Milestone 0 — Source reconnaissance + repository foundation

  • verify Python package/CLI setup
  • detect both expected source files:
    • data/raw/smk_all_da.json
    • data/raw/smk_all_en.json
  • inspect actual top-level JSON structures without guessing
  • compute bytes + SHA-256
  • count/summarize records with bounded memory
  • compare DA/EN identity sets
  • write source-manifest.json
  • document any structural surprises

Done when we understand the actual dumps well enough to implement the parser from evidence rather than assumptions.

Milestone 1 — Streaming source loading + canonical schema

  • implement bounded-memory loader for actual observed structure
  • join DA/EN by object_number, never by row position
  • preserve localized text where useful
  • map stable non-language fields into canonical columns
  • preserve source provenance/disagreements
  • parse physical dimensions/units defensively

Done when a representative fixture/sample becomes deterministic canonical rows.

Status: source loading and pre-canonical audits complete. Stable source-row identity, lossless logical Parquet, duplicate taxonomy, dimension vocabulary, palette/visual quality and DA/EN precedence recommendations are documented. Canonical entities are implemented in Milestone 2 without collapsing duplicate object_number groups.

Milestone 2 — Canonical entities + first analyzable corpus

  • pair language rows only by SMK id
  • preserve object_number as non-unique grouping metadata
  • canonicalize fields with explicit provenance and conflicts
  • resolve image bundles atomically
  • preserve and normalize dimension observations without choosing conflicts
  • freeze smk-public-visual-v1 with machine-readable exclusion reasons

Status: complete. See CANONICALIZATION.md and CORPUS_V1.md. Visual/colour feature extraction has not started.

Milestone 3 — Deterministic per-artwork visual features

Implemented for frozen smk-public-visual-v1:

  • perceptual centroid
  • explicitly uniform bulk-palette weights and duplicate-colour handling
  • sRGB -> OKLab -> OKLCH with achromatic hue semantics
  • palette entropy/effective size with documented uniform-weight limitation
  • palette spread
  • weighted lightness/chroma variation
  • hue concentration
  • SMK visual fields + provenance
  • physical/image geometry + logs

Status: complete. Raw features remain corpus-independent; no corpus normalization or similarity is implemented. See FEATURE_EXTRACTION_V1.md and FEATURE_EXAMPLES.md.

Milestone 4 — Corpus statistics + normalization

Status: complete. Profile every candidate scalar over frozen smk-public-visual-v1, preserve raw OKLab semantics and missingness, generate robust-01/midrank-percentile/robust-z variants, add log aspect and circular-hue diagnostics, and publish separate unweighted candidate families. See NORMALIZATION_V1.md and FEATURE_VECTOR_V1.md.

Milestone 5 — Pilot build

Status: complete as deterministic exact similarity. Three separately versioned profiles use sample-calibrated component scales, explicit weights, shared-component missingness and explainable contributions. QA examples, stability diagnostics and performance measurements are published in SIMILARITY_V1.md and SIMILARITY_EXAMPLES.md.

Milestone 6 — Similarity preparation

Status: enrichment-backed weighted color layer implemented separately from bulk v1. It provides a resumable append-only source cache, weighted palettes/features v2, bulk/enrichment diagnostics and an exact palette-transport similarity profile. See ENRICHMENT_V1.md, WEIGHTED_PALETTES_V1.md and WEIGHTED_SIMILARITY_V1.md.

Milestone 7 — First usable application + sonification

Status: complete. A compact read-only web catalog feeds one FastAPI + React service with search, artwork detail, existing exact similarity profiles, explicit cached weighted similarity, and three versioned deterministic browser-audio mappings. See SONIFICATION_V1.md and WEB_UI_V1.md.

Milestone 8 — Similarity

Implement separate profiles rather than one magic similarity score:

  • color
  • visual
  • composition

Use fast feature-vector candidate retrieval followed optionally by weighted-palette optimal-transport reranking. Do not precompute all pairs.

Milestone 9 — Art Tone v1

Implement versioned, explainable sonification mapping separate from objective features.

Initial mapping:

  • centroid hue -> chromatic pitch class
  • physical area percentile -> register
  • chroma -> velocity/richness
  • lightness -> timbral brightness
  • palette entropy -> complexity
  • contrast -> attack
  • hue concentration -> tonal purity

Emit exact inputs alongside every mapped result.

Milestone 10 — Exploration

Only after Dataset v1 is trustworthy, start experimental interfaces/notebooks/apps:

  • nearest-neighbour browser
  • colour-space explorer
  • timelines
  • artist palette fingerprints
  • mosaics
  • sonification player