raillabel.format package

Submodules

Module contents

Module containing all relevant format classes.

class raillabel.format.Bbox(pos: Point2d, size: Size2d, object_id: UUID, sensor_id: str, attributes: dict[str, float | bool | str | list])

Bases: object

A 2D bounding box in an image.

attributes: dict[str, float | bool | str | list]

Additional information associated with the annotation.

classmethod from_json(json: JSONBbox, object_id: UUID) → Bbox

Construct an instant of this class from RailLabel JSON data.

name(object_type: str) → str

Return the name of the annotation used for indexing in the object data pointers.

object_id: UUID

The unique identifyer of the real-life object, this annotation belongs to.

pos: Point2d

The center point of the bbox in pixels.

sensor_id: str

The unique identifyer of the sensor this annotation is labeled in.

size: Size2d

The dimensions of the bbox in pixels from the top left corner to the bottom right corner.

to_json(uid: UUID, object_type: str) → JSONBbox

Export this object into the RailLabel JSON format.

class raillabel.format.Camera(intrinsics: IntrinsicsPinhole, extrinsics: Transform | None = None, uri: str | None = None, description: str | None = None, TYPE: str = 'camera')

Bases: object

A camera sensor.

TYPE: str = 'camera'
description: str | None = None

Additional information about the sensor.

extrinsics: Transform | None = None

External calibration of the sensor defined by the 3D transform to the coordinate system origin.

classmethod from_json(json_stream: JSONStreamCamera, json_coordinate_system: JSONCoordinateSystem) → Camera

Construct an instant of this class from RailLabel JSON data.

intrinsics: IntrinsicsPinhole

The intrinsic calibration of the sensor.

to_json() → tuple[JSONStreamCamera, JSONCoordinateSystem]

Export this object into the RailLabel JSON format.

uri: str | None = None

Name of the subdirectory containing the sensor files.

class raillabel.format.Cuboid(pos: Point3d, quat: Quaternion, size: Size3d, object_id: UUID, sensor_id: str, attributes: dict[str, float | bool | str | list])

Bases: object

3D bounding box.

attributes: dict[str, float | bool | str | list]

Additional information associated with the annotation.

classmethod from_json(json: JSONCuboid, object_id: UUID) → Cuboid

Construct an instant of this class from RailLabel JSON data.

name(object_type: str) → str

Return the name of the annotation used for indexing in the object data pointers.

object_id: UUID

The unique identifyer of the real-life object, this annotation belongs to.

pos: Point3d

The center position of the cuboid in meters, where the x coordinate points ahead of the vehicle, y points to the left and z points upwards.

quat: Quaternion

The rotation of the cuboid in quaternions.

sensor_id: str

The unique identifyer of the sensor this annotation is labeled in.

size: Size3d

The size of the cuboid in meters.

to_json(uid: UUID, object_type: str) → JSONCuboid

Export this object into the RailLabel JSON format.

class raillabel.format.Frame(timestamp: ~decimal.Decimal | None = None, sensors: dict[str, ~raillabel.format.sensor_reference.SensorReference] = <factory>, frame_data: dict[str, ~raillabel.format.num.Num] = <factory>, annotations: dict[~uuid.UUID, ~raillabel.format.bbox.Bbox | ~raillabel.format.cuboid.Cuboid | ~raillabel.format.poly2d.Poly2d | ~raillabel.format.poly3d.Poly3d | ~raillabel.format.seg3d.Seg3d] = <factory>)

Bases: object

A container of dynamic, timewise, information.

annotations: dict[UUID, Bbox | Cuboid | Poly2d | Poly3d | Seg3d]

All annotations of this frame.

frame_data: dict[str, Num]

Dictionary containing data directly connected to the frame and not to any object, like gps/imu data. Dictionary keys are the ID-strings of the variable the data belongs to.

classmethod from_json(json: JSONFrame) → Frame

Construct an instant of this class from RailLabel JSON data.

sensors: dict[str, SensorReference]

References to the sensors with frame specific information like timestamp and uri.

timestamp: Decimal | None = None

Timestamp containing the Unix epoch time of the frame with up to nanosecond precision.

to_json(objects: dict[UUID, Object]) → JSONFrame

Export this object into the RailLabel JSON format.

class raillabel.format.FrameInterval(start: int, end: int)

Bases: object

Closed interval of frames.

end: int

Ending frame number of the interval (inclusive).

classmethod from_frame_ids(frame_ids: list[int]) → list[FrameInterval]

Convert a list of frame uids into FrameIntervals.

Example: .. code-block:: python

FrameInterval.from_frame_ids([0, 1, 2, 3, 9, 12, 13, 14]) == [

FrameInterval(0, 3), FrameInterval(9, 9), FrameInterval(12, 14),

]

