acra-backend / code /pipeline /reencoding.py
Zeref8425's picture
fix(pipeline): deploy processing refinements from 8ae183d
8cbfe96
Raw History Blame Contribute Delete
26.5 kB
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