1 rendering.candidate_depth_renderer

rendering.candidate_depth_renderer

Render valid candidate poses directly from dataset snippets.

CandidateDepthRenderer consumes an EfmSnippetView with an attached mesh and a CandidateSamplingResult. It renders the compact valid candidate table but returns candidate_indices into the full sampled shell so labels and heavy diagnostics can be joined back to candidate provenance, validity masks, and reason codes.

This module provides CandidateDepths, its renderer config, and the orchestrator that adapts snippet meshes/cameras to the configured depth backend. The backend owns rasterization; candidate generation owns feasibility, and point-cloud conversion plus RRI scoring remain downstream.

Depth output is metric PyTorch3D z-depth in the physical camera frame. The renderer is used for oracle/evaluation labels; callers decide whether rendered depths or backprojected point clouds are retained in a rollout store.

1.1 Attributes

Name	Description
CandidateDepthRendererUiBound	Inclusive presentation bounds for safe interactive depth-renderer controls.

1.2 Classes

Name	Description
CandidateDepthRenderer	High-level wrapper that renders depth for compact valid candidate poses.
CandidateDepthRendererConfig	Compose camera calibration, render sizing, and backend selection.
CandidateDepths	Typed result for candidate depth rendering.

1.2.1 CandidateDepthRenderer

rendering.candidate_depth_renderer.CandidateDepthRenderer(config)

High-level wrapper that renders depth for compact valid candidate poses.

1.2.1.1 Methods

Name	Description
rendered_camera_centers	Return world centres for exactly the configured rendered prefix.
render	Render the configured valid-candidate prefix.
render_compact_indices	Render depth maps for explicit compact-valid candidate rows.

1.2.1.1.1 rendered_camera_centers

rendering.candidate_depth_renderer.CandidateDepthRenderer.rendered_camera_centers(
    candidates,
)

Return world centres for exactly the configured rendered prefix.

1.2.1.1.1.1 Parameters

Name	Type	Description	Default
candidates	CandidateSamplingResult	Compact valid-camera table with full-shell provenance.	required

1.2.1.1.1.2 Returns

Name	Type	Description
	torch.Tensor	World metres Tensor["C_render 3", float] on the renderer device,
	torch.Tensor	retaining the candidate pose dtype and compact row order. The same
	torch.Tensor	canonical camera selection and candidate cap are used by render;
	torch.Tensor	no mesh is accessed and no rasterization occurs. This query does not
	torch.Tensor	mutate candidates, and callers must not mutate returned positions.

1.2.1.1.1.3 Raises

Name	Type	Description
	ValueError	No candidate cameras are available.

1.2.1.1.2 render

rendering.candidate_depth_renderer.CandidateDepthRenderer.render(
    sample,
    candidates,
    *,
    mesh_override=None,
)

Render the configured valid-candidate prefix.

mesh_override replaces geometry only, leaving calibrated cameras, near/far limits and shell indices unchanged. None uses the original snippet mesh. Cropped renders are scoring evidence; full-scene selected observations must be acquired separately before causal state updates.

1.2.1.1.3 render_compact_indices

rendering.candidate_depth_renderer.CandidateDepthRenderer.render_compact_indices(
    sample,
    candidates,
    compact_indices,
    *,
    mesh_override=None,
)

Render depth maps for explicit compact-valid candidate rows.

1.2.1.1.3.1 Parameters

Name	Type	Description	Default
sample	EfmSnippetView	Snippet with an attached mesh.	required
candidates	CandidateSamplingResult	Full candidate sampling result.	required
compact_indices	torch.Tensor | list[int] | tuple[int, …]	Row indices into candidates.views. These are compact valid-candidate indices, not full-shell indices.	required
mesh_override	ViewingCropMesh | None	Optional world-frame geometry replacement. None renders the original full mesh; calibration is unchanged.	None

1.2.1.1.3.2 Returns

Name	Type	Description
	CandidateDepths	Rendered depth batch aligned with compact_indices and carrying
	CandidateDepths	full-shell candidate_indices for joins.

1.2.2 CandidateDepthRendererConfig

rendering.candidate_depth_renderer.CandidateDepthRendererConfig()

Compose camera calibration, render sizing, and backend selection.

Rendering is an oracle/evaluation stage: its mesh-derived depths must not be exposed as actor-visible state. max_candidates_final bounds work on the already compact valid-candidate table rather than changing validity.

1.2.2.1 Attributes

Name	Description
target_type	Return the high-level candidate renderer constructed by this config.
device	Geometry tensor device resolved under PYTORCH3D_BACKEND policy.
renderer	Nested renderer config; omitted devices inherit before provider admission.
max_candidates_final	Maximum number of already-pruned candidate views to render.
resolution_scale	Optional positive uniform scale applied to H,W for rendering.
output_width_px	Optional exact rendered width in pixels; overrides resolution_scale when paired with height.
output_height_px	Optional exact rendered height in pixels; overrides resolution_scale when paired with width.
verbosity	Verbosity level for logging.
is_debug	Enable detailed debug logging.

1.2.3 CandidateDepths

rendering.candidate_depth_renderer.CandidateDepths(
    depths,
    depths_valid_mask,
    poses,
    reference_pose,
    candidate_indices,
    camera,
    p3d_cameras,
)

Typed result for candidate depth rendering.

candidate_indices maps rendered compact rows back to the full candidate shell. That link is required when writing target-RRI labels or selected heavy diagnostics into rollouts.zarr.

1.2.3.1 Attributes

Name	Description
depths	Metric camera z-depth Tensor["C H W", float] in metres.
depths_valid_mask	Face-hit and near/far mask Tensor["C H W", bool] for raw depths.
poses	Rendered world-from-camera poses with logical shape (C, 12).
reference_pose	Physical world-from-reference rig pose with logical shape (12,).
candidate_indices	Full-shell row indices Tensor["C", int64] for rendered candidates.
camera	Physical calibration and camera-from-reference extrinsics aligned over C.
p3d_cameras	PyTorch3D cameras with world-to-view transforms aligned over C.

1.2.3.2 Methods

Name	Description
to_serializable	Serialize this batch into a cache-friendly CPU payload.
from_serializable	Reconstruct one batch from a serialized payload.

1.2.3.2.1 to_serializable

rendering.candidate_depth_renderer.CandidateDepths.to_serializable()

Serialize this batch into a cache-friendly CPU payload.

1.2.3.2.2 from_serializable

rendering.candidate_depth_renderer.CandidateDepths.from_serializable(
    payload,
    *,
    device,
)

Reconstruct one batch from a serialized payload.

1.2.3.2.2.1 Parameters

Name	Type	Description	Default
payload	dict[str, object]	Serialized payload produced by to_serializable.	required
device	torch.device	Destination device for tensors and wrappers.	required

1.2.3.2.2.2 Returns

Name	Type	Description
	'CandidateDepths'	Reconstructed candidate-depth batch.

1.3 Functions

Name	Description
candidate_depth_renderer_ui_bounds	Return domain-owned limits for interactive depth-renderer controls.

1.3.1 candidate_depth_renderer_ui_bounds

rendering.candidate_depth_renderer.candidate_depth_renderer_ui_bounds()

Return domain-owned limits for interactive depth-renderer controls.

Interactive limits bound UI allocation and render count while preserving the broader programmatic configuration contract for batch callers.