Skip to content

Observation API

Repository: https://github.com/OlafenwaMoses/vizion3D

vizion3d.observation

ScaleObservation task direct Python entry point.

ObjectScaleObservation

Bases: BaseModel

Normalised per-object evidence used by ScaleObservation.

Source code in vizion3d/observation/models.py 
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
class ObjectScaleObservation(BaseModel):
    """Normalised per-object evidence used by ScaleObservation."""

    instance_id: int
    label: str
    canonical_label: str | None = None
    prior_source: str = "unknown"
    class_id: int | None
    confidence: float
    bbox_2d: list[float]
    bbox_area_ratio: float = 0.0
    touches_edge: bool = False
    point_count: int
    clean_point_count: int
    centroid: list[float] = Field(default_factory=list)
    depth_band: str = "unknown"
    horizontal_band: str = "unknown"
    vertical_band: str = "unknown"
    observed_dimensions: dict[str, float]
    mask_area_ratio: float = 0.0
    mask_bbox_fill: float = 0.0
    depth_spread_ratio: float = 0.0
    axis_agreement_score: float
    prior_available: bool
    accepted: bool
    rejection_reasons: list[str] = Field(default_factory=list)
    quality: float = 0.0

ScaleCandidate

Bases: BaseModel

Single object/dimension-derived scale candidate.

Source code in vizion3d/observation/models.py 
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
class ScaleCandidate(BaseModel):
    """Single object/dimension-derived scale candidate."""

    label: str
    canonical_label: str | None = None
    prior_source: str = "unknown"
    dimension: str
    observed_relative: float
    prior_m: float
    scale: float
    weight: float
    accepted: bool = False
    rejection_reason: str | None = None
    instance_id: int | None = None
    class_id: int | None = None
    object_quality: float = 1.0
    dimension_reliability: float = 1.0
    point_count: int = 0
    clean_point_count: int = 0
    bbox_area_ratio: float | None = None
    touches_edge: bool = False
    calibration_factor: float = 1.0
    prior_sigma_m: float | None = None
    prior_uncertainty_score: float = 1.0
    axis_agreement_score: float = 1.0
    scene_plausibility_score: float = 1.0

ScaleObservation

Facade for the ScaleObservation task.

Source code in vizion3d/observation/__init__.py 
19
20
21
22
23
24
25
26
27
class ScaleObservation:
    """Facade for the ScaleObservation task."""

    experimental: bool = False

    def run(self, command: ScaleObservationCommand) -> ScaleObservationResult:
        """Dispatch *command* through the CQRS bus to the registered handler."""

        return command_bus.dispatch(command)

run(command)

Dispatch command through the CQRS bus to the registered handler.

Source code in vizion3d/observation/__init__.py 
24
25
26
27
def run(self, command: ScaleObservationCommand) -> ScaleObservationResult:
    """Dispatch *command* through the CQRS bus to the registered handler."""

    return command_bus.dispatch(command)

ScaleObservationAdvancedConfig

Bases: BaseModel

Camera/image settings for ScaleObservation geometry outputs.

Source code in vizion3d/observation/models.py 
32
33
34
35
36
37
38
39
40
class ScaleObservationAdvancedConfig(BaseModel):
    """Camera/image settings for ScaleObservation geometry outputs."""

    image_width: int | None = None
    image_height: int | None = None
    fx: float | None = None
    fy: float | None = None
    cx: float | None = None
    cy: float | None = None

ScaleObservationCommand dataclass

Bases: Command[ScaleObservationResult]

Command payload to estimate metric scale for a generated point cloud.

Attributes:

Name Type Description
point_cloud object

Open3D point cloud, PLY bytes, or a PLY file path.
annotations list[MaskAnnotation3D] | list[dict[str, Any]] | None

Usually ObjectMaskAnnotation3DResult.annotations. JSON-compatible dictionaries are also accepted for REST/gRPC adapters.
image_input str | bytes | None

Optional RGB image path or bytes. The current runtime only uses this for future extensibility; annotations are the scale evidence.
return_scaled_point_cloud bool

