Skip to content

Futures Models

mosaicolabs.models.futures.laser._LaserScanBase

Bases: BaseModel

Internal generic base model shared by laser scan ontologies.

Encodes the scan geometry, timing metadata, and range and intensity arrays that are common to both single-return and multi-echo laser scanners.

This class is not intended to be instantiated directly. Use one of the concrete subclasses: LaserScan or MultiEchoLaserScan.

Attributes:

Name Type Description
angle_min float32

Start angle of the scan in radians.
angle_max float32

End angle of the scan in radians.
angle_increment float32

Angular step between consecutive beams in radians.
time_increment float32

Time elapsed between consecutive beam measurements in seconds.
scan_time float32

Total duration of one full scan in seconds.
range_min float32

Minimum valid range value in meters; measurements below this threshold should be discarded.
range_max float32

Maximum valid range value in meters; measurements above this threshold should be discarded.
ranges float32

Range measurements for each beam. Shape depends on T.
intensities float32

Intensity measurements for each beam, co-indexed with ranges (optional). Shape depends on T.
Querying with the .Q Proxy

Scalar fields on this model are fully queryable via the .Q proxy. List-typed fields (ranges, intensities) are not queryable.

Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.angle_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.angle_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.time_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.scan_time Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.range_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.range_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find scans with a wide field of view and a long maximum range
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_max.gt(30.0))
            .with_expression(LaserScan.Q.angle_max.geq(3.14)),
        )

        # Inspect the response
        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

        # Same query, also extracting the first and last occurrence times
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_max.gt(30.0), include_timestamp_range=True)
            .with_expression(LaserScan.Q.angle_max.geq(3.14)),
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {{topic.name: "
                      f"[topic.timestamp_range.start, topic.timestamp_range.end] "
                      f"for topic in item.topics}}")

angle_min class-attribute instance-attribute 

angle_min = MosaicoField(
    description="start angle of the scan in rad."
)

Start angle of the scan in radians.

Defines the angular position of the first beam in the sweep.Together with angle_max and angle_increment, it fully characterises the angular coverage of the scan.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_min.geq(-3.14))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

angle_max class-attribute instance-attribute 

angle_max = MosaicoField(
    description="end angle of the scan in rad."
)

End angle of the scan in radians.

Defines the angular position of the last beam in the sweep. The total field of view of the scanner is angle_max - angle_min.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_max.geq(3.14))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

angle_increment class-attribute instance-attribute 

angle_increment = MosaicoField(
    description="angular distance between measurements in rad."
)

Angular step between consecutive beams in radians.

The number of beams in a sweep can be derived as round((angle_max - angle_min) / angle_increment) + 1. A negative value indicates a clockwise scan direction.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find high-resolution scans (small angular step)
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_increment.lt(0.01))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

time_increment class-attribute instance-attribute 

time_increment = MosaicoField(
    description="time between measurements in seconds."
)

Time elapsed between consecutive beam measurements, in seconds.

If the scanner is moving, this will be used in interpoling position of 3D points.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.time_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.time_increment.lt(0.0001))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

scan_time class-attribute instance-attribute 

scan_time = MosaicoField(
    description="time between scans in seconds."
)

Time between scans in seconds.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.scan_time Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find sequences recorded at 10 Hz (scan_time ≈ 0.1 s)
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.scan_time.between([0.09, 0.11]))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

range_min class-attribute instance-attribute 

range_min = MosaicoField(
    description="minimum range value in meters."
)

Minimum valid range value, in meters.

Measurements strictly below this threshold are outside the sensor's reliable operating range and should be discarded or treated as invalid during downstream processing.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.range_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_min.leq(0.1))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

range_max class-attribute instance-attribute 

range_max = MosaicoField(
    description="maximum range value in meters."
)

Maximum valid range value, in meters.

Measurements strictly above this threshold exceed the sensor's maximum detection distance and should be discarded or treated as invalid during downstream processing.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.range_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find long-range scanner sessions
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_max.gt(30.0))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

mosaicolabs.models.futures.LaserScan

Bases: _LaserScanBase, Serializable

Single-return 2D laser scan data.

This model represents one sweep of a single-return laser range finder. Each beam yields exactly one range measurement, corresponding to the strongest or first detected echo.

ranges and intensities are flat List[float] whose i-th element corresponds to the beam at angular position angle_min + i * angle_increment.

Attributes:

Name Type Description
angle_min float32

Start angle of the scan in radians.
angle_max float32

End angle of the scan in radians.
angle_increment float32

Angular step between consecutive beams in radians.
time_increment float32

Time between consecutive beam measurements in seconds.
scan_time float32

Total duration of one full scan in seconds.
range_min float32

Minimum valid range threshold in meters.
range_max float32

Maximum valid range threshold in meters.
ranges SingleRange

Measured distance per beam in meters.
intensities Optional[SingleRange]

Signal amplitude per beam (optional).
Note

List-typed fields are not queryable via the .Q proxy. The .Q proxy is not available on this model.

Querying with the .Q Proxy

Scalar fields are fully queryable via the .Q proxy. ranges and intensities are not queryable.

Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.angle_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.angle_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.time_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.scan_time Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.range_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
LaserScan.Q.range_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
from mosaicolabs import MosaicoClient, QueryOntologyCatalog
from mosaicolabs.model.futures import LaserScan

with MosaicoClient.connect("localhost", 6726) as client:
    # Find long-range, wide-FOV scans
    qresponse = client.query(
        QueryOntologyCatalog(LaserScan.Q.range_max.gt(30.0))
            .with_expression(LaserScan.Q.angle_max.geq(3.14)),
    )

    if qresponse is not None:
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")

    # Same query, also extracting the first and last occurrence times
    qresponse = client.query(
        QueryOntologyCatalog(LaserScan.Q.range_max.gt(30.0), include_timestamp_range=True)
            .with_expression(LaserScan.Q.angle_max.geq(3.14)),
    )

    if qresponse is not None:
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {{topic.name: "
                  f"[topic.timestamp_range.start, topic.timestamp_range.end] "
                  f"for topic in item.topics}}")

angle_min class-attribute instance-attribute 

angle_min = MosaicoField(
    description="start angle of the scan in rad."
)

Start angle of the scan in radians.

Defines the angular position of the first beam in the sweep.Together with angle_max and angle_increment, it fully characterises the angular coverage of the scan.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_min.geq(-3.14))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

