Observation

Observation#

class rapidtools.core.Observation(image_id: str, label: str, polygon: list[tuple[float, float]], camera_lon: float, camera_lat: float, compass_angle: float, is_pano: bool = True, sequence_id: str | None = None, captured_at: str | None = None, confidence: float | None = None, source: str = 'mapillary', bearing: float | None = None, elevation: float | None = None, range_m: float | None = None, lon: float | None = None, lat: float | None = None, image_width: int | None = None, image_height: int | None = None, extra: dict[str, ~typing.Any] = <factory>)[source]#

Bases: object

One sighting of an object in a street-level image.

Variables:

  • image_id (str) – Provider image identifier (Mapillary image key).

  • label (str) – Class label of the detection, in the provider’s vocabulary for Mapillary detections ('object--vehicle--car') or the text prompt for model-based detections.

  • polygon (list[tuple[float, float]]) – Exterior ring of the detection in normalised image coordinates: x grows to the right and y downwards, both in [0, 1].

  • camera_lon (float) – Longitude of the camera in WGS84 degrees.

  • camera_lat (float) – Latitude of the camera in WGS84 degrees.

  • compass_angle (float) – Heading of the image centre column in degrees clockwise from north.

  • is_pano (bool) – True for equirectangular panoramas (360 degrees across the width, 180 down the height).

  • sequence_id (str | None) – Capture sequence the image belongs to; observations of one sequence share a camera rig.

  • captured_at (str | None) – Capture date or timestamp as an ISO string.

  • confidence (float | None) – Detector confidence in [0, 1] when the provider reports one.

  • source (str) – Where the detection came from: 'mapillary' or 'sam3'.

  • bearing (float | None) – Absolute bearing from the camera to the object, degrees clockwise from north. Filled in by the localisation step.

  • elevation (float | None) – Elevation angle of the object’s ground contact (its lowest pixel) in degrees; negative below the horizon.

  • range_m (float | None) – Estimated horizontal distance from camera to object in metres.

  • lon (float | None) – Single-view estimate of the object’s longitude.

  • lat (float | None) – Single-view estimate of the object’s latitude.

  • image_width (int | None) – Pixel width of the source image, when known.

  • image_height (int | None) – Pixel height of the source image, when known.

  • extra (dict[str, Any]) – Free-form provider metadata.

Methods

from_dict

Rebuild an observation from to_dict() output.

to_dict

Return a JSON-serialisable dictionary of the observation.
property bbox: tuple[float, float, float, float]#

Axis-aligned bounds of the polygon as (min_x, min_y, max_x, max_y).

Example

>>> Observation('i', 'car', [(0.1, 0.2), (0.3, 0.2), (0.3, 0.4)],
...             0.0, 0.0, 0.0).bbox
(0.1, 0.2, 0.3, 0.4)
property area: float#

Polygon area as a fraction of the image (shoelace formula).

Example

>>> Observation('i', 'car', [(0, 0), (0.5, 0), (0.5, 0.5), (0, 0.5)],
...             0.0, 0.0, 0.0).area
0.25
property has_location: bool#

True once a single-view ground position has been estimated.

to_dict() → dict[str, Any][source]#

Return a JSON-serialisable dictionary of the observation.

Example

>>> obs = Observation('i', 'car', [(0, 0), (1, 0), (1, 1)], 1.0, 2.0, 3.0)
>>> d = obs.to_dict()
>>> d['image_id'], d['polygon'][0]
('i', [0.0, 0.0])
classmethod from_dict(data: dict[str, Any]) → Observation[source]#

Rebuild an observation from to_dict() output.

Unknown keys are kept under extra so records written by a newer version still load.

Example

>>> Observation.from_dict({
...     'image_id': 'i', 'label': 'car',
...     'polygon': [[0, 0], [1, 0], [1, 1]],
...     'camera_lon': 1.0, 'camera_lat': 2.0, 'compass_angle': 3.0,
... }).label
'car'