API Reference

Validation

raillabel_providerkit.validation.validate.validate(scene_source: dict | Path, ontology_source: dict | Path | None = None, validate_for_empty_frames: bool = True, validate_for_rail_side_order: bool = True, validate_for_missing_ego_track: bool = True, validate_for_ego_track_both_rails: bool = True, validate_for_sensors: bool = True, validate_for_uris: bool = True, validate_for_dimensions: bool = True, validate_for_horizon: bool = True, validate_for_annotation_type_per_sensor: bool = True, validate_for_transition: bool = True, horizon_tolerance_percent: float = 10.0) → list[Issue]

Validate a scene based on the Deutsche Bahn Requirements.

Args:

scene_source: The scene either as a dictionary or as a Path to the scene source file. ontology_source: The dataset ontology as a dictionary or as a Path to the ontology YAML

file. If not None, issues are returned if the scene contains annotations with invalid attributes or object types. Default is None.

validate_for_empty_frames (optional): If True, issues are returned if the scene contains

sensor frames without annotations. Only checks middle/center cameras and lidar sensors. Default is True.

validate_for_rail_side_order: If True, issues are returned if the scene contains track with

a mismatching rail side order. Default is True.

validate_for_missing_ego_track: If True, issues are returned if the scene contains frames

where the ego track (the track the recording train is driving on) is missing. Checks both middle/center cameras and lidar sensors. Default is True.

validate_for_ego_track_both_rails: If True, issues are returned if the ego track rails

don’t have overlapping y-ranges or don’t have exactly one left and one right rail. Default is True.

validate_for_sensors: If True, issues are returned if the scene contains sensors that are

not supported or have the wrong sensor type.

validate_for_uris: If True, issues are returned if the uri fields in the scene contain

unsupported values.

validate_for_dimensions: If True, issues are returned if the dimensions of cuboids are

outside the expected values range.

validate_for_horizon: If True, issues are returned if annotations cross the horizon. validate_for_annotation_type_per_sensor: Validate that annotation types match sensor types. validate_for_transition: If True, issues are returned if transition annotations have

identical startTrack and endTrack values. Default is True.

horizon_tolerance_percent: Tolerance buffer as percentage above the horizon line.

Annotations within this buffer zone are considered valid. For example, 10.0 means annotations up to 10% above the horizon line are accepted. Default is 10.0 (10% buffer). This only affects track and transition annotations.

Returns:

List of all requirement errors in the scene. If an empty list is returned, then there are no errors present and the scene is valid.

Ontologies

Built-in Ontology Management

Built-in ontology definitions for raillabel-providerkit.

This module provides access to pre-built ontology parameter files that can be used for scene validation. Instead of managing ontology files separately, you can use:

from raillabel_providerkit.ontologies import get_ontology_path

path = get_ontology_path(“osdar26”) issues = validate(scene_path, ontology=path)

All ontology files are stored centrally in the config/ontologies/ directory.

raillabel_providerkit.ontologies.manager.get_ontology_path(ontology_name: str) → Path

Get the path to a built-in ontology file.

Parameters:

ontology_name (str) – Name of the ontology to load. Supported values: - “osdar26”: Extended railway environment ontology (25 classes) - “automatedtrain”: Safety-critical classes for automated train operation - “osdar23”: Original OSDAR23 dataset ontology

Returns:

Path to the ontology YAML file (located in config/ontologies/)

Return type:

Path

Raises:

ValueError – If the ontology name is not recognized

raillabel_providerkit.ontologies.manager.get_schema_path(schema_name: str) → Path

Get the path to a built-in schema file.

Parameters:

schema_name (str) – Name of the schema to load. Supported values: - “raillabel”: Generic RailLabel JSON schema (OpenLABEL subset) - “osdar23”: OSDAR23-specific RailLabel schema - “osdar26”: OSDAR26-specific RailLabel schema - “automatedtrain”: AutomatedTrain-specific RailLabel schema - “understand_ai_t4”: Understand.AI T4 format schema - “ontology”: Ontology validation schema (v2)

Returns:

Path to the schema file (located in config/schemas/)

Return type:

Path

Raises:

ValueError – If the schema name is not recognized

Notes

The ontology-specific schemas (osdar23, osdar26, automatedtrain) are currently identical copies of the base raillabel schema, as they share the same OpenLABEL structure. Ontology-specific validation is handled by the ontology YAML files.

