Module ouster.sdk.core

ouster.sdk.core.clipped_scan_source

class ClippedScanSource(scan_source, fields, lower, upper)[source]

Bases: ScanSource

limits the values of the specified set of fields to within the range = [lower, upper], any value that exceeds this range is replaced by zero.

property sensor_info: List[SensorInfo]

Retrieve sensor information for all sensors in the scan source.

Returns:

A list of SensorInfo objects, each containing metadata about a sensor, such as serial number, firmware version, and calibration details.

property is_live: bool

Check if the scan source is live.

A live scan source indicates that it is actively receiving data from a sensor.

Returns:

True if the scan source is live, False otherwise.

Return type:

bool

property is_indexed: bool
property scans_num: List[int]
close()[source]
Return type:

None

ouster.sdk.core

Functions

collate()

Collate scans from a scan source.

This function creates a Collator object that combines scans from a scan source.

Parameters:

  • source (ScanSource) – The scan source to collate.

  • dt (int) – The time delta in nanoseconds for collating scans. Default is 210000000.

Returns:

A collator object for the given scan source.

Return type:

Collator

io_type()

Determine the input/output type for a given URI.

io_type_from_extension()

Determine the input/output type based on a file extension.

extension_from_io_type()

Get the file extension for a given input/output type.

euler_pose_to_matrix()

Convert a pose given in Euler angles and translation to a 4x4 transformation matrix.

The pose vector should contain the following elements in order:

[roll, pitch, yaw, x, y, z]

where roll, pitch, and yaw are in radians.

Returns:

A 4x4 homogeneous transformation matrix.

quaternion_pose_to_matrix()

Convert a pose given as a quaternion and translation to a 4x4 transformation matrix.

The pose vector should contain the following elements in order:

[qw, qx, qy, qz, x, y, z]

Returns:

A 4x4 homogeneous transformation matrix.

interp_pose()

Interpolates 4x4 pose matrices at given x-coordinate values.

Parameters:

  • x_interp – NumPy array of shape (N, 1) or (N,) with inquiry x-coordinate values.

  • x_known – NumPy array of shape (M, 1) or (M,) with known x-coordinate values.

  • poses_known – NumPy array of shape (M, 4, 4) with known 4x4 pose matrices.

Returns:

NumPy array of shape (N, 4, 4) containing interpolated pose matrices.

voxel_downsample()

[BETA] Downsample a pointcloud using a voxel grid of the requested resolution.

Parameters:

  • voxel_size – The size of the voxel grid.

  • pts – Nx3 matrix of points to downsample.

  • attributes – A dictionary of attributes to downsample.

  • min_points_per_voxel – Minimum number of points per voxel to keep.

Returns:

A tuple containing the downsampled points and attributes.

Note

This is a beta feature and its API may change in future releases.

read_pointcloud()

[BETA] Loads the 3D X Y and Z points from a PCD or PLY file and returns them as Nx3 matrix.

Parameters:

filename – filename to load

Returns:

Nx3 matrix of the resulting points.

Note

This is a beta feature and its API may change in future releases.

dewarp()

Applies a set of 4x4 pose transformations to a collection of 3D points. :param points: A NumPy array of shape (H, W, 3) representing the 3D points. :param poses: A NumPy array of shape (W, 4, 4) representing the 4x4 pose

Returns:

A NumPy array of shape (H, W, 3) containing the dewarped 3D points

transform()

Applies a single of 4x4 pose transformations to a collection of 3D points. :param points: A NumPy array of shape (H, W, 3), or (N, 3) :param pose: A NumPy array of shape (4, 4) representing the 4x4 pose

Returns:

A NumPy array of shape (H, W, 3) or (N, 3) containing the transformed 3D points after applying the corresponding 4x4 transformation matrices to the points

Classes

class PacketSource

Bases: pybind11_object

PacketSource is a base class for reading packet data from various sources.

sensor_info

Metadata about the sensors providing the packets.

Type:

List[SensorInfo]

is_live

Indicates whether the packet source is live (actively receiving data).

Type:

bool

close()

Closes the packet source and releases any associated resources.

__iter__()

Returns an iterator over the packets in the source.

property is_live

Check if the packet source is live.

property sensor_info