angle_max class-attribute instance-attribute 

angle_max = MosaicoField(
    description="end angle of the scan in rad."
)

End angle of the scan in radians.

Defines the angular position of the last beam in the sweep. The total field of view of the scanner is angle_max - angle_min.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_max.geq(3.14))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

angle_increment class-attribute instance-attribute 

angle_increment = MosaicoField(
    description="angular distance between measurements in rad."
)

Angular step between consecutive beams in radians.

The number of beams in a sweep can be derived as round((angle_max - angle_min) / angle_increment) + 1. A negative value indicates a clockwise scan direction.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find high-resolution scans (small angular step)
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_increment.lt(0.01))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

time_increment class-attribute instance-attribute 

time_increment = MosaicoField(
    description="time between measurements in seconds."
)

Time elapsed between consecutive beam measurements, in seconds.

If the scanner is moving, this will be used in interpoling position of 3D points.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.time_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.time_increment.lt(0.0001))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

scan_time class-attribute instance-attribute 

scan_time = MosaicoField(
    description="time between scans in seconds."
)

Time between scans in seconds.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.scan_time Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find sequences recorded at 10 Hz (scan_time ≈ 0.1 s)
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.scan_time.between([0.09, 0.11]))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

range_min class-attribute instance-attribute 

range_min = MosaicoField(
    description="minimum range value in meters."
)

Minimum valid range value, in meters.

Measurements strictly below this threshold are outside the sensor's reliable operating range and should be discarded or treated as invalid during downstream processing.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.range_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_min.leq(0.1))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

range_max class-attribute instance-attribute 

range_max = MosaicoField(
    description="maximum range value in meters."
)

Maximum valid range value, in meters.

Measurements strictly above this threshold exceed the sensor's maximum detection distance and should be discarded or treated as invalid during downstream processing.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.range_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find long-range scanner sessions
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_max.gt(30.0))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

ranges class-attribute instance-attribute 

ranges = MosaicoField(
    description="range data in meters. Ranges need to be between range min and max otherwise discarded."
)

Range measurements for each beam.

A flat list of float values, one per beam, representing the measured distance in meters.

Values outside the [range_min, range_max] interval should be considered invalid.

intensities class-attribute instance-attribute 

intensities = MosaicoField(
    default=None, description="intensity data."
)

Intensity measurements for each beam (optional).

A flat list of float values, carries the signal amplitude of each beam.

is_registered classmethod 

is_registered()

Checks if a class is registered.

Returns:

Name Type Description
bool bool

True if registered.

ontology_tag classmethod 

ontology_tag()

Retrieves the unique identifier (tag) for the current ontology class, automatically generated during class definition.

This method provides the string key used by the Mosaico platform to identify and route specific data types within the ontology registry. It abstracts away the internal naming conventions, ensuring that you always use the correct identifier for queries and serialization.

Returns:

Type Description
str

The registered string tag for this class (e.g., "imu", "gps").

Raises:

Type Description
Exception

If the class was not properly initialized via __pydantic_init_subclass__.
Practical Application: Topic Filtering

This method is particularly useful when constructing QueryTopic requests. By using the convenience method QueryTopic.with_ontology_tag(), you can filter topics by data type without hardcoding strings that might change.

Example: 

from mosaicolabs import MosaicoClient, Topic, IMU, QueryTopic

with MosaicoClient.connect("localhost", 6726) as client:
    # Filter for a specific data value (using constructor)
    qresponse = client.query(
        QueryTopic(
            Topic.with_ontology_tag(IMU.ontology_tag()),
        )
    )

    # Inspect the response
    if qresponse is not None:
        # Results are automatically grouped by Sequence for easier data management
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")

mosaicolabs.models.futures.MultiEchoLaserScan

Bases: _LaserScanBase, Serializable

Multi-echo 2D laser scan data.

This model represents one sweep of a multi-echo laser range finder. Multi-echo scanners record several range returns per beam, allowing the sensor to detect overlapping surfaces, semi-transparent objects such as vegetation or rain drops, and retroreflective targets simultaneously.

ranges and intensities are List[List[float]] arrays where the i-th inner list contains all echo returns for the beam at angular position angle_min + i * angle_increment, ordered from nearest to farthest. An empty inner list indicates no valid return for that beam.

Attributes:

Name Type Description
angle_min float32

Start angle of the scan in radians.
angle_max float32

End angle of the scan in radians.
angle_increment float32

Angular step between consecutive beams in radians.
time_increment float32

Time between consecutive beam measurements in seconds.
scan_time float32

Total duration of one full scan in seconds.
range_min float32

Minimum valid range threshold in meters.
range_max float32

Maximum valid range threshold in meters.
ranges MultiRange

List of echo distances per beam in meters; may contain multiple returns per beam.
intensities Optional[MultiRange]

List of echo amplitudes per beam, co-indexed with ranges (optional).
Note

List-typed fields are not queryable via the .Q proxy. The .Q proxy is not available on this model.

Querying with the .Q Proxy

Scalar fields are fully queryable via the .Q proxy. ranges and intensities are not queryable.