classmethod from_json(json: JSONFrameInterval) → FrameInterval

Construct an instant of this class from RailLabel JSON data.

start: int

Initial frame number of the interval (inclusive).

to_json() → JSONFrameInterval

Export this object into the RailLabel JSON format.

class raillabel.format.GpsImu(extrinsics: Transform | None = None, uri: str | None = None, description: str | None = None)

Bases: _SensorWithoutIntrinsics

A gps sensor with inertial measurement unit.

TYPE: str = 'gps_imu'
classmethod from_json(json_stream: JSONStreamOther, json_coordinate_system: JSONCoordinateSystem) → GpsImu

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[JSONStreamOther, JSONCoordinateSystem]

Export this object into the RailLabel JSON format.

class raillabel.format.IntrinsicsPinhole(camera_matrix: tuple[float, float, float, float, float, float, float, float, float, float, float, float], distortion: tuple[float, float, float, float, float], width_px: int, height_px: int)

Bases: object

Intrinsic calibration for a camera sensor.

camera_matrix: tuple[float, float, float, float, float, float, float, float, float, float, float, float]

This is a 3x4 camera matrix which projects 3D homogeneous points (4x1) from a camera coordinate system into the image plane (3x1). This is the usual K matrix for camera projection as in OpenCV. It is extended from 3x3 to 3x4 to enable its direct utilisation to project 4x1 homogeneous 3D points. The matrix is defined to follow the camera model: x-to-right, y-down, z-forward. The following equation applies: x_img = camera_matrix * X_ccs.

distortion: tuple[float, float, float, float, float]

This is the array 1x5 radial and tangential distortion coefficients.

classmethod from_json(json: JSONIntrinsicsPinhole) → IntrinsicsPinhole

Construct an instant of this class from RailLabel JSON data.

height_px: int

Height of the image frame in pixel.

to_json() → JSONIntrinsicsPinhole

Export this object into the RailLabel JSON format.

width_px: int

Width of the image frame in pixel.

class raillabel.format.IntrinsicsRadar(resolution_px_per_m: float, width_px: int, height_px: int)

Bases: object

Intrinsic calibration for a radar sensor.

classmethod from_json(json: JSONIntrinsicsRadar) → IntrinsicsRadar

Construct an instant of this class from RailLabel JSON data.

height_px: int

Height of the cartesian image frame in pixel.

resolution_px_per_m: float

Factor for calculating the 3D coordinates of a pixel in the cartesian radar images. Number of pixels in the images per meter from the sensor.

to_json() → JSONIntrinsicsRadar

Export this object into the RailLabel JSON format.

width_px: int

Width of the cartesian image frame in pixel.

class raillabel.format.Lidar(extrinsics: Transform | None = None, uri: str | None = None, description: str | None = None)

Bases: _SensorWithoutIntrinsics

A lidar sensor.

TYPE: str = 'lidar'
classmethod from_json(json_stream: JSONStreamOther, json_coordinate_system: JSONCoordinateSystem) → Lidar

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[JSONStreamOther, JSONCoordinateSystem]

Export this object into the RailLabel JSON format.

class raillabel.format.Metadata(schema_version: str, annotator: str | None = None, comment: str | None = None, exporter_version: str | None = None, file_version: str | None = None, name: str | None = None, subschema_version: str | None = None, tagged_file: str | None = None)

Bases: object

Container for metadata information about the scene itself.

annotator: str | None = None

Name or description of the annotator that created the annotations.

comment: str | None = None

Additional information or description about the annotation content.

exporter_version: str | None = None

Version of the raillabel-devkit, that last exported the scene.

file_version: str | None = None

Version number of the raillabel annotation content.

classmethod from_json(json: JSONMetadata) → Metadata

Construct an instant of this class from RailLabel JSON data.

name: str | None = None

Name of the raillabel annotation content.

schema_version: str

Version number of the OpenLABEL schema this annotation object follows.

subschema_version: str | None = None

Version number of the RailLabel schema this annotation object follows.

tagged_file: str | None = None

Directory with the exported data_dict (e.g. images, point clouds).

to_json() → JSONMetadata

Export this object into the RailLabel JSON format.

class raillabel.format.Num(name: str, val: float, id: UUID | None = None, sensor_id: str | None = None)

Bases: object

A number.

classmethod from_json(json: JSONNum) → Num

Construct an instant of this class from RailLabel JSON data.

id: UUID | None = None

The unique identifyer of the Num.

name: str

Human readable name describing the annotation.

sensor_id: str | None = None

A reference to the sensor, this value is represented in.

to_json() → JSONNum

Export this object into the RailLabel JSON format.

val: float

This is the value of the number object.

class raillabel.format.Object(name: str, type: str)

Bases: object

Physical, unique object in the data, that can be tracked via its UID.