Retrieve sensor information for all sensors in the packet source.

Returns:

A list of SensorInfo objects, each containing metadata about a sensor, such as serial number, firmware version, and calibration details.

class SensorInfo

Sensor Info required to interpret UDP data streams.

See the sensor documentation for the meaning of each property.

Construct an empty metadata.

Parameters:

s (str) – json string to parse

property beam_altitude_angles

Beam altitude angles, useful for XYZ projection.

property beam_azimuth_angles

Beam azimuth angles, useful for XYZ projection.

property beam_to_lidar_transform

Homogenous transformation matrix reprsenting Beam to Lidar Transform

property build_date

Build date

property cal

sensor calibration

property config

sensor config

property extrinsic

Extrinsic Matrix.

property format

Describes the structure of a lidar packet. See class DataFormat.

static from_default()

Create gen-1 OS-1-64 SensorInfo populated with design values.

property fw_rev

Sensor firmware revision.

get_product_info()

Get parsed product info

get_version()

Get parsed sensor version

property h

returns the height of a frame (equivalent to format.pixels_per_column)

has_fields_equal()

Compare public fields”

property image_rev

Image rev

property imu_to_sensor_transform

Homogenous transformation matrix representing IMU offset to Sensor Coordinate Frame.

property init_id

Initialization id.

property lidar_origin_to_beam_origin_mm

Distance between lidar origin and beam origin in millimeters.

property lidar_to_sensor_transform

Homogeneous transformation matrix from Lidar Coordinate Frame to Sensor Coordinate Frame.

property prod_line

Product line, e.g., ‘OS-1-128’.

property prod_pn

Prod pn

property sn

Sensor serial number.

property status

sensor status

to_json_string()

Return metadata string made from current entries”

property user_data

sensor user data

property w

returns the width of a frame (equivalent to format.columns_per_frame)

class ScanSource

Bases: pybind11_object

ScanSource is a base class for reading point cloud data from various sources.

__iter__()
clip(fields, lower, upper)

limits the values of the specified set of fields to within the range = [lower, upper], any value that exceeds this range is replaced by zero.

close()
property full_index
property individual_index
property is_indexed
property is_live

Check if the scan source is live.

A live scan source indicates that it is actively receiving data from a sensor.

Returns:

True if the scan source is live, False otherwise.

Return type:

bool

mask(fields, masks)
property metadata
reduce(beams)

Takes a regular ScanSource and reduces the beams count to the specified values.

Return type:

ScanSource

property scans_num
property sensor_info

Retrieve sensor information for all sensors in the scan source.

Returns:

A list of SensorInfo objects, each containing metadata about a sensor, such as serial number, firmware version, and calibration details.

property sensors_count
single()
single_iter()
slice()

Deprecation warnings:

  • ScanSource.sensors_count is deprecated. To get the number of sensors get the length of sensor_info.

  • ScanSource.metadata is deprecated. To get the sensor_info for each sensor use sensor_info instead.

    sensors_count() and metadata will be removed in future releases.

class LidarScan

Bases: pybind11_object

Represents a single “scan” or “frame” of lidar data.

This is a “struct of arrays” representation of lidar data. Column headers are stored as contiguous W element arrays, while fields are WxH arrays. Channel fields are staggered, so the ith column header value corresponds to the ith column of data in each field.

Default constructor creates a 0 x 0 scan

Parameters:

  • height – height of scan

  • width – width of scan

Returns:

New LidarScan of 0x0 expecting fields of the LEGACY profile

Initialize a scan with the default fields for a particular udp profile

Parameters:

  • height – height of LidarScan, i.e., number of channels

  • width – width of LidarScan

  • profile – udp profile

Returns:

New LidarScan of specified dimensions expecting fields of specified profile

Initialize a scan with a custom set of fields

Parameters:

  • height – height of LidarScan, i.e., number of channels

  • width – width of LidarScan

  • field_types – list of FieldType that specifies which fields should be present in the scan

Returns:

New LidarScan of specified dimensions expecting fields specified by dict

Initialize a scan with defaults fields and size for a given sensor_info

Parameters:

sensor_info – SensorInfo to construct a scan for

Returns:

New LidarScan approprate for the sensor_info