Field Access Path Queryable Type Supported Operators
MultiEchoLaserScan.Q.angle_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
MultiEchoLaserScan.Q.angle_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
MultiEchoLaserScan.Q.angle_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
MultiEchoLaserScan.Q.time_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
MultiEchoLaserScan.Q.scan_time Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
MultiEchoLaserScan.Q.range_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
MultiEchoLaserScan.Q.range_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import MultiEchoLaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find long-range, wide-FOV multi-echo scans
        qresponse = client.query(
            QueryOntologyCatalog(MultiEchoLaserScan.Q.range_max.gt(30.0))
                .with_expression(MultiEchoLaserScan.Q.angle_max.geq(3.14)),
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

        # Same query, also extracting the first and last occurrence times
        qresponse = client.query(
            QueryOntologyCatalog(MultiEchoLaserScan.Q.range_max.gt(30.0), include_timestamp_range=True)
                .with_expression(MultiEchoLaserScan.Q.angle_max.geq(3.14)),
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {{topic.name: "
                    f"[topic.timestamp_range.start, topic.timestamp_range.end] "
                    f"for topic in item.topics}}")

angle_min class-attribute instance-attribute 

angle_min = MosaicoField(
    description="start angle of the scan in rad."
)

Start angle of the scan in radians.

Defines the angular position of the first beam in the sweep.Together with angle_max and angle_increment, it fully characterises the angular coverage of the scan.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_min.geq(-3.14))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

angle_max class-attribute instance-attribute 

angle_max = MosaicoField(
    description="end angle of the scan in rad."
)

End angle of the scan in radians.

Defines the angular position of the last beam in the sweep. The total field of view of the scanner is angle_max - angle_min.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_max.geq(3.14))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

angle_increment class-attribute instance-attribute 

angle_increment = MosaicoField(
    description="angular distance between measurements in rad."
)

Angular step between consecutive beams in radians.

The number of beams in a sweep can be derived as round((angle_max - angle_min) / angle_increment) + 1. A negative value indicates a clockwise scan direction.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.angle_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find high-resolution scans (small angular step)
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.angle_increment.lt(0.01))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

time_increment class-attribute instance-attribute 

time_increment = MosaicoField(
    description="time between measurements in seconds."
)

Time elapsed between consecutive beam measurements, in seconds.

If the scanner is moving, this will be used in interpoling position of 3D points.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.time_increment Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.time_increment.lt(0.0001))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

scan_time class-attribute instance-attribute 

scan_time = MosaicoField(
    description="time between scans in seconds."
)

Time between scans in seconds.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.scan_time Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find sequences recorded at 10 Hz (scan_time ≈ 0.1 s)
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.scan_time.between([0.09, 0.11]))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

range_min class-attribute instance-attribute 

range_min = MosaicoField(
    description="minimum range value in meters."
)

Minimum valid range value, in meters.

Measurements strictly below this threshold are outside the sensor's reliable operating range and should be discarded or treated as invalid during downstream processing.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.range_min Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_min.leq(0.1))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

range_max class-attribute instance-attribute 

range_max = MosaicoField(
    description="maximum range value in meters."
)

Maximum valid range value, in meters.

Measurements strictly above this threshold exceed the sensor's maximum detection distance and should be discarded or treated as invalid during downstream processing.

Querying with the .Q Proxy
Field Access Path Queryable Type Supported Operators
LaserScan.Q.range_max Numeric .eq(), .neq(), .lt(), .gt(), .leq(), .geq(), .in_(), .between()
Example 
    from mosaicolabs import MosaicoClient, QueryOntologyCatalog
    from mosaicolabs.model.futures import LaserScan

    with MosaicoClient.connect("localhost", 6726) as client:
        # Find long-range scanner sessions
        qresponse = client.query(
            QueryOntologyCatalog(LaserScan.Q.range_max.gt(30.0))
        )

        if qresponse is not None:
            for item in qresponse:
                print(f"Sequence: {item.sequence.name}")
                print(f"Topics: {[topic.name for topic in item.topics]}")

ranges class-attribute instance-attribute 

ranges = MosaicoField(
    description="range data in meters. Ranges need to be between range min and max otherwise discarded."
)

Range measurements for each beam.

A list of lists, where the i-th inner list contains all echo distances returned by the i-th beam, ordered from nearest to farthest. An empty inner list indicates no valid return for that beam.

Values outside the [range_min, range_max] interval should be considered invalid.

intensities class-attribute instance-attribute 

intensities = MosaicoField(
    default=None, description="intensity data."
)

Intensity measurements for each beam. (optional).

A flat list of list of float value carries the signal amplitude of each returned echo.

is_registered classmethod 

is_registered()

Checks if a class is registered.

Returns:

Name Type Description
bool bool

True if registered.

ontology_tag classmethod 

ontology_tag()

Retrieves the unique identifier (tag) for the current ontology class, automatically generated during class definition.

This method provides the string key used by the Mosaico platform to identify and route specific data types within the ontology registry. It abstracts away the internal naming conventions, ensuring that you always use the correct identifier for queries and serialization.

Returns:

Type Description
str

The registered string tag for this class (e.g., "imu", "gps").

Raises:

Type Description
Exception

If the class was not properly initialized via __pydantic_init_subclass__.
Practical Application: Topic Filtering

This method is particularly useful when constructing QueryTopic requests. By using the convenience method QueryTopic.with_ontology_tag(), you can filter topics by data type without hardcoding strings that might change.

Example: 

from mosaicolabs import MosaicoClient, Topic, IMU, QueryTopic

with MosaicoClient.connect("localhost", 6726) as client:
    # Filter for a specific data value (using constructor)
    qresponse = client.query(
        QueryTopic(
            Topic.with_ontology_tag(IMU.ontology_tag()),
        )
    )

    # Inspect the response
    if qresponse is not None:
        # Results are automatically grouped by Sequence for easier data management
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")

mosaicolabs.models.futures.Radar

Bases: Serializable

Radar Ontology.

This model represents a set of detections acquired from a Radar sensor. Each detection corresponds to a target or a reflection point in the sensor's field of view, characterised by its position, optional velocity, and signal-quality metrics.

Each field is a flat list whose i-th element corresponds to the i-th detection in the scan.

Unlike a LiDAR, Radar detections are inherently sparse and carry additional electromagnetic attributes such as Radar Cross Section (RCS), Signal-to-Noise Ratio (SNR), and Doppler velocity, which are not available from purely optical sensors.

Attributes:

Name Type Description
x list_(float32)

X coordinates of each detection in meters.
y list_(float32)

Y coordinates of each detection in meters.
z list_(float32)

Z coordinates of each detection in meters.
range Optional[list_(float32)]

Radial distance from the sensor origin to each detection in meters (optional).
azimuth Optional[list_(float32)]

Azimuth angle in radians for each detection (optional).
elevation Optional[list_(float32)]

Elevation angle in radians for each detection (optional).
rcs Optional[list_(float32)]