raillabel_providerkit.ontologies.manager.list_available_ontologies() → list[str]

List all available built-in ontologies.

Returns:

List of available ontology names

Return type:

list[str]

raillabel_providerkit.ontologies.manager.list_available_schemas() → list[str]

List all available built-in schemas.

Returns:

List of available schema names

Return type:

list[str]

The raillabel_providerkit provides built-in ontology files that can be used for validation without managing external files.

Available Ontologies

OSDAR26 (osdar26)

Extended railway environment ontology with 25 object classes. Features comprehensive signal aspects (Hp, Ks, Vr, Zs, Sh variants), updated occlusion ranges (0-24%, 25-49%, 50-74%, 75-99%, 100%), and classes for personal_item, pram, scooter, flame, smoke.

AutomatedTrain (automatedtrain)

Specialized ontology for automated train perception and safety-critical annotation. Includes obstacle detection, platform recognition, level crossings, and speed signs.

OSDAR23 (osdar23)

Original railway environment annotation ontology for the OSDAR23 dataset. Standard occlusion ranges (0-25%, 25-50%, 50-75%, 75-99%, 100%).

Usage Examples

from raillabel_providerkit import validate, get_ontology_path, list_available_ontologies

# List available ontologies
ontologies = list_available_ontologies()
print(ontologies)  # ['osdar26', 'automatedtrain', 'osdar23']

# Get ontology path and validate
ontology_path = get_ontology_path("osdar26")
issues = validate("scene.json", ontology=ontology_path)

# Validate with AutomatedTrain ontology
ontology_path = get_ontology_path("automatedtrain")
issues = validate("scene.json", ontology=ontology_path)

Conversion

raillabel_providerkit.convert.convert.convert(data: dict, loader_class: type[LoaderABC] | None = None) → Scene

Convert annotation data from provider formats into raillabel.

Parameters:

  • data (dict) – Raw data in the provider format, that should be converted.

  • loader_class (child-class of raillabel_providerkit.LoaderABC, optional) – Class used for converting the provider formatted data. If None is provided, then one is chosen based on criteria present in the data. Default is None.

Returns:

scene – Scene with the loaded data in the raillabel format.

Return type:

raillabel.Scene

Raises:

raillabel.UnsupportedFormatError – if the annotation file does not match any loaders.

Format Handling

Understand.AI Format

Module containing all relevant understand.ai format classes.

class raillabel_providerkit.format.understand_ai.BoundingBox2d(id: UUID, object_id: UUID, class_name: str, attributes: dict, sensor: SensorReference, x_min: float, y_min: float, x_max: float, y_max: float)

Bases: _Annotation

A 2d bounding box.

Parameters:

  • id (uuid.UUID) – Unique identifier of the annotation.

  • object_id (uuid.UUID) – Unique identifier of the object this annotation refers to. Used for tracking.

  • class_name (str) – Name of the class this annotation belongs to.

  • attributes (dict[str, str or list]) – Key value pairs of attributes with the keys beeing the friendly identifier of the attribute and the value beeing the attribute value.

  • sensor (raillabel.format.understand_ai.SensorReference) – Information about the sensor this annotation is labeled in.

  • x_min (float) – Left corner of the bounding box in pixels.

  • y_min (float) – Top corner of the bounding box in pixels.

  • x_max (float) – Right corner of the bounding box in pixels.

  • y_max (float) – Bottom corner of the bounding box in pixels.

OPENLABEL_ID = 'bbox'
classmethod fromdict(data_dict: dict) → BoundingBox2d

Generate a BoundingBox2d from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted 2d bounding box.

Return type:

BoundingBox2d

x_max: float
x_min: float
y_max: float
y_min: float
class raillabel_providerkit.format.understand_ai.BoundingBox3d(id: UUID, object_id: UUID, class_name: str, attributes: dict, sensor: SensorReference, center: Point3d, size: Size3d, quaternion: Quaternion)

Bases: _Annotation

A 3d bounding box.

Parameters:

  • id (uuid.UUID) – Unique identifier of the annotation.

  • object_id (uuid.UUID) – Unique identifier of the object this annotation refers to. Used for tracking.

  • class_name (str) – Name of the class this annotation belongs to.

  • attributes (dict[str, str or list]) – Key value pairs of attributes with the keys beeing the friendly identifier of the attribute and the value beeing the attribute value.

  • sensor (raillabel.format.understand_ai.SensorReference) – Information about the sensor this annotation is labeled in.

  • center (raillabel.format.understand_ai.Point3d) – Center position of the bounding box.

  • size (raillabel.format.understand_ai.Size3d) – 3d size of the bounding box.

  • quaternion (raillabel.format.understand_ai.Quaternion) – Rotation quaternion of the bounding box.