Initialize a scan with defaults fields and size for a given sensor_info

Parameters:

sensor_info – SensorInfo to construct a scan for

Returns:

New LidarScan approprate for the sensor_info

Initialize a scan with defaults fields and size for a given sensor_info with only the specified fields

Parameters:

  • sensor_info – SensorInfo to construct a scan for

  • field_types – list of fields to have in the new scan where keys are ChanFields and values are type, e.g., FieldType(client.ChanField.SIGNAL, np.uint32)

Returns:

New LidarScan approprate for the sensor_info

Initialize a lidar scan from another with only the indicated fields. Casts, zero pads or removes fields from the original scan if necessary.

Parameters:

  • source – LidarScan to copy data from

  • field_types – list of fields to have in the new scan where keys are ChanFields and values are type, e.g., FieldType(client.ChanField.SIGNAL, np.uint32)

Returns:

New LidarScan with selected data copied over or zero padded

Initialize a lidar scan with a copy of the data from another.

Parameters:

source – LidarScan to copy

Returns:

New LidarScan with data copied over from provided scan.

add_field()

Adds a new field under specified name

Parameters:

  • name – name of the field to add

  • shape – tuple of ints, shape of the field to add

  • dtype – dtype of field to add, e.g. np.uint32

  • field_class – class of the field to add, see field_class

Returns:

The field as a numpy array

Adds a new field under specified name and type

Parameters:

type – FieldType of the field to add

Returns:

The field as a numpy array

Adds a new field under the specified name, with the given contents. IMPORTANT: this will deep copy the supplied data.

Parameters:

  • name – the name of the new field

  • data – the contents of the new field

  • field_class – class of the field to add, see field_class

Returns:

The field as a numpy array.

property alert_flags

The alert flags header as a numpy array with W/columns-per-packet entries.

complete()
del_field()

Release a field from the LidarScan and return it to the user

Parameters:

name – name of the field to drop

Returns:

The specified field as a numpy array

field()

Return a view of the specified channel field.

Parameters:

name – name of the field to return

Returns:

The specified field as a numpy array

field_class()

Retrieve FieldClass of field

Parameters:

name – name of the field

Returns:

FieldClass of the field

property field_types

Return an list of available fields.

property fields

Return an list of available fields.

property frame_id

Corresponds to the frame id header in the packet format.

property frame_status

Information from the packet header which corresponds to a frame.

get_first_valid_column()

Return first valid column index in the scan.

get_first_valid_column_timestamp()

Return first valid column timestamp in the scan.

get_first_valid_packet_timestamp()

Return first valid packet timestamp in the scan.

get_last_valid_column()

Return last valid column index in the scan.

get_last_valid_column_timestamp()

Return last valid column timestamp in the scan.

get_last_valid_packet_timestamp()

Return last valid packet timestamp in the scan.

property h

Height or vertical resolution of the scan.

has_field()

Returns true if the LidarScan has a field with the given name

Parameters:

name – name of the field to check for

Returns:

True if the field exists in the scan, false otherwise

Check if a field with a given name exists in the LidarScan.

Parameters:

name – name of the field

Returns:

True if the field is present in the LidarScan.

property measurement_id

The measurement id header as a W-element numpy array.

property packet_count

The number of packets used to produce a full scan given the width in pixels and the number of columns per packet.

property packet_timestamp

The host timestamp header as a numpy array with W/columns-per-packet entries.

property pose

The pose vector of 4x4 homogeneous matrices (per each timestamp).

property sensor_info

The SensorInfo associated with this LidarScan.

shot_limiting()

The frame shot limiting status.

property shot_limiting_countdown

Shot-limiting countdown. Please refer to the firmware documentation for more information.

property shutdown_countdown

Thermal shutdown countdown. Please refer to the firmware documentation for more information.

property status

The measurement status header as a W-element numpy array.

thermal_shutdown()

The frame thermal shutdown status.

property timestamp

The measurement timestamp header as a W-element numpy array.

property w

Width or horizontal resolution of the scan.

class ImuPacket
class LidarPacket
class UDPProfileLidar

UDP lidar profile.

Members:

PROFILE_LIDAR_UNKNOWN

PROFILE_LIDAR_LEGACY

PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16_DUAL

PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16

PROFILE_LIDAR_RNG15_RFL8_NIR8

PROFILE_LIDAR_FIVE_WORD_PIXEL

PROFILE_LIDAR_FUSA_RNG15_RFL8_NIR8_DUAL

PROFILE_LIDAR_FIVE_WORD_PIXEL = <UDPProfileLidar.PROFILE_LIDAR_FIVE_WORD_PIXEL: 5>
PROFILE_LIDAR_FUSA_RNG15_RFL8_NIR8_DUAL = <UDPProfileLidar.PROFILE_LIDAR_FUSA_RNG15_RFL8_NIR8_DUAL: 6>
PROFILE_LIDAR_LEGACY = <UDPProfileLidar.PROFILE_LIDAR_LEGACY: 1>
PROFILE_LIDAR_RNG15_RFL8_NIR8 = <UDPProfileLidar.PROFILE_LIDAR_RNG15_RFL8_NIR8: 4>
PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16 = <UDPProfileLidar.PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16: 3>
PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16_DUAL = <UDPProfileLidar.PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16_DUAL: 2>
PROFILE_LIDAR_UNKNOWN = <UDPProfileLidar.PROFILE_LIDAR_UNKNOWN: 0>
from_string()

Create UDPProfileLidar from string.

property name

The name of the Enum member.

property value

The value of the Enum member.

values = <iterator object>

ouster.sdk.core.core

Ouster sensor Python client.

Copyright (c) 2021, Ouster, Inc. All rights reserved.

This module contains more idiomatic wrappers around the lower-level module generated using pybind11.

class Packets(it, metadata)[source]

Bases: PacketSource

Create a PacketSource from an existing iterator.

Parameters:
property sensor_info: List[SensorInfo]

Retrieve sensor information for all sensors in the packet source.

Returns:

A list of SensorInfo objects, each containing metadata about a sensor, such as serial number, firmware version, and calibration details.

close()[source]
Return type:

None

property is_live: bool

Check if the packet source is live.

class FrameBorder(meta, pred=<function FrameBorder.<lambda>>)[source]

Bases: object

Create callable helper that indicates the cross frames packets.

first_valid_column(scan)[source]

Return first valid column of a LidarScan

Return type:

int

last_valid_column(scan)[source]

Return last valid column of a LidarScan

Return type:

int

first_valid_column_ts(scan)[source]

Return first valid column timestamp of a LidarScan

Return type:

int

first_valid_packet_ts(scan)[source]

Return first valid packet timestamp of a LidarScan

Return type:

int

last_valid_packet_ts(scan)[source]

Return first valid packet timestamp of a LidarScan

Return type:

int

last_valid_column_ts(scan)[source]

Return last valid column timestamp of a LidarScan

Return type:

int

first_valid_column_pose(scan)[source]

Return first valid column pose of a LidarScan

Return type:

ndarray

last_valid_column_pose(scan)[source]

Return last valid column pose of a LidarScan

Return type:

ndarray

valid_packet_idxs(scan)[source]

Checks for valid packets that was used in in the scan construction

Return type:

ndarray

poses_present(scan)[source]

Check whether any of scan.pose in not identity

Return type:

bool

ouster.sdk.core.data

Copyright (c) 2021, Ouster, Inc. All rights reserved.

BufferT

Types that support the buffer protocol.

alias of Union[bytes, bytearray, memoryview, ndarray]

class ChanField[source]

Bases: object

RANGE = 'RANGE'
RANGE2 = 'RANGE2'
SIGNAL = 'SIGNAL'
SIGNAL2 = 'SIGNAL2'
REFLECTIVITY = 'REFLECTIVITY'
REFLECTIVITY2 = 'REFLECTIVITY2'
NEAR_IR = 'NEAR_IR'
FLAGS = 'FLAGS'
FLAGS2 = 'FLAGS2'
RAW_HEADERS = 'RAW_HEADERS'
RAW32_WORD1 = 'RAW32_WORD1'
RAW32_WORD2 = 'RAW32_WORD2'
RAW32_WORD3 = 'RAW32_WORD3'
RAW32_WORD4 = 'RAW32_WORD4'
RAW32_WORD5 = 'RAW32_WORD5'
RAW32_WORD6 = 'RAW32_WORD6'
RAW32_WORD7 = 'RAW32_WORD7'
RAW32_WORD8 = 'RAW32_WORD8'
RAW32_WORD9 = 'RAW32_WORD9'
class ColHeader(value)[source]