Radar Cross Section of each detection in dBm (optional).
snr Optional[list_(float32)]

Signal-to-Noise Ratio of each detection in dB (optional).
doppler_velocity Optional[list_(float32)]

Doppler radial velocity of each detection in m/s (optional).
vx Optional[list_(float32)]

X component of the velocity of each detection in m/s (optional).
vy Optional[list_(float32)]

Y component of the velocity of each detection in m/s (optional).
vx_comp Optional[list_(float32)]

Ego-motion-compensated X velocity of each detection in m/s (optional).
vy_comp Optional[list_(float32)]

Ego-motion-compensated Y velocity of each detection in m/s (optional).
ax Optional[list_(float32)]

X component of the acceleration of each detection in m/s² (optional).
ay Optional[list_(float32)]

Y component of the acceleration of each detection in m/s² (optional).
radial_speed Optional[list_(float32)]

Radial speed of each detection in m/s (optional).
Note

MosaicoType.list_() typed fields are not queryable via the .Q proxy. The .Q proxy is not available on this model.

Example 
from mosaicolabs import MosaicoClient
from mosaicolabs.models.futures import Radar

with MosaicoClient.connect("localhost", 6726) as client:
    # Fetch all sequences that contain at least one Radar topic
    sequences = client.get_sequences(ontology=Radar)

    for sequence in sequences:
        print(f"Sequence: {sequence.name}")
        print(f"Topics:   {[topic.name for topic in sequence.topics]}")

x class-attribute instance-attribute 

x = MosaicoField(description='x coordinates in meters.')

X coordinates of each detection, in meters.

y class-attribute instance-attribute 

y = MosaicoField(description='y coordinates in meters.')

Y coordinates of each detection, in meters.

z class-attribute instance-attribute 

z = MosaicoField(description='z coordinates in meters.')

Z coordinates of each detection, in meters.

range class-attribute instance-attribute 

range = MosaicoField(
    default=None, description="radial distance in meters."
)

Radial distance from the sensor origin to each detection, in meters.

Represents the straight-line distance along the beam axis.

azimuth class-attribute instance-attribute 

azimuth = MosaicoField(
    default=None, description="azimuth angle in radians."
)

Horizontal (azimuth) angle of each detection in radians.

Measured in the sensor's horizontal plane, typically from 0 to 2π, with 0 aligned to the sensor's forward axis.

elevation class-attribute instance-attribute 

elevation = MosaicoField(
    default=None, description="elevation angle in radians."
)

Vertical (elevation) angle of each detection in radians.

Measured from the sensor's horizontal plane; positive values point upward.

rcs class-attribute instance-attribute 

rcs = MosaicoField(
    default=None, description="radar cross section in dBm."
)

Radar Cross Section (RCS) of each detection, in dBm.

Quantifies the effective scattering area of the target as seen by the sensor. Higher values typically correspond to larger or more reflective objects. Useful for target classification and false-positive filtering.

snr class-attribute instance-attribute 

snr = MosaicoField(
    default=None, description="signal to noise ratio in dB."
)

Signal-to-Noise Ratio (SNR) of each detection, in dB.

Indicates the quality of the received echo relative to background noise. Low-SNR detections are generally less reliable and may be filtered out during object-level processing.

doppler_velocity class-attribute instance-attribute 

doppler_velocity = MosaicoField(
    default=None, description="doppler velocity in m/s."
)

Doppler radial velocity of each detection, in m/s.

Represents the component of the target's velocity along the sensor's line of sight, derived directly from the frequency shift of the returned signal. Positive values conventionally indicate motion away from the sensor.

vx class-attribute instance-attribute 

vx = MosaicoField(
    default=None, description="x velocity in m/s."
)

X component of the estimated velocity of each detection, in m/s.

Expressed in the sensor frame. This is a Cartesian decomposition of the target velocity, as opposed to the purely radial doppler_velocity.

vy class-attribute instance-attribute 

vy = MosaicoField(
    default=None, description="y velocity in m/s."
)

Y component of the estimated velocity of each detection, in m/s.

Expressed in the sensor frame. See vx for further context.

vx_comp class-attribute instance-attribute 

vx_comp = MosaicoField(
    default=None,
    description="x compensated velocity in m/s.",
)

Ego-motion-compensated X velocity of each detection, in m/s.

Obtained by subtracting the host vehicle's own velocity from vx, yielding the detection's absolute velocity in the world frame along the X axis.

vy_comp class-attribute instance-attribute 

vy_comp = MosaicoField(
    default=None,
    description="y compensated velocity in m/s.",
)

Ego-motion-compensated Y velocity of each detection, in m/s.

Analogous to vx_comp along the Y axis. See vx_comp for further context.

ax class-attribute instance-attribute 

ax = MosaicoField(
    default=None, description="x acceleration in m/s^2."
)

X component of the estimated acceleration of each detection, in m/s².

Available only on sensors that track detections across multiple scans and report per-point kinematic state (e.g. high-level object-list outputs).

ay class-attribute instance-attribute 

ay = MosaicoField(
    default=None, description="y acceleration in m/s^2."
)

Y component of the estimated acceleration of each detection, in m/s².

Analogous to ax along the Y axis. See ax for further context.

radial_speed class-attribute instance-attribute 

radial_speed = MosaicoField(
    default=None, description="radial speed in m/s."
)

Radial speed of each detection, in m/s.

Represents the magnitude of the velocity component along the line of sight, without sign convention. Distinct from doppler_velocity, which may carry a directional sign depending on the sensor's convention.

is_registered classmethod 

is_registered()

Checks if a class is registered.

Returns:

Name Type Description
bool bool

True if registered.

ontology_tag classmethod 

ontology_tag()

Retrieves the unique identifier (tag) for the current ontology class, automatically generated during class definition.

This method provides the string key used by the Mosaico platform to identify and route specific data types within the ontology registry. It abstracts away the internal naming conventions, ensuring that you always use the correct identifier for queries and serialization.

Returns:

Type Description
str

The registered string tag for this class (e.g., "imu", "gps").

Raises:

Type Description
Exception

If the class was not properly initialized via __pydantic_init_subclass__.
Practical Application: Topic Filtering

