File size: 26,526 Bytes
78661be
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8cbfe96
78661be
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
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