classmethod from_json(json: JSONObject) → Object

Construct an instant of this class from RailLabel JSON data.

name: str

Name of the object. It is a friendly name and not used for indexing. Commonly the class name is used followed by an underscore and an integer (i.e. person_0032).

to_json(object_id: UUID, frames: dict[int, Frame]) → JSONObject

Export this object into the RailLabel JSON format.

type: str

The type of an object defines the class the object corresponds to (like ‘person’).

class raillabel.format.OtherSensor(extrinsics: Transform | None = None, uri: str | None = None, description: str | None = None)

Bases: _SensorWithoutIntrinsics

A sensor that is not represented by the available options.

TYPE: str = 'other'
classmethod from_json(json_stream: JSONStreamOther, json_coordinate_system: JSONCoordinateSystem) → OtherSensor

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[JSONStreamOther, JSONCoordinateSystem]

Export this object into the RailLabel JSON format.

class raillabel.format.Point2d(x: float, y: float)

Bases: object

A 2d point in an image.

classmethod from_json(json: tuple[float, float]) → Point2d

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[float, float]

Export this object into the RailLabel JSON format.

x: float

The x-coordinate of the point in the image in pixels from the left.

y: float

The y-coordinate of the point in the image in pixels from the top.

class raillabel.format.Point3d(x: float, y: float, z: float)

Bases: object

A point in the 3D space.

classmethod from_json(json: tuple[float, float, float]) → Point3d

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[float, float, float]

Export this object into the RailLabel JSON format.

x: float

The x-coordinate of the point.

y: float

The y-coordinate of the point.

z: float

The z-coordinate of the point.

class raillabel.format.Poly2d(points: list[Point2d], closed: bool, object_id: UUID, sensor_id: str, attributes: dict[str, float | bool | str | list])

Bases: object

Sequence of 2D points. Can either be a polygon or polyline.

attributes: dict[str, float | bool | str | list]

Additional information associated with the annotation.

closed: bool

If True, this object represents a polygon and if False, it represents a polyline.

classmethod from_json(json: JSONPoly2d, object_id: UUID) → Poly2d

Construct an instant of this class from RailLabel JSON data.

name(object_type: str) → str

Return the name of the annotation used for indexing in the object data pointers.

object_id: UUID

The unique identifyer of the real-life object, this annotation belongs to.

points: list[Point2d]

List of the 2d points that make up the polyline.

sensor_id: str

The unique identifyer of the sensor this annotation is labeled in.

to_json(uid: UUID, object_type: str) → JSONPoly2d

Export this object into the RailLabel JSON format.

class raillabel.format.Poly3d(points: list[Point3d], closed: bool, object_id: UUID, sensor_id: str, attributes: dict[str, float | bool | str | list])

Bases: object

Sequence of 3D points. Can either be a polygon or polyline.

attributes: dict[str, float | bool | str | list]

Additional information associated with the annotation.

closed: bool

If True, this object represents a polygon and if False, it represents a polyline.

classmethod from_json(json: JSONPoly3d, object_id: UUID) → Poly3d

Construct an instant of this class from RailLabel JSON data.

name(object_type: str) → str

Return the name of the annotation used for indexing in the object data pointers.

object_id: UUID

The unique identifyer of the real-life object, this annotation belongs to.

points: list[Point3d]

List of the 3d points that make up the polyline.

sensor_id: str

The unique identifyer of the sensor this annotation is labeled in.

to_json(uid: UUID, object_type: str) → JSONPoly3d

Export this object into the RailLabel JSON format.

class raillabel.format.Quaternion(x: float, y: float, z: float, w: float)

Bases: object

A rotation represented by a quaternion.

classmethod from_json(json: tuple[float, float, float, float]) → Quaternion

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[float, float, float, float]

Export this object into the RailLabel JSON format.

w: float

The omega component of the quaternion.

x: float

The x component of the quaternion.

y: float

The y component of the quaternion.

z: float

The z component of the quaternion.

class raillabel.format.Radar(intrinsics: IntrinsicsRadar, extrinsics: Transform | None = None, uri: str | None = None, description: str | None = None, TYPE: str = 'radar')

Bases: object

A radar sensor.

TYPE: str = 'radar'
description: str | None = None

Additional information about the sensor.

extrinsics: Transform | None = None

External calibration of the sensor defined by the 3D transform to the coordinate system origin.

classmethod from_json(json_stream: JSONStreamRadar, json_coordinate_system: JSONCoordinateSystem) → Radar

Construct an instant of this class from RailLabel JSON data.

intrinsics: IntrinsicsRadar

The intrinsic calibration of the sensor.

to_json() → tuple[JSONStreamRadar, JSONCoordinateSystem]

Export this object into the RailLabel JSON format.

uri: str | None = None

Name of the subdirectory containing the sensor files.