OPENLABEL_ID = 'cuboid'
center: Point3d
classmethod fromdict(data_dict: dict) → BoundingBox3d

Generate a BoundingBox3d from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted 3d bounding box.

Return type:

BoundingBox3d

quaternion: Quaternion
size: Size3d
class raillabel_providerkit.format.understand_ai.CoordinateSystem(uid: str, topic: str, frame_id: str, position: list[float], rotation_quaternion: list[float], rotation_matrix: list[float], angle_axis_rotation: list[float], homogeneous_transform: list[float] | None = None, measured_position: list[float] | None = None, camera_matrix: list[float] | None = None, dist_coeffs: list[float] | None = None)

Bases: object

Global information for a sensor regarding calibration.

Parameters:

  • uid (str) – Friendly name of the sensor as well as its identifier. Must be unique

  • topic (str) – Rostopic of the sensor.

  • frame_id (str) – Name of the directory containing the files from this sensor.

  • position (list of float) – 3D translation with regards to the origin.

  • rotation_quaternion (list of float) – Rotation quaternion with regards to the origin.

  • rotation_matrix (list of float) – Rotation matrix with regards to the origin.

  • angle_axis_rotation (list of float) – Angle axis rotation with regards to the origin.

  • homogeneous_transform (list of float, optional) – Homogeneous transformation matrix with regards to the origin. Default is None.

  • measured_position (list of float, optional)

  • camera_matrix (list of float, optional) – Camera matrix of the sensor. Only applies to sensors of type camera. Default is None.

  • dist_coeffs (list of float, optional) – Distortion coefficients of the sensor. Only applies to sensors of type camera. Default is None.

angle_axis_rotation: list[float]
camera_matrix: list[float] | None = None
dist_coeffs: list[float] | None = None
frame_id: str
classmethod fromdict(data_dict: dict) → CoordinateSystem

Generate a CoordinateSystem from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data.

Returns:

coordinate_system – Converted coordinate_system.

Return type:

CoordinateSystem

homogeneous_transform: list[float] | None = None
measured_position: list[float] | None = None
position: list[float]
rotation_matrix: list[float]
rotation_quaternion: list[float]
to_raillabel() → tuple[dict, dict]

Convert to a raillabel compatible dict.

Returns:

  • coordinate_system_dict (dict) – Dictionary of the raillabel coordinate system.

  • stream_dict (dict) – Dictionary of the raillabel stream.

topic: str
property translated_uid: str

Return uid translated to raillabel.

uid: str
class raillabel_providerkit.format.understand_ai.Frame(id: int, timestamp: Decimal, bounding_box_2ds: dict[str, BoundingBox2d], bounding_box_3ds: dict[str, BoundingBox3d], polygon_2ds: dict[str, Polygon2d], polyline_2ds: dict[str, Polyline2d], segmentation_3ds: dict[str, Segmentation3d], _annotation_uids: set[str] = None)

Bases: object

A container of dynamic, timewise, information.

Parameters:

  • id (int) – Numerical identifier of the frame. Must be unique within the scene.

  • timestamp (decimal.Decimal) – Timestamp containing the Unix epoch time of the frame with up to nanosecond precision.

  • annotations (dict) – Dictionary containing all annotations. The keys are the uids of the annotations and the values are objects of type BoundingBox2d, BoundingBox3d, Polygon2d, Polyline2d or Segementation3d.

property annotations: dict

Return all annotations of this frame in one dict.

bounding_box_2ds: dict[str, BoundingBox2d]
bounding_box_3ds: dict[str, BoundingBox3d]
classmethod fromdict(data_dict: dict) → Frame

Generate a Frame from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted frame.

Return type:

Frame

id: int
polygon_2ds: dict[str, Polygon2d]
polyline_2ds: dict[str, Polyline2d]
segmentation_3ds: dict[str, Segmentation3d]
timestamp: Decimal
to_raillabel() → dict

Generate a Frame from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted frame.

Return type:

Frame

property translated_objects: dict

Return all objects in this frame and translate them.

Returns:

