paper_code_mapping.md

Paper ↔ code mapping

This document maps every equation of the ReDiMask paper to the implementation, and records the decisions taken where the paper specifies the role of a term but not its functional form.

Sec. III-B — Regionized Diffusion Labeling

Paper	Implementation
Eq. (1) region descriptor h^t_{i,j} = mean of F^t_phi(x_i) over region r_{i,j}	redimask/regions.py::RegionAggregator.descriptors
Region partition R_i = {r_{i,j}} (SLIC, spatial support only)	redimask/regions.py::slic_partition
Eq. (2) assignment margin rho^t_{i,j} = sim to nearest minus sim to second-nearest prototype	redimask/rdl.py::assignment_margin
Cluster prototypes c^t_k	redimask/rdl.py::group_prototypes
K-means over region descriptors per timestep	redimask/rdl.py::fit_kmeans, RegionizedDiffusionLabeling.fit
Cross-timestep alignment to the reference timestep (Hungarian)	redimask/rdl.py::_align_to_reference
Eqs. (3)-(5) structural response map B_i	redimask/rdl.py::structural_response; the underlying per-pixel diffusion signal is also available as redimask/features.py::structural_boundary_hint
Eq. (6) supporting region set R_k	RegionizedDiffusionLabeling.region_state, select_candidates
Eq. (7) structural score T_k	RegionizedDiffusionLabeling.select_candidates
Eq. (8) group score Q_k = lambda_t T_k + lambda_m M_k + lambda_s S_k + lambda_r R_k	RegionizedDiffusionLabeling.select_candidates
Group support filter (0.5% – 70% of the image area)	RegionizedDiffusionLabeling.select_candidates (min_support_ratio, max_support_ratio)
Eq. (9) candidate set C+ = TopK_{Kc}{Q_k}	RegionizedDiffusionLabeling.select_candidates
Eq. (10) reliable candidate-support count u_{i,j}	RegionizedDiffusionLabeling.render
Eq. (11) candidate-assignment count v_{i,j}, mean margin rho_bar	RegionizedDiffusionLabeling.render
Eq. (12) region label in {1, 0, 255}	RegionizedDiffusionLabeling.render
Pixel projection of region labels	RegionizedDiffusionLabeling.render

Decisions where the paper leaves the functional form open

1. M_k (margin term, Eq. 8) — implemented as the mean prototype margin of the regions supporting group k, then min-max normalised across groups.
2. S_k (timestep-consistency term, Eq. 8) — the paper states "whether the cluster is repeatedly supported by the same regions across low-noise timesteps". Implemented as the mean, over the supporting regions, of the fraction of timesteps in which the region is aligned to group k. The value already lies in [0, 1] and is min-max normalised with the other terms.
3. R_k (spatial-regularity term, Eq. 8) — the paper states it is computed from image-derived region supports. Implemented as the mean isoperimetric ratio 4*pi*A / P^2 of the supporting SLIC regions, which down-weights fragmented or sprawling supports. The hard coverage filter (0.5%–70%) is applied before ranking, as described in the paper.
4. Group coverage — computed from the aligned assignments at the reference timestep so that per-image coverage is non-overlapping and deterministic.
5. tau_m and tau- — both set to the image-level median of the prototype margins, as stated in the Implementation Details ("the image-level median of prototype margins is used as the margin cutoff"; "regions that never belong to candidate groups and have above-median margins are labeled as reliable non-building").
6. Native resolution of the feature map — RDL is defined on the 16x16 mid-block activation resized to the 256px patch. The structural response B_i is computed at 16x16 and then resized, and the region descriptors are obtained with the equivalent bilinear aggregation matrix, so that the 1280x256x256 tensor is never materialised.

Sec. III-C — Coarse segmentation student

Paper	Implementation
Eq. (13) A_c = S_theta(x) single-channel building score map	redimask/student.py::CoarseStudent.forward
Eq. (14) P_c = Sigmoid(A_c)	redimask/student.py::CoarseStudent.probability
Eq. (15) valid pixel set Omega_v (all pixels with a non-ignored label)	redimask/student.py::partial_bce
Eq. (16) partial BCE over Omega_v	redimask/student.py::partial_bce
Student frozen before W-MR training	tools/train_wmr.py (requires_grad_(False))