This method is particularly useful when constructing QueryTopic requests. By using the convenience method QueryTopic.with_ontology_tag(), you can filter topics by data type without hardcoding strings that might change.

Example: 

from mosaicolabs import MosaicoClient, Topic, IMU, QueryTopic

with MosaicoClient.connect("localhost", 6726) as client:
    # Filter for a specific data value (using constructor)
    qresponse = client.query(
        QueryTopic(
            Topic.with_ontology_tag(IMU.ontology_tag()),
        )
    )

    # Inspect the response
    if qresponse is not None:
        # Results are automatically grouped by Sequence for easier data management
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")

mosaicolabs.models.futures.Lidar

Bases: Serializable

LiDAR Ontology.

This model represents a 3D point cloud acquired from a LiDAR sensor. Each field is a flat list whose i-th element corresponds to the i-th point in the scan. All lists within a single instance are therefore guaranteed to have the same length.

Attributes:

Name Type Description
x list_(float32)

X coordinates of each point in meters.
y list_(float32)

Y coordinates of each point in meters.
z list_(float32)

Z coordinates of each point in meters.
intensity Optional[list_(float32)]

Strength of the returned signal for each point (optional).
reflectivity Optional[list_(uint16)]

Surface reflectivity per point (optional).
beam_id Optional[list_(uint16)]

Laser beam index (ring / channel / line) that fired each point (optional).
range Optional[list_(float32)]

Distance from the sensor origin to each point in meters (optional).
near_ir Optional[list_(float32)]

Near-infrared ambient light reading per point, useful as a noise/ambient estimate (optional).
azimuth Optional[list_(float32)]

Azimuth angle in radians for each point (optional).
elevation Optional[list_(float32)]

Elevation angle in radians for each point (optional).
confidence Optional[list_(uint8)]

Per-point validity or confidence flags as a manufacturer-specific bitmask (optional).
return_type Optional[list_(uint8)]

Single/dual return classification, manufacturer-specific (optional).
point_timestamp Optional[list_(float64)]

Per-point acquisition time offset from the scan start, in seconds (optional).
Note

List-typed fields are not queryable via the .Q proxy. The .Q proxy is not available on this model.

Example 
from mosaicolabs import MosaicoClient
from mosaicolabs.models.futures import Lidar

with MosaicoClient.connect("localhost", 6726) as client:
    # Fetch all sequences that contain at least one LiDAR topic
    sequences = client.get_sequences(ontology=Lidar)

    for sequence in sequences:
        print(f"Sequence: {sequence.name}")
        print(f"Topics:   {[topic.name for topic in sequence.topics]}")

x class-attribute instance-attribute 

x = MosaicoField(description='x coordinates in meters')

X coordinates of each point in the cloud, in meters.

y class-attribute instance-attribute 

y = MosaicoField(description='y coordinates in meters')

Y coordinates of each point in the cloud, in meters.

z class-attribute instance-attribute 

z = MosaicoField(description='z coordinates in meters')

Z coordinates of each point in the cloud, in meters.

intensity class-attribute instance-attribute 

intensity = MosaicoField(
    default=None,
    description="Surface reflectivity per point.",
)

Strength of the returned laser signal for each point.

reflectivity class-attribute instance-attribute 

reflectivity = MosaicoField(
    default=None,
    description="Surface reflectivity per point.",
)

Surface reflectivity per point.

Encodes the estimated reflectance of the surface that produced each return, independently of the distance. Manufacturer-specific scaling applies.

beam_id class-attribute instance-attribute 

beam_id = MosaicoField(
    default=None,
    description="Laser beam index (ring / channel / line) that fired each point.",
)

Laser beam index (ring / channel / line) that fired each point.

Identifies which physical emitter in the sensor array produced the return. Equivalent to the ring field commonly found in ROS PointCloud2 messages from multi-beam sensors such as Velodyne or Ouster.

range class-attribute instance-attribute 

range = MosaicoField(
    default=None,
    description="Distance from the sensor origin to each point, in meters.",
)

Distance from the sensor origin to each point, in meters.

Represents the raw radial distance along the beam axis, before projection onto Cartesian coordinates. Not always provided by all sensor drivers.

near_ir class-attribute instance-attribute 

near_ir = MosaicoField(
    default=None,
    description="Near-infrared ambient light reading per point.",
)

Near-infrared ambient light reading per point.

Captured passively by the sensor between laser pulses. Useful as a proxy for ambient illumination or for filtering sun-noise artefacts. Exposed as the ambient channel in Ouster drivers.

azimuth class-attribute instance-attribute 

azimuth = MosaicoField(
    default=None,
    description="Horizontal (azimuth) angle of each point in radians.",
)

Horizontal (azimuth) angle of each point in radians.

elevation class-attribute instance-attribute 

elevation = MosaicoField(
    default=None,
    description="Vertical (elevation) angle of each point in radians.",
)

Vertical (elevation) angle of each point in radians.

confidence class-attribute instance-attribute 

confidence = MosaicoField(
    default=None,
    description="Per-point validity or confidence flags.",
)

Per-point validity or confidence flags.

Stored as a manufacturer-specific bitmask (equivalent to the tag or flags fields in Ouster point clouds). Individual bits may signal saturated returns, calibration issues, or other quality indicators.

return_type class-attribute instance-attribute 

return_type = MosaicoField(
    default=None,
    description="Single/dual return classification per point.",
)

Single/dual return classification per point.

Indicates whether a point originates from the first return, last return, strongest return, etc. Encoding is manufacturer-specific.

point_timestamp class-attribute instance-attribute 

point_timestamp = MosaicoField(
    default=None,
    description="Per-point acquisition time offset from the scan start, in seconds.",
)

Per-point acquisition time offset from the scan start, in seconds.

Allows precise temporal localisation of individual points within a single sweep, which is important for motion-distortion correction during point-cloud registration.

is_registered classmethod 

is_registered()

Checks if a class is registered.

Returns:

Name Type Description
bool bool

True if registered.

ontology_tag classmethod 

ontology_tag()

Retrieves the unique identifier (tag) for the current ontology class, automatically generated during class definition.

