1 rri_metrics.rri

rri_metrics.rri

Prepared relative reconstruction improvement payloads and computation.

This module centralizes the numerical guard, candidate-aligned result payload, and pure RRI formula shared by Oracle scorers. Evidence preparation and point–mesh distance evaluation remain in their owning modules.

RriResult stores both the scalar improvement label and the directional point-mesh diagnostics needed to audit target-vs-scene behavior. Downstream datasets should carry these diagnostics when feasible so improvements in RRI can be decomposed into accuracy and completeness changes.

1.1 Attributes

Name Description
DEFAULT_RRI_EPSILON Shared additive error guard for RRI and rollout-return metrics.

1.2 Classes

Name Description
RriConfig Numerical contract for prepared RRI computation.
RriResult Batch of oracle RRI labels and directional distance diagnostics.

1.2.1 RriConfig

rri_metrics.rri.RriConfig(epsilon=DEFAULT_RRI_EPSILON)

Numerical contract for prepared RRI computation.

1.2.1.1 Attributes

Name Description
epsilon Positive additive denominator guard for reconstruction errors.

1.2.2 RriResult

rri_metrics.rri.RriResult(
    rri,
    pm_dist_before,
    pm_dist_after,
    pm_acc_before,
    pm_comp_before,
    pm_acc_after,
    pm_comp_after,
    fscore_tau=None,
)

Batch of oracle RRI labels and directional distance diagnostics.

C is the finite-candidate axis. Reference-only distances are broadcast to that axis so every diagnostic stays aligned with its candidate row. For the bidirectional squared point–mesh error \(D\), the label is

\[ \mathrm{RRI}_t(q)=\frac{D(P_t,M)-D(P_{t\mid q},M)} {D(P_t,M)+\epsilon}. \]

Here \(P_t\) and \(P_{t\mid q}\) are the prepared current and candidate- successor states supplied to compute_rri; this payload does not assume that preparation distributes over a point-set union.

RRI is dimensionless and can be negative when candidate evidence worsens the reconstruction. A low or negative value is still a valid oracle label; candidate invalidity is an upstream hard-mask/reason-code contract and is not encoded in this payload. In the thesis pipeline, the matched target mesh and rendered candidate geometry are oracle-only supervision, not actor-visible VIN inputs.

1.2.2.1 Attributes

Name Description
rri Tensor["C", float32] dimensionless relative reconstruction improvement.
pm_dist_before Tensor["C", float32] broadcast pre-view bidirectional error, in square metres.
pm_dist_after Tensor["C", float32] post-view bidirectional error per candidate, in square metres.
pm_acc_before Tensor["C", float32] broadcast pre-view point-to-mesh error, in square metres.
pm_comp_before Tensor["C", float32] broadcast pre-view mesh-to-point error, in square metres.
pm_acc_after Tensor["C", float32] post-view point-to-mesh error, in square metres.
pm_comp_after Tensor["C", float32] post-view mesh-to-point error, in square metres.
fscore_tau Optional Tensor["C ...", float32] per-candidate F-scores at configured thresholds.

1.2.2.2 Methods

Name Description
to_serializable Serialize tensors into a cache-friendly CPU payload without changing candidate order.
from_serializable Reconstruct one candidate-aligned result on a requested device.
to Return a copy with every present tensor moved to device.
1.2.2.2.1 to_serializable
rri_metrics.rri.RriResult.to_serializable()

Serialize tensors into a cache-friendly CPU payload without changing candidate order.

1.2.2.2.2 from_serializable
rri_metrics.rri.RriResult.from_serializable(payload, *, device)

Reconstruct one candidate-aligned result on a requested device.

1.2.2.2.2.1 Parameters
Name Type Description Default
payload dict[str, Any] Serialized payload produced by :meth:to_serializable. required
device torch.device Destination device for tensors. required
1.2.2.2.2.2 Returns
Name Type Description
'RriResult' Reconstructed RRI result.
1.2.2.2.3 to
rri_metrics.rri.RriResult.to(device)

Return a copy with every present tensor moved to device.

1.3 Functions

Name Description
compute_rri Compute RRI from prepared before/after point-mesh distances.

1.3.1 compute_rri

rri_metrics.rri.compute_rri(before, after, *, config=_DEFAULT_RRI_CONFIG)

Compute RRI from prepared before/after point-mesh distances.

The caller owns evidence preparation, cropping, and fusion. This function owns only the differentiable reconstruction-improvement formula.

Back to top