Dictionary containing all objects. Keys are the object IDs and values are the translated class names.

Return type:

dict

property translated_sensors: dict

Return all sensors in this frame and translates them.

Returns:

Dictionary containing all sensors. Keys are the translated sensor IDs and values are the SensorReference objects.

Return type:

dict

class raillabel_providerkit.format.understand_ai.Metadata(clip_id: str, external_clip_id: str, project_id: str, export_time: str, exporter_version: str, coordinate_system_3d: str, coordinate_system_reference: str, folder_name: str)

Bases: object

Container for metadata information about the scene itself.

Parameters:

  • clip_id (str) – Identifier of the scene for internal purposes.

  • external_clip_id (str) – Identifier of the scene for external purposes.

  • project_id (str) – Identifier of the annotation project.

  • export_time (str) – Timestamp of the export in the format ‘YYYY-MM-DD hh:mm UTC’.

  • exporter_version (str) – Version of the Understand.AI-exporter.

  • coordinate_system_3d (str)

  • coordinate_system_reference (str)

  • folder_name (str) – Directory with the exported reference data (e.g. images, point clouds).

clip_id: str
coordinate_system_3d: str
coordinate_system_reference: str
export_time: str
exporter_version: str
external_clip_id: str
folder_name: str
classmethod fromdict(data_dict: dict) → Metadata

Generate a Metadata from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

metadata – Converted metadata.

Return type:

Metadata

project_id: str
to_raillabel() → dict

Convert to a raillabel compatible dict.

Returns:

metadata – Converted metadata.

Return type:

dict

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

Bases: object

Dimensional information of an object in 3d.

Parameters:

  • x (float) – Position of the object in the x-dimension.

  • y (float) – Position of the object in the y-dimension.

  • z (float) – Position of the object in the z-dimension.

classmethod fromdict(data_dict: dict) → Point3d

Generate a Point3d from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted 3d point.

Return type:

Point3d

x: float
y: float
z: float
class raillabel_providerkit.format.understand_ai.Polygon2d(id: UUID, object_id: UUID, class_name: str, attributes: dict, sensor: SensorReference, points: list[tuple[float, float]])

Bases: _Annotation

A 2d polygon.

Parameters:

  • id (uuid.UUID) – Unique identifier of the annotation.

  • object_id (uuid.UUID) – Unique identifier of the object this annotation refers to. Used for tracking.

  • class_name (str) – Name of the class this annotation belongs to.

  • attributes (dict[str, str or list]) – Key value pairs of attributes with the keys beeing the friendly identifier of the attribute and the value beeing the attribute value.

  • sensor (raillabel.format.understand_ai.SensorReference) – Information about the sensor this annotation is labeled in.

  • points (list[tuple[float, float]]) – 2d points belonging to the polygon.

OPENLABEL_ID = 'poly2d'
classmethod fromdict(data_dict: dict) → Polygon2d

Generate a Polygon2d from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted 2d polygon.

Return type:

Polygon2d

points: list[tuple[float, float]]
to_raillabel() → tuple[dict, str, str, dict]

Convert to a raillabel compatible dict.

Returns:

  • annotation (dict) – Dictionary valid for the raillabel schema.

  • object_id (str) – Friendly identifier of the object this sensor belongs to.

  • class_name (str) – Friendly identifier of the class the annotated object belongs to.

  • sensor_reference (dict) – Dictionary of the sensor reference.

class raillabel_providerkit.format.understand_ai.Polyline2d(id: UUID, object_id: UUID, class_name: str, attributes: dict, sensor: SensorReference, points: list[tuple[float, float]])

Bases: _Annotation

A 2d polyline.

Parameters:

  • id (uuid.UUID) – Unique identifier of the annotation.

  • object_id (uuid.UUID) – Unique identifier of the object this annotation refers to. Used for tracking.

  • class_name (str) – Name of the class this annotation belongs to.

  • attributes (dict[str, str or list]) – Key value pairs of attributes with the keys beeing the friendly identifier of the attribute and the value beeing the attribute value.

  • sensor (raillabel.format.understand_ai.SensorReference) – Information about the sensor this annotation is labeled in.

  • points (list[tuple[float, float]]) – 2d points belonging to the polyline.

OPENLABEL_ID = 'poly2d'
classmethod fromdict(data_dict: dict) → Polyline2d

Generate a Polyline2d from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted 2d polyline.

Return type:

Polyline2d

