import numpy as np from typing import List, Tuple, Optional from .conflict import ( delta_e_cie76, delta_e_ciede2000, detect_conflicts, _achromatic_threshold, _rg_chroma_min, _rg_a_min, ) from .cvd_simulation import get_simulation_matrix # ── Direction orthogonal to the CVD confusion axis in (a*, b*) ─────────────── # For deutans, the confusion axis is v_c = [0.9139, 0.4062] (red-green collapse). # The orthogonal direction v_c_perp = [-0.4062, 0.9139] points along the blue-yellow # axis (intact S-cone pathway). Shifting conflicting colors along this axis creates # vivid chromatic separation in CVD simulation with zero loss of natural lightness. # For protans, the confusion axis is [0.9785, -0.2065]; its exact perpendicular is # [0.2065, 0.9785]. The vector [0.0, 1.0] provides the canonical S-cone / b* shift. ORTHOGONAL_DIRECTIONS = { "protan": np.array([0.0, 1.0], dtype=np.float64), "deutan": np.array([-0.4062, 0.9139], dtype=np.float64), } def _effective_target_gap(severity: float, cvd_type: str, base_target: float = 30.0) -> float: """Scale required lightness separation dynamically based on CVD severity.""" if severity <= 0.0: return 0.0 s = float(np.clip(severity, 0.0, 1.0)) if cvd_type == "protan": return float(18.0 + (base_target - 18.0) * s) return float(14.0 + (base_target - 14.0) * s) def _simulate_lab_center( lab_centers: np.ndarray, sim_matrix: Optional[np.ndarray] = None, severity: float = 1.0, cvd_type: str = "deutan", ) -> np.ndarray: """Simulate CIELAB cluster centers through CVD in linear RGB. Uses DaltonLens Smith & Pokorny (1975) sRGB simulation (Brettel 1997 or Viénot 1999). Avoids an extra LAB→sRGB→linear round-trip that clips saturated colors. """ is_1d = lab_centers.ndim == 1 if is_1d: lab_centers = lab_centers.reshape(1, 3) from .__init__ import _lab_to_linear_f32, _linear_to_lab_f32 linear = _lab_to_linear_f32(lab_centers.astype(np.float32)) if sim_matrix is not None: sim_linear = np.clip(linear.reshape(-1, 3) @ sim_matrix.T, 0.0, 1.0) else: from .cvd_simulation import simulate_cvd_machado2009 sim_linear = np.clip(simulate_cvd_machado2009(linear.reshape(-1, 3), severity, cvd_type), 0.0, 1.0) sim_lab = _linear_to_lab_f32(sim_linear.reshape(lab_centers.shape).astype(np.float32)) return sim_lab[0] if is_1d else sim_lab def _chroma(center: np.ndarray) -> float: return float(np.hypot(center[1], center[2])) def _is_red(center: np.ndarray) -> bool: l_star = float(center[0]) return float(center[1]) > _rg_a_min(l_star) and _chroma(center) > _rg_chroma_min(l_star) def _red_strength(center: np.ndarray) -> float: """Return 0..1 strength for how red a center is (a* and chroma).""" l_star = float(center[0]) a_min = _rg_a_min(l_star) c_min = _rg_chroma_min(l_star) a = float(center[1]) c = _chroma(center) a_score = np.clip((a - a_min) / 22.0, 0.0, 1.0) c_score = np.clip((c - c_min) / 28.0, 0.0, 1.0) return float(0.6 * a_score + 0.4 * c_score) def _is_green(center: np.ndarray) -> bool: l_star = float(center[0]) return float(center[1]) < -_rg_a_min(l_star) and _chroma(center) > _rg_chroma_min(l_star) def _green_strength(center: np.ndarray) -> float: """Return 0..1 strength for how green a center is (a* and chroma).""" l_star = float(center[0]) a_min = _rg_a_min(l_star) c_min = _rg_chroma_min(l_star) a = float(center[1]) c = _chroma(center) a_score = np.clip((-a - a_min) / 24.0, 0.0, 1.0) c_score = np.clip((c - c_min) / 30.0, 0.0, 1.0) return float(0.6 * a_score + 0.4 * c_score) # Near-achromatic centers (black/white/gray text & ink). NEUTRAL_CHROMA = 12.0 def _is_neutral(center: np.ndarray) -> bool: """True for near-achromatic centers - text, ink and paper must not move. Uses luminance-scaled thresholding to avoid falsely classifying dark saturated primaries as neutral black ink while preserving true neutrals. """ return _chroma(center) < _achromatic_threshold(float(center[0])) def _scale_chroma( center: np.ndarray, scale: float, max_delta_chroma: float, ) -> np.ndarray: """Scale a*/b* chroma without rotating hue.""" out = center.copy() c = _chroma(out) if c < 1e-6: return out target_c = c * scale target_c = np.clip(target_c, max(0.0, c - max_delta_chroma), c + max_delta_chroma) out[1:3] *= target_c / c return out def _candidate_center( base: np.ndarray, delta_l: float, chroma_scale: float, max_delta_chroma: float, ortho_dir: Optional[np.ndarray] = None, ortho_step: float = 0.0, ) -> np.ndarray: out = _scale_chroma(base.astype(np.float64), chroma_scale, max_delta_chroma) out[0] = np.clip(float(base[0]) + delta_l, 5.0, 95.0) if ortho_dir is not None and abs(ortho_step) > 1e-5: shift_mag = min(max_delta_chroma * 0.5, 6.0) * ortho_step # Bound coordinates to full CIELAB range [-128.0, 127.0] rather than an arbitrary # [-80.0, 80.0] box, which dragged saturated sRGB primaries inwards. Gamut overflow # is penalised by _clipping_penalty during search. out[1] = np.clip(out[1] + shift_mag * ortho_dir[0], -128.0, 127.0) out[2] = np.clip(out[2] + shift_mag * ortho_dir[1], -128.0, 127.0) return out def _classify_pair(centers: np.ndarray, ci: int, cj: int) -> Tuple[int, int, bool]: c1_red, c1_green = _is_red(centers[ci]), _is_green(centers[ci]) c2_red, c2_green = _is_red(centers[cj]), _is_green(centers[cj]) is_rg_pair = (c1_red and c2_green) or (c1_green and c2_red) l_diff = float(centers[ci][0]) - float(centers[cj][0]) # Natural polarity: if there is an existing lightness difference (|L_i - L_j| >= 5.0), # preserve natural polarity: darker cluster stays dark_idx, lighter stays light_idx! if abs(l_diff) >= 5.0: if l_diff < 0: return ci, cj, is_rg_pair return cj, ci, is_rg_pair # Near-equal lightness (|L_i - L_j| < 5.0): tie-break with conventional red-dark / green-light if c1_red and (c2_green or not c2_red): return ci, cj, is_rg_pair if c2_red and (c1_green or not c1_red): return cj, ci, is_rg_pair if c1_green and not c2_green: return cj, ci, is_rg_pair if c2_green and not c1_green: return ci, cj, is_rg_pair if centers[ci][0] <= centers[cj][0]: return ci, cj, is_rg_pair return cj, ci, is_rg_pair def _clipping_penalty(center: np.ndarray) -> float: """Small penalty for colors likely to clip after LAB to sRGB conversion.""" L = float(center[0]) c = _chroma(center) penalty = max(0.0, 8.0 - L) + max(0.0, L - 92.0) penalty += max(0.0, c - 85.0) * 0.15 return penalty def reencode( centers: np.ndarray, conflict_pairs: List[Tuple[int, int]], severity: float, cvd_type: str, use_fast: bool = False, target_de: float = 24.0, target_rg_l_gap: float = 30.0, allow_chroma_shift: bool = True, max_delta_l: float = 38.0, max_delta_chroma: float = 8.0, refinement_passes: int = 2, cluster_labels: Optional[List[str]] = None, pinned_indices: Optional[set] = None, ) -> np.ndarray: """ Bounded candidate-search re-encoding. The optimizer tries conservative L* and chroma candidates for each conflicting pair, then keeps the candidate that best satisfies simulated separation, visible red/green lightness gap, and naturalness. """ original_centers = centers.copy().astype(np.float64) modified_centers = original_centers.copy() if not conflict_pairs: return modified_centers sim_matrix = get_simulation_matrix(severity, cvd_type) delta_e_fn = delta_e_cie76 if use_fast else delta_e_ciede2000 cumulative_drift = np.zeros(len(centers), dtype=np.float64) # Protected clusters (text / ink / paper / background / person) are pinned # - their centers must never move, so the chromatic partner carries the separation. protected = np.array( [_is_neutral(c) for c in original_centers], dtype=bool ) if cluster_labels is not None: for idx, lbl in enumerate(cluster_labels): if idx < len(protected): nl = lbl.lower() if idx == 0 or "person" in nl or "exclude" in nl or "paper" in nl or "background" in nl or ("text" in nl and _is_neutral(original_centers[idx])): protected[idx] = True if pinned_indices is not None: for idx in pinned_indices: if idx < len(protected): protected[idx] = True effective_base_gap = _effective_target_gap(severity, cvd_type, target_rg_l_gap) dark_steps = np.array([0.0, -4.0, -8.0, -12.0, -16.0]) light_steps = np.array([0.0, 4.0, 8.0, 12.0, 16.0]) rg_dark_steps = np.array([0.0, -6.0, -12.0, -18.0, -24.0]) rg_light_steps = np.array([-4.0, 0.0, 4.0, 8.0, 14.0, 20.0]) neutral_chroma = [1.0] red_chroma = [1.0, 1.10] if allow_chroma_shift else neutral_chroma green_chroma = [1.0, 1.06] if allow_chroma_shift else neutral_chroma other_chroma = [1.0, 1.08] if allow_chroma_shift else neutral_chroma ortho_dir = ORTHOGONAL_DIRECTIONS.get(cvd_type) if (allow_chroma_shift and cvd_type in ORTHOGONAL_DIRECTIONS) else None ortho_steps = np.array([0.0, 1.0, -1.0]) if ortho_dir is not None else np.array([0.0]) def _pair_is_flagged(ci: int, cj: int) -> bool: if protected[ci] and protected[cj]: return False sim_i = _simulate_lab_center(modified_centers[ci], sim_matrix) sim_j = _simulate_lab_center(modified_centers[cj], sim_matrix) de_sim = delta_e_fn(sim_i, sim_j) _, _, is_rg = _classify_pair(original_centers, ci, cj) pair_thresh = 35.0 if is_rg else 20.0 l_thresh = 22.0 if is_rg else 20.0 if de_sim >= pair_thresh or abs(float(sim_i[0]) - float(sim_j[0])) >= l_thresh: return False return True for pass_idx in range(max(1, refinement_passes)): changed = False for ci, cj in conflict_pairs: if not _pair_is_flagged(ci, cj): continue dark_idx, light_idx, is_rg_pair = _classify_pair(original_centers, ci, cj) # Two near-neutral clusters are already distinguishable by lightness # - nothing to fix, and neither may be recolored. if protected[dark_idx] and protected[light_idx]: continue orig_dark_l = float(original_centers[dark_idx][0]) orig_light_l = float(original_centers[light_idx][0]) dark_is_red = _is_red(original_centers[dark_idx]) dark_is_green = _is_green(original_centers[dark_idx]) light_is_red = _is_red(original_centers[light_idx]) light_is_green = _is_green(original_centers[light_idx]) if is_rg_pair: red_c = original_centers[dark_idx] if dark_is_red else original_centers[light_idx] green_c = original_centers[dark_idx] if dark_is_green else original_centers[light_idx] red_strength = _red_strength(red_c) green_strength = _green_strength(green_c) rg_gap_target = effective_base_gap + 4.0 * min(red_strength, green_strength) pair_dark_steps = rg_dark_steps pair_light_steps = rg_light_steps dark_chroma_options = red_chroma if dark_is_red else green_chroma light_chroma_options = green_chroma if light_is_green else red_chroma dark_l_budget = min(max_delta_l, 18.0 + 14.0 * (red_strength if dark_is_red else green_strength)) light_l_budget = min(max_delta_l, 22.0 + 14.0 * (green_strength if light_is_green else red_strength)) else: rg_gap_target = effective_base_gap pair_dark_steps = dark_steps pair_light_steps = light_steps dark_chroma_options = other_chroma light_chroma_options = other_chroma non_rg_budget = 18.0 if (protected[dark_idx] or protected[light_idx]) else 16.0 dark_l_budget = light_l_budget = non_rg_budget dark_base = modified_centers[dark_idx] light_base = modified_centers[light_idx] # Pin protected clusters if protected[dark_idx]: pair_dark_steps = np.array([0.0]) dark_chroma_options = neutral_chroma dark_l_budget = 0.0 if protected[light_idx]: pair_light_steps = np.array([0.0]) light_chroma_options = neutral_chroma light_l_budget = 0.0 best_score = -np.inf best_dark = dark_base.copy() best_light = light_base.copy() for dl_dark in pair_dark_steps: for dl_light in pair_light_steps: for c_dark in dark_chroma_options: for c_light in light_chroma_options: for o_step in ortho_steps: cand_dark = _candidate_center( dark_base, dl_dark, c_dark, max_delta_chroma, ortho_dir=ortho_dir, ortho_step=-o_step, ) cand_light = _candidate_center( light_base, dl_light, c_light, max_delta_chroma, ortho_dir=ortho_dir, ortho_step=o_step, ) if abs(float(cand_dark[0]) - orig_dark_l) > dark_l_budget: continue if abs(float(cand_light[0]) - orig_light_l) > light_l_budget: continue sim_dark = _simulate_lab_center(cand_dark, sim_matrix) sim_light = _simulate_lab_center(cand_light, sim_matrix) de_sim = delta_e_fn(sim_dark, sim_light) l_gap = float(cand_light[0] - cand_dark[0]) drift_dark = delta_e_fn(original_centers[dark_idx], cand_dark) drift_light = delta_e_fn(original_centers[light_idx], cand_light) mean_drift = 0.5 * (drift_dark + drift_light) extra_drift = cumulative_drift[dark_idx] + cumulative_drift[light_idx] score = 0.0 score += min(de_sim, target_de + 12.0) * 20.0 score += min(max(l_gap, 0.0), rg_gap_target + 14.0) * 3.0 if is_rg_pair: score += min(max(l_gap, 0.0), rg_gap_target + 20.0) * 9.0 if l_gap < 0.0: score -= 400.0 # Polarity inversion penalty else: score -= max(0.0, rg_gap_target - l_gap) * 38.0 if de_sim >= 20.0: score += 120.0 if de_sim >= target_de: score += 60.0 if (not is_rg_pair) or l_gap >= rg_gap_target: score += 80.0 score -= max(0.0, 20.0 - de_sim) * 50.0 drift_soft_limit = 24.0 if is_rg_pair else 22.0 score -= max(0.0, mean_drift - drift_soft_limit) * 4.5 score -= extra_drift * 0.15 score -= _clipping_penalty(cand_dark) * 8.0 score -= _clipping_penalty(cand_light) * 8.0 if score > best_score: best_score = score best_dark = cand_dark best_light = cand_light if ( delta_e_fn(modified_centers[dark_idx], best_dark) > 1e-6 or delta_e_fn(modified_centers[light_idx], best_light) > 1e-6 ): changed = True cumulative_drift[dark_idx] += delta_e_fn(modified_centers[dark_idx], best_dark) cumulative_drift[light_idx] += delta_e_fn(modified_centers[light_idx], best_light) modified_centers[dark_idx] = best_dark modified_centers[light_idx] = best_light if not changed: break # Directional retry for pairs that remain flagged for retry_round in range(2): retry_changed = False for ci, cj in conflict_pairs: if not _pair_is_flagged(ci, cj): continue dark_idx, light_idx, is_rg_pair = _classify_pair(original_centers, ci, cj) if protected[dark_idx] and protected[light_idx]: continue move_indices = (dark_idx, light_idx) dark_budget = 0.0 if protected[dark_idx] else (26.0 if is_rg_pair else 18.0) light_budget = 0.0 if protected[light_idx] else (26.0 if is_rg_pair else 18.0) move_budgets = (min(max_delta_l, dark_budget), min(max_delta_l, light_budget)) for _ in range(8): if not _pair_is_flagged(ci, cj): break current_sim = _simulate_lab_center(modified_centers, sim_matrix) current_de = delta_e_fn(current_sim[ci], current_sim[cj]) current_gap = float(modified_centers[light_idx][0] - modified_centers[dark_idx][0]) candidates = [] for first_delta, second_delta in ( (-4.0, 0.0), (0.0, 4.0), (-4.0, 4.0), (-6.0, 0.0), (0.0, 6.0), (-6.0, 6.0), ): candidate = modified_centers.copy() for index, delta, budget in zip(move_indices, (first_delta, second_delta), move_budgets): if protected[index] or abs(float(candidate[index][0] + delta) - float(original_centers[index][0])) > budget: continue candidate[index][0] = np.clip(candidate[index][0] + delta, 5.0, 95.0) candidate_sim = _simulate_lab_center(candidate, sim_matrix) candidate_de = delta_e_fn(candidate_sim[ci], candidate_sim[cj]) candidate_gap = float(candidate[light_idx][0] - candidate[dark_idx][0]) candidates.append((candidate_de, candidate_gap, candidate)) if not candidates: break candidates.sort(key=lambda item: (item[0], item[1]), reverse=True) best_de, best_gap, best_candidate = candidates[0] if best_de <= current_de + 1e-6 and best_gap <= current_gap + 1e-6: break modified_centers = best_candidate retry_changed = True if not retry_changed: break return modified_centers def enforce_rg_separation( centers: np.ndarray, target_gap: Optional[float] = None, l_min: float = 5.0, l_max: float = 95.0, conflict_pairs: Optional[List[Tuple[int, int]]] = None, cluster_labels: Optional[List[str]] = None, pinned_indices: Optional[set] = None, severity: float = 1.0, cvd_type: str = "deutan", original_centers: Optional[np.ndarray] = None, max_delta_l: Optional[float] = None, ) -> np.ndarray: """ Safety net: guarantee required lightness gap between red and green clusters. Respects natural polarity: if green was naturally darker than red, green stays dark and red stays light. Never forces green to invert over red when green is a dark background. Bounds total lightness drift against original_centers when max_delta_l is provided. Parameters ---------- centers : (K, 3) cluster centers in CIELAB target_gap : minimum L* gap to enforce (computed from severity if None) l_min : floor for L* (default 5.0) l_max : ceiling for L* (default 95.0) conflict_pairs : list of active conflict pairs, or None for image-wide fallback cluster_labels : semantic labels for background/text protection pinned_indices : indices of clusters that must not move severity : CVD severity level (0.0 to 1.0) cvd_type : 'deutan' or 'protan' original_centers : ground-truth pre-reencoding cluster centers for polarity and drift bounds max_delta_l : maximum total lightness shift allowed from original_centers """ out = centers.copy().astype(np.float64) if out.shape[0] == 0: return out if target_gap is None: target_gap = _effective_target_gap(severity, cvd_type, base_target=30.0) orig = original_centers if original_centers is not None else centers if conflict_pairs is not None: if len(conflict_pairs) == 0: return out # No conflicts detected - no-op for ci, cj in conflict_pairs: c1_red, c1_green = _is_red(orig[ci]), _is_green(orig[ci]) c2_red, c2_green = _is_red(orig[cj]), _is_green(orig[cj]) is_rg = (c1_red and c2_green) or (c1_green and c2_red) if not is_rg: continue dark_i, light_i, _ = _classify_pair(orig, ci, cj) dark_l = float(out[dark_i, 0]) light_l = float(out[light_i, 0]) current_gap = light_l - dark_l shortfall = target_gap - current_gap if shortfall <= 0.0: continue is_pinned_dark = (pinned_indices and dark_i in pinned_indices) is_pinned_light = (pinned_indices and light_i in pinned_indices) if cluster_labels is not None: nl_dark = cluster_labels[dark_i].lower() if dark_i < len(cluster_labels) else "" nl_light = cluster_labels[light_i].lower() if light_i < len(cluster_labels) else "" if "background" in nl_dark or "paper" in nl_dark or ("text" in nl_dark and _is_neutral(orig[dark_i])): is_pinned_dark = True if "background" in nl_light or "paper" in nl_light or ("text" in nl_light and _is_neutral(orig[light_i])): is_pinned_light = True if is_pinned_dark and is_pinned_light: continue # Bound drift against original_centers and max_delta_l (R2) if max_delta_l is not None: dark_l_min = max(l_min, float(orig[dark_i, 0]) - max_delta_l) dark_l_max = min(l_max, float(orig[dark_i, 0]) + max_delta_l) light_l_min = max(l_min, float(orig[light_i, 0]) - max_delta_l) light_l_max = min(l_max, float(orig[light_i, 0]) + max_delta_l) else: dark_l_min, dark_l_max = l_min, l_max light_l_min, light_l_max = l_min, l_max if is_pinned_dark: out[light_i, 0] = float(np.clip(light_l + shortfall, light_l_min, light_l_max)) elif is_pinned_light: out[dark_i, 0] = float(np.clip(dark_l - shortfall, dark_l_min, dark_l_max)) else: dark_headroom = max(0.0, dark_l - dark_l_min) light_headroom = max(0.0, light_l_max - light_l) total_headroom = dark_headroom + light_headroom if total_headroom > 1e-4: shift_down = shortfall * (dark_headroom / total_headroom) shift_up = shortfall * (light_headroom / total_headroom) else: shift_down = shift_up = shortfall / 2.0 out[dark_i, 0] = float(np.clip(dark_l - shift_down, dark_l_min, dark_l_max)) out[light_i, 0] = float(np.clip(light_l + shift_up, light_l_min, light_l_max)) return out # Legacy fallback when conflict_pairs is None red_idx = [i for i in range(out.shape[0]) if _is_red(orig[i])] green_idx = [i for i in range(out.shape[0]) if _is_green(orig[i])] if not red_idx or not green_idx: return out red_l = float(np.median(out[red_idx, 0])) green_l = float(np.median(out[green_idx, 0])) gap = abs(green_l - red_l) shortfall = target_gap - gap if shortfall <= 0.0: return out if green_l >= red_l: dark_headroom = max(0.0, red_l - l_min) light_headroom = max(0.0, l_max - green_l) total_headroom = dark_headroom + light_headroom if total_headroom > 1e-4: shift_down = shortfall * (dark_headroom / total_headroom) shift_up = shortfall * (light_headroom / total_headroom) else: shift_down = shift_up = shortfall / 2.0 for i in red_idx: r_min = max(l_min, float(orig[i, 0]) - max_delta_l) if max_delta_l is not None else l_min out[i, 0] = float(np.clip(out[i, 0] - shift_down, r_min, l_max)) for i in green_idx: g_max = min(l_max, float(orig[i, 0]) + max_delta_l) if max_delta_l is not None else l_max out[i, 0] = float(np.clip(out[i, 0] + shift_up, l_min, g_max)) else: dark_headroom = max(0.0, green_l - l_min) light_headroom = max(0.0, l_max - red_l) total_headroom = dark_headroom + light_headroom if total_headroom > 1e-4: shift_down = shortfall * (dark_headroom / total_headroom) shift_up = shortfall * (light_headroom / total_headroom) else: shift_down = shift_up = shortfall / 2.0 for i in green_idx: g_min = max(l_min, float(orig[i, 0]) - max_delta_l) if max_delta_l is not None else l_min out[i, 0] = float(np.clip(out[i, 0] - shift_down, g_min, l_max)) for i in red_idx: r_max = min(l_max, float(orig[i, 0]) + max_delta_l) if max_delta_l is not None else l_max out[i, 0] = float(np.clip(out[i, 0] + shift_up, l_min, r_max)) return out