The paper does not fix the student architecture; a three-level U-Net with base_channels = 32 is used (redimask/nets.py).

The paper writes the student output as a single-channel score map. The implementation can also carry a native class map; in that case the building score is read as the building logit minus the log-sum-exp of the remaining logits, exposed as redimask/student.py::building_binary_logit. Both forms describe A_c of Eq. (13) and the single-channel reduction is the default.

Sec. III-D — Warm-start Mask Refinement

Paper	Implementation
Eq. (17) perturbation P_i,t = Proj_[0,1] of P_c + sigma_t * eps	redimask/wmr.py::perturb_mask_state
Eq. (18) residual branch Delta = D_psi(x, P_i,t, t)	redimask/wmr.py::MaskResidualRefiner.forward
Eq. (19) coarse binary mask Y_c = I[P_c >= tau_c]	redimask/wmr.py::completion_gate
Eq. (20) completion gate (uncertainty band OR boundary band)	redimask/wmr.py::completion_gate
Eq. (21) A_r = A_c + alpha * G * ReLU(Delta)	redimask/wmr.py::WarmStartMaskRefinement.refine_from_state
Eq. (22) P_r = Sigmoid(A_r)	redimask/wmr.py::refine_from_state / refine
Eq. (23) gated valid pixel set Omega_g	redimask/wmr.py::refinement_loss
Eq. (24) L_ref = BCE over Omega_g	redimask/wmr.py::refinement_loss
Eq. (25) fixed-step inference anchored on A_c	redimask/wmr.py::WarmStartMaskRefinement.refine, inference_levels
Gradients restricted to D_psi	tools/train_wmr.py

Decisions where the paper leaves the functional form open

1. T_infer (Eq. 25) — the Q = 3 fixed noise-condition levels are evenly spaced over the training range, from the upper bound down to the lower bound.
2. tau_seg — the paper introduces it in Algorithm 2 without a value; the default is 0.5.
3. Timestep conditioning — the noise level is supplied to the residual branch as a broadcast scalar channel. This is the only conditioning the paper requires ("conditioned on the image, the perturbed mask state, and the noise level").
4. L_ref numerics — computed with binary_cross_entropy_with_logits on A_r, which is algebraically identical to BCE(P_r, Y_hat) with P_r = Sigmoid(A_r) and numerically stable.
5. Anchoring of the loss — Omega_g is the intersection of the valid pseudo-label set Omega_v and the gate, exactly as written in Eq. (23).
6. alpha (Eq. 21) and T_train (Eq. 17) — the paper gives the role of both but no value. The defaults are alpha = 1.0 and T_train = [0.0, 0.30].
7. Perturbation schedule (Eq. 17) — projection, the form written in the paper, is the default. variance_preserving is offered through wmr.noise_schedule as an alternative normalisation of the perturbed state.
8. positive_dropout — defaults to 0.0, i.e. no foreground pixels are removed before perturbation. The value is exposed for completeness.

Sec. III-E — Interior Consistency Correction

Paper	Implementation
Enclosed non-building component, no border contact, area <= 1024, mean probability >= 0.15	redimask/icr.py::apply_icr
Small reliable interior holes only	4-connectivity components, area threshold, probability threshold

Sec. IV-A — Metrics

Paper	Implementation
Eq. (26) IoU, F1	redimask/metrics.py::mask_metrics
Eq. (27) boundary precision/recall with 3-pixel dilation tolerance	mask_metrics, binary_boundary, dilate_binary
Eq. (28) BoundF	mask_metrics
Eq. (29) Building Ratio (BR)	redimask/metrics.py::building_ratio
Eq. (30) Recall Contribution (RC)	redimask/metrics.py::recall_contribution

Fig. 1 — mismatch analysis

Panel	Implementation
(a) group–class affinity `P(class	group)`
(b) building dispersion `P(group	building)` and cumulative coverage
(c) purity–coverage trade-off	redimask/analysis.py::purity_coverage_curve

Ground truth is read by tools/diagnose_groups.py only. No diagnostic quantity is consumed by RDL, the student or W-MR.