points: list[tuple[float, float]]
to_raillabel() → tuple[dict, str, str, dict]

Convert to a raillabel compatible dict.

Returns:

  • annotation (dict) – Dictionary valid for the raillabel schema.

  • object_id (str) – Friendly identifier of the object this sensor belongs to.

  • class_name (str) – Friendly identifier of the class the annotated object belongs to.

  • sensor_reference (dict) – Dictionary of the sensor reference.

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

Bases: object

Dimensional information of an object in 3d.

Parameters:

  • x (float) – The x component of the quaternion.

  • y (float) – The y component of the quaternion.

  • z (float) – The z component of the quaternion.

  • w (float) – The w component of the quaternion.

classmethod fromdict(data_dict: dict) → Quaternion

Generate a Quaternion from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted quaternion.

Return type:

Quaternion

w: float
x: float
y: float
z: float
class raillabel_providerkit.format.understand_ai.Scene(metadata: Metadata, coordinate_systems: dict[str, CoordinateSystem], frames: dict[int, Frame])

Bases: object

The root Understand.Ai class, which contains all data.

Parameters:

  • metadata (raillabel.format.understand_ai.Metadata) – Container for metadata information about the scene itself.

  • coordinate_systems (dict[str, raillabel.format.understand_ai.CoordinateSystem]) – Global information for sensors regarding calibration.

  • frames (dict[int, raillabel.format.understand_ai.Frame])

coordinate_systems: dict[str, CoordinateSystem]
frames: dict[int, Frame]
classmethod fromdict(data_dict: dict) → Scene

Generate a Scene from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted scene.

Return type:

Scene

metadata: Metadata
to_raillabel() → dict

Convert to a raillabel compatible dict.

Returns:

Dictionary of the raillabel scene.

Return type:

dict

class raillabel_providerkit.format.understand_ai.Segmentation3d(id: UUID, object_id: UUID, class_name: str, attributes: dict, sensor: SensorReference, associated_points: list[int], number_of_points: int)

Bases: _Annotation

The 3D segmentation of a lidar pointcloud.

Parameters:

  • id (uuid.UUID) – Unique identifier of the annotation.

  • object_id (uuid.UUID) – Unique identifier of the object this annotation refers to. Used for tracking.

  • class_name (str) – Name of the class this annotation belongs to.

  • attributes (dict[str, str or list]) – Key value pairs of attributes with the keys beeing the friendly identifier of the attribute and the value beeing the attribute value.

  • sensor (raillabel.format.understand_ai.SensorReference) – Information about the sensor this annotation is labeled in.

  • associated_points (list[int]) – List of point indices of the lidar pointcloud.

  • number_of_points (int) – Total number of points in the associated_points.

OPENLABEL_ID = 'vec'
associated_points: list[int]
classmethod fromdict(data_dict: dict) → Segmentation3d

Generate a Segmentation3d from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted 3d segmentation.

Return type:

Segmentation3d

number_of_points: int
class raillabel_providerkit.format.understand_ai.SensorReference(type: str, uri: str, timestamp: Decimal)

Bases: object

Information for a sensor in a frame.

Parameters:

  • type (str) – Friendly name of the sensor and its unique identifier.

  • uri (str) – URI to the file containing the frame specific sensor output from the project directory.

  • timestamp (decimal.Decimal) – Unix timestamp of the sensor recording.

classmethod fromdict(data_dict: dict) → SensorReference

Generate a SensorReference from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted sensor reference.

Return type:

SensorReference

timestamp: Decimal
to_raillabel() → tuple[str, dict]

Convert to a raillabel compatible dict.

Returns:

  • sensor_id (str) – Friendly identifier of the sensor.

  • sensor_reference (dict) – Dictionary valid for the raillabel schema.

type: str
uri: str
class raillabel_providerkit.format.understand_ai.Size3d(width: float, length: float, height: float)

Bases: object

Dimensional information of an object in 3d.

Parameters:

  • width (float) – Size of the object in the x-dimension.

  • length (float) – Size of the object in the y-dimension.

  • height (float) – Size of the object in the z-dimension.

classmethod fromdict(data_dict: dict) → Size3d

Generate a Size3d from a dictionary in the UAI format.

Parameters:

data_dict (dict) – Understand.AI T4 format dictionary containing the data_dict.

Returns:

Converted 3d size.

Return type:

Size3d

height: float
length: float
width: float

Exceptions