phenotypic.util.candidate_medoid#

phenotypic.util.candidate_medoid(lab_points: numpy.ndarray, k: int = 256, chunk_size: int | None = None) → MedoidResult[source]#

The delta-E 2000 medoid of lab_points, found deterministically.

Scores only the k pixels nearest the cloud’s Lab geometric median, each against every pixel, and returns the best. Cost is O(k * n) rather than the exhaustive O(n^2), and no pixel is ever sampled at random.

Why not medoid_ciede2000(): it selects the medoid from a seeded subsample of 1000 pixels, and re-drawing that seed moves the answer by ~0.12 delta-E 2000 (worst 0.81) – larger than the difference between the medoid and the geometric median it is chosen over. Raising the cap does not fix it affordably: selection is quadratic, costing ~41 s per 24-tile frame at a 4000-pixel cap, while the seed spread only falls from ~0.32 to ~0.25 delta-E 2000. Restricting the candidates instead removes the randomness entirely and reproduces the exhaustive medoid exactly on unimodal tile clouds.

Parameters:
  • lab_points (numpy.ndarray) – (N, 3) CIE Lab pixels.

  • k (int) – Number of candidates to score. Widened once, automatically, if the winner lands past CANDIDATE_EDGE_FRACTION of the set.

  • chunk_size (int | None) – Candidates scored per block, bounding peak memory to O(chunk_size * N) instead of O(k * N). None (the default) sizes the block from MEDOID_MEMORY_BUDGET_BYTES: max(1, min(64, budget // (N * MEDOID_BYTES_PER_PAIR))). The result is bit-identical for every block size – each candidate’s total is summed over the same full row – so this bounds memory and nothing else. Below one candidate per block the floor is one (1, N) row, ~265 B per pixel.

Returns:

A MedoidResult. For an empty input the index is -1 and the coordinate is all-NaN; for a single pixel it is that pixel.

Raises:

ValueError – If lab_points is not 2-D, or k or chunk_size is not positive.

Return type:

MedoidResult