Bases: Enum

Column headers available in lidar data.

This definition is deprecated.

TIMESTAMP = 0
ENCODER_COUNT = 1
MEASUREMENT_ID = 2
STATUS = 3
FRAME_ID = 4
stagger(info, fields)[source]

Return a staggered copy of the provided fields.

In the default staggered representation, each column corresponds to a single timestamp. A destaggered representation compensates for the azimuth offset of each beam, returning columns that correspond to a single azimuth angle.

Parameters:

  • info (SensorInfo) – Sensor metadata associated with the provided data

  • fields (ndarray) – A numpy array of shape H X W or H X W X N

Return type:

ndarray

Returns:

A staggered numpy array of the same shape

destagger(info, fields, inverse=False)[source]

Return a destaggered copy of the provided fields.

In the default staggered representation, each column corresponds to a single timestamp. A destaggered representation compensates for the azimuth offset of each beam, returning columns that correspond to a single azimuth angle.

Parameters:

  • info (SensorInfo) – Sensor metadata associated with the provided data

  • fields (ndarray) – A numpy array of shape H X W or H X W X N

  • inverse – perform inverse “staggering” operation

Return type:

ndarray

Returns:

A destaggered numpy array of the same shape

XYZLut(info, use_extrinsics=False)[source]

Return a function that can project scans into Cartesian coordinates.

If called with a numpy array representing a range image, the range image must be in “staggered” form, where each column corresponds to a single measurement block. LidarScan fields are always staggered.

Internally, this will pre-compute a lookup table using the supplied intrinsic parameters. XYZ points are returned as a H x W x 3 array of doubles, where H is the number of beams and W is the horizontal resolution of the scan.

The coordinates are reported in meters in the sensor frame (when use_extrinsics is False, default) as defined in the sensor documentation.

However, the result is returned in the “extrinsics frame” if use_extrinsics is True, which makes additional transform from “sensor frame” to “extrinsics frame” using the homogeneous 4x4 transform matrix from info.extrinsic property.

Parameters:

  • info (SensorInfo) – sensor metadata

  • use_extrinsics (bool) – if True, applies the info.extrinsic transform to the resulting “sensor frame” coordinates and returns the result in “extrinsics frame”.

Return type:

Callable[[Union[LidarScan, ndarray]], ndarray]

Returns:

A function that computes a point cloud given a range image

XYZLutFloat(info, use_extrinsics=False)[source]
Return type:

Callable[[Union[LidarScan, ndarray]], ndarray]

packet_ts(packet)[source]

Return the packet timestamp in nanoseconds

Return type:

int

ouster.sdk.core.io_types

ouster.sdk.core.masked_scan_source

class MaskedScanSource(scan_source, fields, masks)[source]

Bases: ScanSource

property sensor_info: List[SensorInfo]

Retrieve sensor information for all sensors in the scan source.

Returns:

A list of SensorInfo objects, each containing metadata about a sensor, such as serial number, firmware version, and calibration details.

property is_live: bool

Check if the scan source is live.

A live scan source indicates that it is actively receiving data from a sensor.

Returns:

True if the scan source is live, False otherwise.

Return type:

bool

property is_indexed: bool
property scans_num: List[int]
close()[source]
Return type:

None

ouster.sdk.core.multi

Deprecated since version collate_scans: is deprecated: use ouster.sdk.core.collate instead. collate_scans will be removed in the upcoming release.

collate_scans(source, sensors_count, get_ts, *, dt=210000000)[source]

Collate by sensor idx with a cut every dt (ns) time length.

Assuming that multi sensor packets stream are PTP synced, so the sensor time of LidarScans don’t have huge deltas in time, though some latency of packets receiving (up to dt) should be ok.

Parameters:

  • source (Iterable[Tuple[int, Any]]) – data stream with scans

  • sensors_count (int) – number of sensors generating the stream of scans

  • dt (int) – max time difference between scans in the collated scan (i.e. max time period at which every new collated scan is released/cut), default is 0.21 s