This method provides the string key used by the Mosaico platform to identify and route specific data types within the ontology registry. It abstracts away the internal naming conventions, ensuring that you always use the correct identifier for queries and serialization.

Returns:

Type Description
str

The registered string tag for this class (e.g., "imu", "gps").

Raises:

Type Description
Exception

If the class was not properly initialized via __pydantic_init_subclass__.
Practical Application: Topic Filtering

This method is particularly useful when constructing QueryTopic requests. By using the convenience method QueryTopic.with_ontology_tag(), you can filter topics by data type without hardcoding strings that might change.

Example: 

from mosaicolabs import MosaicoClient, Topic, IMU, QueryTopic

with MosaicoClient.connect("localhost", 6726) as client:
    # Filter for a specific data value (using constructor)
    qresponse = client.query(
        QueryTopic(
            Topic.with_ontology_tag(IMU.ontology_tag()),
        )
    )

    # Inspect the response
    if qresponse is not None:
        # Results are automatically grouped by Sequence for easier data management
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")

mosaicolabs.models.futures.depth_camera._DepthCameraBase

Bases: BaseModel

Internal base model shared by all depth camera ontologies.

Defines the spatial core and common optional channels that every depth camera variant exposes, regardless of the underlying acquisition technology.

This class is not intended to be instantiated directly. Use one of the concrete subclasses: RGBDCamera, ToFCamera, or StereoCamera.

Attributes:

Name Type Description
x list_(float32)

Horizontal positions of each point, derived from depth, in meters.
y list_(float32)

Vertical positions of each point, derived from depth, in meters.
z list_(float32)

Depth values (distance along the optical axis) of each point, in meters.
rgb Optional[list_(float32)]

Packed RGB colour value per point (optional).
intensity Optional[list_(float32)]

Signal amplitude or intensity per point (optional).

x class-attribute instance-attribute 

x = MosaicoField(
    description="Horizontal position derived from depth."
)

Horizontal position of each point derived from the depth map, in meters.

y class-attribute instance-attribute 

y = MosaicoField(
    description="Vertical position derived from depth."
)

Vertical position of each point derived from the depth map, in meters.

z class-attribute instance-attribute 

z = MosaicoField(
    description="Depth value directly (distance along optical axis)."
)

Depth value of each point, in meters.

Represents the distance along the camera's optical axis (Z-forward convention). This is the primary measurement from which x and y are projected using the sensor's intrinsic parameters.

rgb class-attribute instance-attribute 

rgb = MosaicoField(
    default=None, description="Packed RGB color value."
)

Packed RGB colour value per point.

Each element encodes the red, green, and blue channels of the pixel co-registered with the corresponding depth sample. The packing convention rgb field (bits 16–23 = R, 8–15 = G, 0–7 = B, stored as a float32 reinterpretation of a uint32). There are useful utilities for pack_rgb() and unpack_rgb() rgb in in the internal of depth camera.

intensity class-attribute instance-attribute 

intensity = MosaicoField(
    default=None, description="Signal amplitude/intensity."
)

Signal amplitude or intensity per point.

mosaicolabs.models.futures.depth_camera.pack_rgb 

pack_rgb(r, g, b)

Packs three RGB channels (8-bit each) into a single float32 value.

This utility combines Red, Green, and Blue components into a 32-bit integer and then bit-casts the result into a float. This is a standard technique used in point cloud processing to store color data efficiently within a single field.

Parameters:

Name Type Description Default
r int

Red intensity (0-255).

 required
g int

Green intensity (0-255).

 required
b int

Blue intensity (0-255).

 required

Returns:

Type Description
float

The RGB color encoded as a 32-bit float.

mosaicolabs.models.futures.depth_camera.unpack_rgb 

unpack_rgb(packed_rgb)

Unpacks a float32 value back into its original RGB components.

This is the inverse operation of pack_rgb(). It reinterprets the float's bits as an unsigned 32-bit integer and extracts the individual color bytes.

Parameters:

Name Type Description Default
packed_rgb float

The encoded float value containing RGB data.

 required

Returns:

Type Description
Tuple[int, int, int]

A tuple of (red, green, blue), where each value is between 0 and 255.

mosaicolabs.models.futures.RGBDCamera

Bases: _DepthCameraBase, Serializable

RGB-D camera ontology.

This model represents a registered depth-and-colour point cloud produced by an RGB-D sensor (e.g. Intel RealSense D-series, Microsoft Azure Kinect). Each point carries a 3D position in the camera frame together with an optional packed RGB colour value and an optional intensity channel.

RGB-D sensors typically fuse a structured-light or active-infrared depth map with a co-located colour camera, yielding a dense, pixel-aligned point cloud at video frame rates.

Each field is a flat list whose i-th element corresponds to the i-th point in the frame. All lists within a single instance are therefore guaranteed to have the same length.

Attributes:

Name Type Description
x list_(float32)

Horizontal positions of each point, derived from depth, in meters.
y list_(float32)

Vertical positions of each point, derived from depth, in meters.
z list_(float32)

Depth values (distance along the optical axis) of each point, in meters.
rgb Optional[list_(float32)]

Packed RGB colour value per point (optional).
intensity Optional[list_(float32)]

Signal amplitude or intensity per point (optional).
Note

List-typed fields are not queryable via the .Q proxy. The .Q proxy is not available on this model.

Example: 

        from mosaicolabs import MosaicoClient
        from mosaicolabs.models.futures import RGBDCamera

        with MosaicoClient.connect("localhost", 6726) as client:
            # Fetch all sequences that contain at least one RGB-D camera topic
            sequences = client.get_sequences(ontology=RGBDCamera)

            for sequence in sequences:
                print(f"Sequence: {sequence.name}")
                print(f"Topics:   {[topic.name for topic in sequence.topics]}")

x class-attribute instance-attribute 

x = MosaicoField(
    description="Horizontal position derived from depth."
)

Horizontal position of each point derived from the depth map, in meters.

y class-attribute instance-attribute 

y = MosaicoField(
    description="Vertical position derived from depth."
)

Vertical position of each point derived from the depth map, in meters.

z class-attribute instance-attribute 

z = MosaicoField(
    description="Depth value directly (distance along optical axis)."
)

Depth value of each point, in meters.

Represents the distance along the camera's optical axis (Z-forward convention). This is the primary measurement from which x and y are projected using the sensor's intrinsic parameters.

rgb class-attribute instance-attribute 

rgb = MosaicoField(
    default=None, description="Packed RGB color value."
)

Packed RGB colour value per point.

Each element encodes the red, green, and blue channels of the pixel co-registered with the corresponding depth sample. The packing convention rgb field (bits 16–23 = R, 8–15 = G, 0–7 = B, stored as a float32 reinterpretation of a uint32). There are useful utilities for pack_rgb() and unpack_rgb() rgb in in the internal of depth camera.

intensity class-attribute instance-attribute 

intensity = MosaicoField(
    default=None, description="Signal amplitude/intensity."
)

Signal amplitude or intensity per point.

is_registered classmethod 

is_registered()

Checks if a class is registered.

Returns:

Name Type Description
bool bool

True if registered.

ontology_tag classmethod 

ontology_tag()

Retrieves the unique identifier (tag) for the current ontology class, automatically generated during class definition.

This method provides the string key used by the Mosaico platform to identify and route specific data types within the ontology registry. It abstracts away the internal naming conventions, ensuring that you always use the correct identifier for queries and serialization.

Returns:

Type Description
str

The registered string tag for this class (e.g., "imu", "gps").

Raises:

Type Description
Exception

If the class was not properly initialized via __pydantic_init_subclass__.
Practical Application: Topic Filtering

This method is particularly useful when constructing QueryTopic requests. By using the convenience method QueryTopic.with_ontology_tag(), you can filter topics by data type without hardcoding strings that might change.

Example: 

from mosaicolabs import MosaicoClient, Topic, IMU, QueryTopic

with MosaicoClient.connect("localhost", 6726) as client:
    # Filter for a specific data value (using constructor)
    qresponse = client.query(
        QueryTopic(
            Topic.with_ontology_tag(IMU.ontology_tag()),
        )
    )

    # Inspect the response
    if qresponse is not None:
        # Results are automatically grouped by Sequence for easier data management
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")

mosaicolabs.models.futures.StereoCamera

Bases: _DepthCameraBase, Serializable

Stereo camera ontology.

This model represents a dense point cloud produced by a passive stereo camera system (e.g. Stereolabs ZED, Luxonis OAK-D, Carnegie Robotics MultiSense). Depth is estimated by computing the horizontal disparity between a rectified left/right image pair and projecting it into 3D space using the known baseline and intrinsic parameters.

In addition to the common spatial and colour channels inherited from _DepthCamera, this model exposes two stereo-specific fields: luma, which carries the luminance of the source rectified image pixel, and cost, which encodes the confidence of the disparity estimate at each point.

Each field is a flat list whose i-th element corresponds to the i-th pixel in the disparity map (in row-major order). All lists within a single instance are therefore guaranteed to have the same length.

Attributes:

Name Type Description
x list_(float32)

Horizontal positions of each point in meters.
y list_(float32)

Vertical positions of each point in meters.
z list_(float32)

Depth values (distance along the optical axis) of each point, in meters.
rgb Optional[list_(float32)]

Packed RGB colour value per point (optional).
intensity Optional[list_(float32)]

Signal amplitude or intensity per point (optional).
luma Optional[list_(uint8)]

Luminance of the corresponding pixel in the rectified image (optional).
cost Optional[list_(uint8)]

Stereo matching cost per point; lower values indicate higher disparity confidence (optional).
Note

List-typed fields are not queryable via the .Q proxy. The .Q proxy is not available on this model.

Example: 

        from mosaicolabs import MosaicoClient
        from mosaicolabs.models.futures import StereoCamera

        with MosaicoClient.connect("localhost", 6726) as client:
            # Fetch all sequences that contain at least one stereo camera topic
            sequences = client.get_sequences(ontology=StereoCamera)

            for sequence in sequences:
                print(f"Sequence: {sequence.name}")
                print(f"Topics:   {[topic.name for topic in sequence.topics]}")

x class-attribute instance-attribute 

x = MosaicoField(
    description="Horizontal position derived from depth."
)

Horizontal position of each point derived from the depth map, in meters.

y class-attribute instance-attribute 

y = MosaicoField(
    description="Vertical position derived from depth."
)

Vertical position of each point derived from the depth map, in meters.

z class-attribute instance-attribute 

z = MosaicoField(
    description="Depth value directly (distance along optical axis)."
)

Depth value of each point, in meters.

Represents the distance along the camera's optical axis (Z-forward convention). This is the primary measurement from which x and y are projected using the sensor's intrinsic parameters.

rgb class-attribute instance-attribute 

rgb = MosaicoField(
    default=None, description="Packed RGB color value."
)

Packed RGB colour value per point.

Each element encodes the red, green, and blue channels of the pixel co-registered with the corresponding depth sample. The packing convention rgb field (bits 16–23 = R, 8–15 = G, 0–7 = B, stored as a float32 reinterpretation of a uint32). There are useful utilities for pack_rgb() and unpack_rgb() rgb in in the internal of depth camera.

intensity class-attribute instance-attribute 

intensity = MosaicoField(
    default=None, description="Signal amplitude/intensity."
)

Signal amplitude or intensity per point.

luma class-attribute instance-attribute 

luma = MosaicoField(
    default=None,
    description="Luminance of the corresponding pixel in the rectified image.",
)

Luminance of the corresponding pixel in the rectified image.

cost class-attribute instance-attribute 

cost = MosaicoField(
    default=None,
    description="Stereo matching cost (disparity confidence measure, 0 = high confidence).",
)

Stereo matching cost per point; lower values indicate higher disparity confidence.

is_registered classmethod 

is_registered()

Checks if a class is registered.

Returns:

Name Type Description
bool bool

True if registered.

ontology_tag classmethod 

ontology_tag()

Retrieves the unique identifier (tag) for the current ontology class, automatically generated during class definition.

This method provides the string key used by the Mosaico platform to identify and route specific data types within the ontology registry. It abstracts away the internal naming conventions, ensuring that you always use the correct identifier for queries and serialization.