Include a uniformly scaled Open3D point cloud.
return_scaled_depth bool

Include a projected camera-space Z depth image when intrinsics and image dimensions are provided.
config ScaleObservationConfig

ScaleObservation estimator configuration. Defaults to promoted V4.1.
advanced_config ScaleObservationAdvancedConfig

Image size and camera intrinsics for bbox edge checks and optional scaled-depth reprojection.
Source code in vizion3d/observation/commands.py 
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
@dataclass
class ScaleObservationCommand(Command[ScaleObservationResult]):
    """Command payload to estimate metric scale for a generated point cloud.

    Attributes:
        point_cloud: Open3D point cloud, PLY bytes, or a PLY file path.
        annotations: Usually ``ObjectMaskAnnotation3DResult.annotations``.
            JSON-compatible dictionaries are also accepted for REST/gRPC adapters.
        image_input: Optional RGB image path or bytes. The current runtime only
            uses this for future extensibility; annotations are the scale evidence.
        return_scaled_point_cloud: Include a uniformly scaled Open3D point cloud.
        return_scaled_depth: Include a projected camera-space Z depth image when
            intrinsics and image dimensions are provided.
        config: ScaleObservation estimator configuration. Defaults to promoted V4.1.
        advanced_config: Image size and camera intrinsics for bbox edge checks
            and optional scaled-depth reprojection.
    """

    point_cloud: object
    annotations: list[MaskAnnotation3D] | list[dict[str, Any]] | None = None
    image_input: str | bytes | None = None
    return_scaled_point_cloud: bool = False
    return_scaled_depth: bool = False
    return_report: bool = True
    config: ScaleObservationConfig = field(default_factory=ScaleObservationConfig)
    advanced_config: ScaleObservationAdvancedConfig = field(
        default_factory=ScaleObservationAdvancedConfig
    )

ScaleObservationConfig

Bases: BaseModel

Runtime configuration for the promoted ScaleObservation estimator.

Source code in vizion3d/observation/models.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class ScaleObservationConfig(BaseModel):
    """Runtime configuration for the promoted ScaleObservation estimator."""

    name: str = "v4_1_yoloe_strong_dimension_class_trimmed_huber"
    candidate_source: str = "yoloe_strong"
    aggregate: str = "dimension_class_trimmed_huber"
    prior: float = 0.30
    prior_weight: float = 0.015
    quality_power: float = 0.20
    confidence_power: float = 1.0
    min_candidate_weight: float = 1e-6
    no_candidate: str = "prior"
    prior_weight_power: float = 1.75
    winsor_quantile: float = 0.08
    huber_delta: float = 0.12
    object_weight_power: float = 1.1
    min_object_weight: float = 0.02

ScaleObservationResult

Bases: BaseModel

Result payload returned by ScaleObservation.

Source code in vizion3d/observation/models.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
class ScaleObservationResult(BaseModel):
    """Result payload returned by ScaleObservation."""

    scale_factor: float
    scale_confidence: float
    scale_confidence_reason: str
    algorithm_version: str
    candidates: list[ScaleCandidate]
    object_observations: list[ObjectScaleObservation] = Field(default_factory=list)
    accepted_candidates: int
    rejected_candidates: int
    scaled_point_cloud: O3dPointCloud | None = None
    scaled_depth_image: O3dImage | None = None
    scaled_depth_metadata: ScaledDepthMetadata | None = None
    scale_report: dict[str, Any] = Field(default_factory=dict)

    model_config = ConfigDict(arbitrary_types_allowed=True)

ScaledDepthMetadata

Bases: BaseModel

Metadata for a scaled depth image reprojected from a scaled point cloud.

Source code in vizion3d/observation/models.py 
100
101
102
103
104
105
106
107
class ScaledDepthMetadata(BaseModel):
    """Metadata for a scaled depth image reprojected from a scaled point cloud."""

    dtype: str = "float32"
    units: str = "metres"
    invalid_value: float = 0.0
    coordinate_space: str = "OpenGL camera space: X right, Y up, Z negative forward"
    z_buffer_policy: str = "nearest point wins"