Return type:

Iterator[List[Optional[Any]]]

Returns:

List of LidarScans elements

class Scans(source, *, complete=False, cycle=False, fields=None, **_)[source]

Bases: ScanSource

Multi LidarScan source.

Parameters:

  • source (PacketSource) – packet multi source

  • complete (bool) – set to True to only release complete scans

  • cycle (bool) – repeat infinitely after iteration is finished is True. in case source refers to a live sensor then this parameter has no effect.

  • fields (Optional[List[List[FieldType]]]) – specify which channel fields to populate on LidarScans

property sensor_info: List[SensorInfo]

Retrieve sensor information for all sensors in the scan source.

Returns:

A list of SensorInfo objects, each containing metadata about a sensor, such as serial number, firmware version, and calibration details.

property is_live: bool

Check if the scan source is live.

A live scan source indicates that it is actively receiving data from a sensor.

Returns:

True if the scan source is live, False otherwise.

Return type:

bool

property is_indexed: bool
property fields: List[List[str]]
property field_types: List[List[FieldType]]
property scans_num: List[int]
close()[source]
Return type:

None

ouster.sdk.core.reduced_scan_source

class ReducedScanSource(scan_source, beams)[source]

Bases: ScanSource

Takes a regular ScanSource and reduces the beams count to the specified values.

property sensor_info: List[SensorInfo]

Retrieve sensor information for all sensors in the scan source.

Returns:

A list of SensorInfo objects, each containing metadata about a sensor, such as serial number, firmware version, and calibration details.

property is_live: bool

Check if the scan source is live.

A live scan source indicates that it is actively receiving data from a sensor.

Returns:

True if the scan source is live, False otherwise.

Return type:

bool

property is_indexed: bool
property scans_num: List[int]
close()[source]
Return type:

None

ouster.sdk.core.scan_ops

clip(scan, fields, lower, upper, invalid=0)[source]

limits the values of the specified set of fields to within the range = [lower, upper], any value that exceeds this range is replaced by the supplied invalid value (default is zero)

Return type:

None

filter_field(scan, field, lower, upper, invalid=0, filtered_fields=None)[source]

Filters out scan fields based on the specified axis and range. Values that falls in the range [lower, upper] are replaced by the supplied invalid value (default is zero).

Parameters: - scan: LidarScan - field: str; the field to be used as the filter - lower: float; lower bound - upper: float; upper bound - invalid: int; the invalid value to use default is 0 - filtered_fields: Optional[List[str]]; an optional list of fields to filter

Return type:

None

filter_uv(scan, coord_2d, lower, upper, invalid=0, filtered_fields=None)[source]

Filters the scan based on the specified image axis. Values that falls in the range [lower, upper] are replaced by the supplied invalid value (default is zero).

Parameters: - scan: LidarScan - field: str; the field to be used as the filter - lower: Union[int, float]; lower bound if float it is assumed a percentage - upper: Union[int, float]; upper bound if float it is assumed a percentage - invalid: int; the invalid value to use default is 0 - filtered_fields: Optional[List[str]]; an optional list of fields to filter

Return type:

None

filter_xyz(scan, xyzlut, axis_idx, lower=-inf, upper=inf, invalid=0, filtered_fields=None)[source]

Filters the scan based on the specified axis and range. Values below the lower bound or above the upper bound are replaced by the supplied invalid value (default is zero)

Parameters: - scan: LidarScan - xyzlut: Callable[[Union[LidarScan, np.ndarray]], np.ndarray] - axis_idx: int; can be 0, 1, or 2 - lower: float; lower bound - upper: float; upper bound - invalid: int; the invalid value to use default is 0 - filtered_fields: Optional[List[str]]; an optional list of fields to filter

Return type:

None

mask(scan, fields, mask)[source]

applies a mask/filter to all fields of the LidarScan mask should be of the same as size scan.PIXEL_FIELD

Return type:

None

reduce_by_factor_metadata(metadata, factor)[source]
Return type:

SensorInfo

reduce_by_factor(scan, factor, update_metadata=False)[source]

Vertically downsample the LidarScan by the supplied factor factor must by a divisor of the LidarScan height

Return type:

LidarScan

Enums