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 exhaustiveO(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_FRACTIONof the set.chunk_size (int | None) – Candidates scored per block, bounding peak memory to
O(chunk_size * N)instead ofO(k * N).None(the default) sizes the block fromMEDOID_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-1and 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: