1 pose_generation.candidate_mixture

pose_generation.candidate_mixture

Mixed finite-candidate view generation with full-shell provenance.

The mixture wrapper keeps CandidateViewGeneratorConfig backward-compatible while prebuilding one private leaf runtime per center/gaze combination and concatenating their full sampled shells. Component counts therefore define the fixed candidate budget exactly, while each output row retains strategy_id, mixture_id, sampler_probability, and optional component name.

Ordering is part of the data contract: invalid candidates remain in the full-shell masks and provenance arrays; compact valid views are recoverable through CandidateSamplingResult.candidate_shell_indices(). Target-point components require CandidateGenerationRuntimeContext.target_center_world because the thesis V1 actor may condition on observed/predicted target records but not on GT target geometry.

This module owns mixture-component configs, stable strategy/position ids, and concatenation of component shells into one provenance-aligned result. Each component delegates geometric sampling and pruning to CandidateViewGenerator; rendering, RRI labels, and final action selection remain downstream responsibilities.

1.1 Theory

The default target-conditioned mixture has 60 full-shell rows: forward_local 24, target_bearing_local 24, and lateral_target_bypass 12. Richer local-refinement, revisit-backtrack, and free-shell components are explicit ablations. Each row records stable position_id, strategy_id, mixture_id, component name, and sampler_probability = 1/N. These provenance arrays let rollout/Q_H stores audit which finite-action family produced each candidate without changing the compact valid-action contract.

1.2 Classes

Name Description
CandidateMixtureViewGenerator Generate a fixed-size candidate table from multiple sampling families.
CandidateMixtureViewGeneratorConfig Config-as-factory for fixed-count mixed candidate tables.

1.2.1 CandidateMixtureViewGenerator

pose_generation.candidate_mixture.CandidateMixtureViewGenerator(config)

Generate a fixed-size candidate table from multiple sampling families.

The generator retains one safely versioned prepared mesh query across requests. Each request lends that query to every component as request-local state, including paired-view components, without extending its lifetime.

1.2.1.1 Attributes

Name Description
config Return a detached copy of the authoring snapshot used by this runtime.

1.2.1.2 Methods

Name Description
generate_from_typed_sample Generate mixed candidates from an EFM snippet.
generate Generate one concatenated full-shell candidate table.
1.2.1.2.1 generate_from_typed_sample
pose_generation.candidate_mixture.CandidateMixtureViewGenerator.generate_from_typed_sample(
    sample,
    frame_index=None,
    runtime_context=None,
)

Generate mixed candidates from an EFM snippet.

1.2.1.2.2 generate
pose_generation.candidate_mixture.CandidateMixtureViewGenerator.generate(
    reference_pose,
    gt_mesh,
    mesh_verts,
    mesh_faces,
    camera_calib_template,
    occupancy_extent,
    runtime_context=None,
    seed=None,
)

Generate one concatenated full-shell candidate table.

1.2.2 CandidateMixtureViewGeneratorConfig

pose_generation.candidate_mixture.CandidateMixtureViewGeneratorConfig()

Config-as-factory for fixed-count mixed candidate tables.

1.2.2.1 Attributes

Name Description
target_type Return the fixed-count mixed candidate generator runtime type.
base Base generator settings shared by all mixture components.
components Ordered mixture components. Full-shell row order follows this list.
total_count Total full-shell candidate budget across mixture components.
device Return the resolved device shared by all mixture components.
camera_label Base camera label used for typed-snippet generation.

1.2.2.2 Methods

Name Description
upper_bound_free_shell Build the explicit legacy free-shell upper-bound ablation config.
rich_local_five_family Build the previous five-family local sampler for ablation runs.
paired_center_gaze_family Build a 60-row sampler with paired target and forward gaze hypotheses.
radial_target_backtrack_family Build the radial/backtrack rollout-diversity sampler.
1.2.2.2.1 upper_bound_free_shell
pose_generation.candidate_mixture.CandidateMixtureViewGeneratorConfig.upper_bound_free_shell(
    count=60,
)

Build the explicit legacy free-shell upper-bound ablation config.

1.2.2.2.2 rich_local_five_family
pose_generation.candidate_mixture.CandidateMixtureViewGeneratorConfig.rich_local_five_family(
)

Build the previous five-family local sampler for ablation runs.

1.2.2.2.3 paired_center_gaze_family
pose_generation.candidate_mixture.CandidateMixtureViewGeneratorConfig.paired_center_gaze_family(
)

Build a 60-row sampler with paired target and forward gaze hypotheses.

1.2.2.2.4 radial_target_backtrack_family
pose_generation.candidate_mixture.CandidateMixtureViewGeneratorConfig.radial_target_backtrack_family(
)

Build the radial/backtrack rollout-diversity sampler.

This preset mirrors .configs/historical/build_rollouts_v1_diverse.toml: most rows probe radial-towards, radial-away, and revisit-backtrack action families, with a small target-point anchor group for continuity with the target-conditioned default sampler. It is a named data-generation profile only; CandidateMixtureViewGeneratorConfig() keeps the historical 60-row default.

1.3 Functions

Name Description
candidate_position_id Return the stable integer provenance id for a position family.
candidate_strategy_id Return the stable integer provenance id for a view-direction family.

1.3.1 candidate_position_id

pose_generation.candidate_mixture.candidate_position_id(position_mode)

Return the stable integer provenance id for a position family.

1.3.2 candidate_strategy_id

pose_generation.candidate_mixture.candidate_strategy_id(strategy)

Return the stable integer provenance id for a view-direction family.

Back to top