class raillabel.format.Scene(metadata: ~raillabel.format.metadata.Metadata, sensors: dict[str, ~raillabel.format.camera.Camera | ~raillabel.format.lidar.Lidar | ~raillabel.format.radar.Radar | ~raillabel.format.gps_imu.GpsImu | ~raillabel.format.other_sensor.OtherSensor] = <factory>, objects: dict[~uuid.UUID, ~raillabel.format.object.Object] = <factory>, frames: dict[int, ~raillabel.format.frame.Frame] = <factory>)

Bases: object

The root RailLabel class, which contains all data.

Examples: You can load scenes like this:

import raillabel
scene = raillabel.load("path/to/scene.json")

The scenes then contain all of the data. This is how you can iterate over the annotations:

for frame in scene.frames.values():
    for annotation in frame.annotations.values():
        pass  # do something with the annotation here
filter(filters: list[_FilterAbc]) → Scene

Return a scene with annotations, sensors, objects and frames excluded.

Example:

from raillabel.filter import (
    IncludeObjectTypeFilter,
    ExcludeAnnotationTypeFilter,
    StartTimeFilter, ExcludeFrameIdFilter,
    IncludeAttributesFilter
)

scene_with_only_trains = scene.filter([IncludeObjectTypeFilter(["rail_vehicle"])])

scene_without_bboxs = scene.filter([ExcludeAnnotationTypeFilter(["bbox"])])

cut_scene_with_only_red_trains = scene.filter([
    StartTimeFilter("1587349200.004200000"),
    ExcludeFrameIdFilter([2, 4]),
    IncludeObjectTypeFilter(["rail_vehicle"]),
    IncludeAttributesFilter({"color": "red"}),
])
frames: dict[int, Frame]

A container of dynamic, timewise, information. Keys are the frame integer number.

classmethod from_json(json: JSONScene) → Scene

Construct a scene from a json object.

metadata: Metadata

Container of information about the annotation file itself.

objects: dict[UUID, Object]

Unique objects (like a specific person) in this scene. Keys are object uuids

sensors: dict[str, Camera | Lidar | Radar | GpsImu | OtherSensor]

The sensors used in this scene. Keys are sensor names.

to_json() → JSONScene

Export this scene into the RailLabel JSON format.

class raillabel.format.Seg3d(point_ids: list[int], object_id: UUID, sensor_id: str, attributes: dict[str, float | bool | str | list])

Bases: object

The 3D segmentation of a lidar pointcloud.

attributes: dict[str, float | bool | str | list]

Additional information associated with the annotation.

classmethod from_json(json: JSONVec, object_id: UUID) → Seg3d

Construct an instant of this class from RailLabel JSON data.

name(object_type: str) → str

Return the name of the annotation used for indexing in the object data pointers.

object_id: UUID

The unique identifyer of the real-life object, this annotation belongs to.

point_ids: list[int]

The list of point indices.

sensor_id: str

The unique identifyer of the sensor this annotation is labeled in.

to_json(uid: UUID, object_type: str) → JSONVec

Export this object into the RailLabel JSON format.

class raillabel.format.SensorReference(timestamp: Decimal, uri: str | None = None)

Bases: object

A reference to a sensor in a specific frame.

classmethod from_json(json: JSONStreamSync) → SensorReference

Construct an instant of this class from RailLabel JSON data.

timestamp: Decimal

Timestamp containing the Unix epoch time of the sensor in a specific frame with up to nanosecond precision.

to_json() → JSONStreamSync

Export this object into the RailLabel JSON format.

uri: str | None = None

URI to the file corresponding to the frame recording in the particular frame.

class raillabel.format.Size2d(x: float, y: float)

Bases: object

The size of a rectangle in a 2d image.

classmethod from_json(json: tuple[float, float]) → Size2d

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[float, float]

Export this object into the RailLabel JSON format.

x: float

The size along the x-axis.

y: float

The size along the y-axis.

class raillabel.format.Size3d(x: float, y: float, z: float)

Bases: object

The 3D size of a cube.

classmethod from_json(json: tuple[float, float, float]) → Size3d

Construct an instant of this class from RailLabel JSON data.

to_json() → tuple[float, float, float]

Export this object into the RailLabel JSON format.

x: float

The size along the x-axis.

y: float

The size along the y-axis.

z: float

The size along the z-axis.

class raillabel.format.Transform(pos: Point3d, quat: Quaternion)

Bases: object

A transformation between two coordinate systems.

classmethod from_json(json: JSONTransformData) → Transform

Construct an instant of this class from RailLabel JSON data.

pos: Point3d

Translation with regards to the parent coordinate system.

quat: Quaternion

Rotation quaternion with regards to the parent coordinate system.

to_json() → JSONTransformData

Export this object into the RailLabel JSON format.