Returns:

Type Description
str

The registered string tag for this class (e.g., "imu", "gps").

Raises:

Type Description
Exception

If the class was not properly initialized via __pydantic_init_subclass__.
Practical Application: Topic Filtering

This method is particularly useful when constructing QueryTopic requests. By using the convenience method QueryTopic.with_ontology_tag(), you can filter topics by data type without hardcoding strings that might change.

Example: 

from mosaicolabs import MosaicoClient, Topic, IMU, QueryTopic

with MosaicoClient.connect("localhost", 6726) as client:
    # Filter for a specific data value (using constructor)
    qresponse = client.query(
        QueryTopic(
            Topic.with_ontology_tag(IMU.ontology_tag()),
        )
    )

    # Inspect the response
    if qresponse is not None:
        # Results are automatically grouped by Sequence for easier data management
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")

mosaicolabs.models.futures.ToFCamera

Bases: _DepthCameraBase, Serializable

Time-of-Flight (ToF) camera ontology.

This model represents a point cloud produced by a Time-of-Flight sensor (e.g. PMD Flexx2, ifm O3R, Sony DepthSense). ToF sensors measure depth by emitting amplitude-modulated infrared light and computing the phase shift of the returning signal, yielding per-pixel depth, amplitude, and noise estimates in a single acquisition.

In addition to the common spatial and colour channels inherited from _DepthCamera, this model exposes two ToF-specific fields: noise, which quantifies the per-pixel measurement uncertainty, and grayscale, which carries the passive greyscale amplitude captured alongside the active depth measurement.

Each field is a flat list whose i-th element corresponds to the i-th pixel in the depth frame (in row-major order). All lists within a single instance are therefore guaranteed to have the same length.

Attributes:

Name Type Description
x list_(float32)

Horizontal positions of each point, derived from depth, in meters.
y list_(float32)

Vertical positions of each point, derived from depth, in meters.
z list_(float32)

Depth values (distance along the optical axis) of each point, in meters.
rgb Optional[list_(float32)]

Packed RGB colour value per point (optional).
intensity Optional[list_(float32)]

Signal amplitude or intensity per point (optional).
noise Optional[list_(float32)]

Per-pixel noise estimate of the depth measurement (optional).
grayscale Optional[list_(float32)]

Passive greyscale amplitude per pixel (optional).
Note

List-typed fields are not queryable via the .Q proxy. The .Q proxy is not available on this model.

Example 
    from mosaicolabs import MosaicoClient
    from mosaicolabs.models.futures import ToFCamera

    with MosaicoClient.connect("localhost", 6726) as client:
        # Fetch all sequences that contain at least one ToF camera topic
        sequences = client.get_sequences(ontology=ToFCamera)

        for sequence in sequences:
            print(f"Sequence: {sequence.name}")
            print(f"Topics:   {[topic.name for topic in sequence.topics]}")

x class-attribute instance-attribute 

x = MosaicoField(
    description="Horizontal position derived from depth."
)

Horizontal position of each point derived from the depth map, in meters.

y class-attribute instance-attribute 

y = MosaicoField(
    description="Vertical position derived from depth."
)

Vertical position of each point derived from the depth map, in meters.

z class-attribute instance-attribute 

z = MosaicoField(
    description="Depth value directly (distance along optical axis)."
)

Depth value of each point, in meters.

Represents the distance along the camera's optical axis (Z-forward convention). This is the primary measurement from which x and y are projected using the sensor's intrinsic parameters.

rgb class-attribute instance-attribute 

rgb = MosaicoField(
    default=None, description="Packed RGB color value."
)

Packed RGB colour value per point.

Each element encodes the red, green, and blue channels of the pixel co-registered with the corresponding depth sample. The packing convention rgb field (bits 16–23 = R, 8–15 = G, 0–7 = B, stored as a float32 reinterpretation of a uint32). There are useful utilities for pack_rgb() and unpack_rgb() rgb in in the internal of depth camera.

intensity class-attribute instance-attribute 

intensity = MosaicoField(
    default=None, description="Signal amplitude/intensity."
)

Signal amplitude or intensity per point.

noise class-attribute instance-attribute 

noise = MosaicoField(
    default=None, description="Noise value per pixel."
)

Per-pixel noise estimate of the depth measurement.

High noise values typically indicate low-confidence depth samples caused by low signal return, multi-path interference, or motion blur, and should be treated with caution during downstream processing.

grayscale class-attribute instance-attribute 

grayscale = MosaicoField(
    default=None, description="Grayscale amplitude."
)

Passive greyscale amplitude per pixel.

Captured by the sensor's infrared photodiodes independently of the active modulation cycle. Provides a texture channel that can be used for feature extraction or visual odometry without requiring a separate colour camera.

is_registered classmethod 

is_registered()

Checks if a class is registered.

Returns:

Name Type Description
bool bool

True if registered.

ontology_tag classmethod 

ontology_tag()

Retrieves the unique identifier (tag) for the current ontology class, automatically generated during class definition.

This method provides the string key used by the Mosaico platform to identify and route specific data types within the ontology registry. It abstracts away the internal naming conventions, ensuring that you always use the correct identifier for queries and serialization.

Returns:

Type Description
str

The registered string tag for this class (e.g., "imu", "gps").

Raises:

Type Description
Exception

If the class was not properly initialized via __pydantic_init_subclass__.
Practical Application: Topic Filtering

This method is particularly useful when constructing QueryTopic requests. By using the convenience method QueryTopic.with_ontology_tag(), you can filter topics by data type without hardcoding strings that might change.

Example: 

from mosaicolabs import MosaicoClient, Topic, IMU, QueryTopic

with MosaicoClient.connect("localhost", 6726) as client:
    # Filter for a specific data value (using constructor)
    qresponse = client.query(
        QueryTopic(
            Topic.with_ontology_tag(IMU.ontology_tag()),
        )
    )

    # Inspect the response
    if qresponse is not None:
        # Results are automatically grouped by Sequence for easier data management
        for item in qresponse:
            print(f"Sequence: {item.sequence.name}")
            print(f"Topics: {[topic.name for topic in item.topics]}")