Cinema Color
Intelligence

# cinema_extract.py — per-frame palette clustering
import cv2
import numpy as np
from sklearn.cluster import KMeans
from pydantic import BaseModel, validator

class PaletteRecord(BaseModel):
    film_id:    str
    scene_id:   int
    frame_ts:   float
    centroids:  list[dict]   # [{L, a, b, weight}, ...]

    @validator('centroids')
    def weights_sum_to_one(cls, v):
        total = sum(c['weight'] for c in v)
        if abs(total - 1.0) > 0.001:
            raise ValueError(f'Weights sum to {total:.4f}, expected 1.0')
        return v

def extract_palette(frame_bgr: np.ndarray, k: int = 5) -> list[dict]:
    # Downsample to 64x36 before clustering
    small = cv2.resize(frame_bgr, (64, 36))
    lab   = cv2.cvtColor(small, cv2.COLOR_BGR2LAB)
    pixels = lab.reshape(-1, 3).astype(np.float32)

    km = KMeans(n_clusters=k, n_init=10, tol=1e-4, random_state=42)
    km.fit(pixels)

    counts = np.bincount(km.labels_, minlength=k)
    weights = counts / counts.sum()

    return sorted([
        {'L': float(c[0]), 'a': float(c[1]), 'b': float(c[2]),
         'weight': float(weights[i])}
        for i, c in enumerate(km.cluster_centers_)
    ], key=lambda x: -x['weight'])

-- mart/director_palette_signature.sql
WITH scene_agg AS (
  SELECT
    film_id,
    scene_id,
    AVG(
      CASE WHEN
        -- warm: reds/oranges/yellows (hue angle 0-60 + 300-360)
        (ATAN2(b, a) * 180.0 / PI() + 360) % 360
          BETWEEN 0 AND 60
        OR (ATAN2(b, a) * 180.0 / PI() + 360) % 360 > 300
      THEN weight_fraction ELSE 0
    END
    ) AS warm_frac,
    AVG(
      CASE WHEN
        -- cool: blues/cyans (hue angle 180-270)
        (ATAN2(b, a) * 180.0 / PI() + 360) % 360
          BETWEEN 180 AND 270
      THEN weight_fraction ELSE 0
    END
    ) AS cool_frac,
    -SUM(weight_fraction * LN(weight_fraction + 1e-9)) AS palette_entropy
  FROM frame_clusters
  GROUP BY film_id, scene_id
)
SELECT
  d.director_id,
  AVG(s.warm_frac)        AS mean_warm,
  AVG(s.cool_frac)        AS mean_cool,
  1 - AVG(s.warm_frac)
      - AVG(s.cool_frac)  AS mean_neutral,
  AVG(s.palette_entropy)  AS mean_entropy
FROM scene_agg s
JOIN film_metadata f ON s.film_id = f.film_id
JOIN director_lookup d ON f.director_id = d.director_id
GROUP BY d.director_id
ORDER BY mean_warm DESC