Module `ouster.client`

class Sensor(hostname='localhost', lidar_port=7502, imu_port=7503, *, metadata=None, buf_size=128, timeout=1.0, _overflow_err=False, _flush_before_read=True, _legacy_format=True)[source]

A packet source listening on local UDP ports.

Uses a separate thread that fills internal buffers without holding the GIL.

Note

Make sure close() will be called on all instances before Python attempts to exit, or the interpreter will hang waiting to join the thread (like any other non-daemonized Python thread).

Neither the ports nor udp destination configuration on the sensor will be updated. The metadata will be fetched over the network from the sensor unless explicitly provided using the metadata parameter.

Parameters

hostname (str) – hostname or IP address of the sensor
lidar_port (int) – UDP port to listen on for lidar data
imu_port (int) – UDP port to listen on for imu data
metadata (Optional[SensorInfo]) – explicitly provide metadata for the stream
buf_size (int) – number of packets to buffer before dropping data
timeout (Optional[float]) – seconds to wait for packets before signaling error or None
_overflow_err (bool) – if True, raise ClientOverflow
_flush_before_read (bool) – if True, try to clear buffers before reading
_legacy_format (bool) – if True, use legacy metadata format

Raises

ClientError – If initializing the client fails.

write_metadata(path)[source]

Save metadata to disk.

Parameters: path (str) – path to write
Return type: None

property metadata: ouster.client._client.SensorInfo

Metadata associated with the packet stream.

Return type: SensorInfo

__iter__()[source]

Access the UDP data stream as an iterator.

Reading may block waiting for network data for up to the specified timeout. Failing to consume this iterator faster than the data rate of the sensor may cause packets to be dropped.

Raises

ClientTimeout – if no packets are received within the configured timeout
ClientError – if the client enters an unspecified error state
ValueError – if the packet source has already been closed

Return type

Iterator[Union[ImuPacket, LidarPacket]]

flush(n_frames=3, *, full=False)[source]

Drop some data to clear internal buffers.

Parameters

n_frames (int) – number of frames to drop
full – clear internal buffers first, so data is read from the OS receive buffers (or the network) directly

Return type

int

Returns

The number of packets dropped

Raises

ClientTimeout – if a lidar packet is not received within the configured timeout
ClientError – if the client enters an unspecified error state

close()[source]

Shut down producer thread and close network connection.

Attributes may be unset if constructor throws an exception.

Return type: None

class Scans(source, *, complete=False, timeout=None, fields=None, _max_latency=0)[source]

An iterable stream of scans batched from a PacketSource.

Batching will emit a scan every time the frame_id increments (i.e. on receiving first packet in the next scan). Reordered packets will be handled, except across frame boundaries: packets from the previous scan will be dropped.

Optionally filters out incomplete frames and enforces a timeout. A batching timeout can be useful to detect when we’re only receiving incomplete frames or only imu packets. Can also be configured to manage internal buffers for soft real-time applications.

Parameters

source (PacketSource) – any source of packets
complete (bool) – if True, only return full scans
timeout (Optional[float]) – seconds to wait for a scan before error or None
fields (Optional[Dict[ChanField, Type[unsignedinteger]]]) – specify which channel fields to populate on LidarScans
_max_latency (int) – (experimental) approximate max number of frames to buffer

__iter__()[source]

Get an iterator.

Return type: Iterator[LidarScan]

close()[source]

Close the underlying PacketSource.

Return type: None

property metadata: ouster.client._client.SensorInfo

Return metadata from the underlying PacketSource.

Return type: SensorInfo

classmethod sample(hostname='localhost', n=1, lidar_port=7502, *, metadata=None)[source]

Conveniently sample n consecutive scans from a sensor.

Does not leave UDP ports open. Suitable for interactive use.

Parameters

hostname (str) – hostname of the sensor
n (int) – number of consecutive frames in each sample
lidar_port (int) – UDP port to listen on for lidar data
metadata (Optional[SensorInfo]) – explicitly provide metadata for the stream

Return type

Tuple[SensorInfo, Iterator[List[LidarScan]]]

Returns

A tuple of metadata queried from the sensor and an iterator that samples n consecutive scans

classmethod stream(hostname='localhost', lidar_port=7502, *, buf_size=640, timeout=1.0, complete=True, metadata=None, fields=None)[source]

Stream scans from a sensor.

Will drop frames preemptively to avoid filling up internal buffers and to avoid returning frames older than the scanning period of the sensor.

Parameters

hostname (str) – hostname of the sensor
lidar_port (int) – UDP port to listen on for lidar data
timeout (Optional[float]) – seconds to wait for scans before signaling error
complete (bool) – if True, only return full scans
metadata (Optional[SensorInfo]) – explicitly provide metadata for the stream
fields (Optional[Dict[ChanField, Type[unsignedinteger]]]) – specify which channel fields to populate on LidarScans

Return type

Scans

Metadata 

class SensorInfo

Sensor Info required to interpret UDP data streams.

See the sensor documentation for the meaning of each property.

Parameters: raw (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 extrinsic: Extrinsic Matrix.

property format: Describes the structure of a lidar packet.

static from_default(): Create gen-1 OS-1-64 SensorInfo populated with design values.

property fw_rev: Sensor firmware revision.

property hostname: Sensor hostname.

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 mode: Lidar mode, e.g., 1024x10.

property prod_line: Product line, e.g., ‘OS-1-128’.

property sn: Sensor serial number.

property udp_port_imu: Configured port for imu data.

property udp_port_lidar: Configured port for lidar data.

class SensorConfig

Corresponds to sensor config parameters. Please see sensor documentation for the meaning of each property.

Parameters: raw (str) – json string to parse

property azimuth_window: Tuple representing the visible region of interest of the sensor in millidegrees, .e.g., (0, 360000) for full visibility.

property columns_per_packet: Measurement blocks per UDP packet. See sensor documentation for details.

property lidar_mode: Horizontal and Vertical Resolution rate of sensor as mode, e.g., 1024x10. See class LidarMode.

property multipurpose_io_mode: Mode of MULTIPURPOSE_IO pin. See class MultipurposeIOMode.

property nmea_baud_rate: Expected baud rate sensor attempts to decode for NMEA UART input $GPRMC messages.

property nmea_ignore_valid_char: NMEA Ignore Valid Char. True corresponds to 1 and False to 0 for property; see sensor documentation for details.

property nmea_in_polarity: Polarity of NMEA UART input $GPRMC messages. See sensor documentation for details.

property nmea_leap_seconds: Integer number of leap seconds that will be added to the UDP timetsamp when calculating seconds since Unix Epoch time. See sensor documentation for details.

property operating_mode: Operating Mode of sensor. See class OperatingMode.

property phase_lock_enable: Enable phase lock. See sensor documentation for more details.

property phase_lock_offset: Angle in Lidar Coordinate Frame that sensors are locked to, in millidegrees. See sensor documentation for details.

property signal_multiplier: Multiplier for signal strength of sensor, corresponding to maximum allowable azimuth_window. Gen 2 Only.

property sync_pulse_in_polarity: Polarity of SYNC_PULSE_IN pin. See sensor documentation for details.

property sync_pulse_out_angle: Polarity of SYNC_PULSE_OUT output. See sensor documentation for details.

property sync_pulse_out_frequency: SYNC_PULSE_OUT rate. See sensor documentation for details.

property sync_pulse_out_polarity: Polarity of SYNC_PULSE_OUT output. See sensor documentation for details.

property sync_pulse_out_pulse_width: SYNC_PULSE_OUT pulse width in ms. See sensor documentation for details.

property timestamp_mode: Timestamp mode of sensor. See class TimestampMode.

property udp_dest: Destination to which sensor sends UDP traffic.

property udp_port_imu: Port on UDP destination to which IMU data will be sent.

property udp_port_lidar: Port on UDP destination to which lidar data will be sent.

property udp_profile_imu: UDP packet format for imu data. See sensor documentation for details.

property udp_profile_lidar: UDP packet format for lidar data. See sensor documentation for details.

get_config()

Returns sensor config parameters as SensorConfig.

Parameters

hostname (str) – hostname of the sensor
active (bool) – return active or staged sensor configuration

set_config()

Set sensor config parameters on sensor.

Parameters

hostname (str) – hostname of the sensor
config (SensorConfig) – config to set sensor parameters to
persist (bool) – persist parameters after sensor disconnection (default = False)
udp_dest_auto – automatically determine sender’s IP at the time command was sent and set it as destination of UDP traffic. Function will error out if config has udp_dest member. (default = False)

class LidarMode

Possible Lidar Modes of sensor.

Determines to horizontal and vertical resolution rates of sensor. See sensor documentation for details.

Members:

MODE_UNKNOWN

MODE_512x10

MODE_512x20

MODE_1024x10

MODE_1024x20

MODE_2048x10

MODE_4096x5

MODE_UNSPEC

MODE_1024x10 = <LidarMode.MODE_1024x10: 3>

MODE_1024x20 = <LidarMode.MODE_1024x20: 4>

MODE_2048x10 = <LidarMode.MODE_2048x10: 5>

MODE_4096x5 = <LidarMode.MODE_4096x5: 6>

MODE_512x10 = <LidarMode.MODE_512x10: 1>

MODE_512x20 = <LidarMode.MODE_512x20: 2>

MODE_UNKNOWN = <LidarMode.MODE_UNKNOWN: 0>

MODE_UNSPEC = <LidarMode.MODE_UNKNOWN: 0>

property cols: Returns columns of lidar mode, e.g., 1024 for LidarMode 1024x10.

property frequency: Returns frequency of lidar mode, e.g. 10 for LidarMode 512x10.

from_string(): Create LidarMode from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

class TimestampMode

Possible Timestamp modes of sensor.

See sensor documentation for details.

Members:

UNKNOWN

TIME_FROM_INTERNAL_OSC

TIME_FROM_SYNC_PULSE_IN

TIME_FROM_PTP_1588

TIME_FROM_UNSPEC

TIME_FROM_INTERNAL_OSC = <TimestampMode.TIME_FROM_INTERNAL_OSC: 1>

TIME_FROM_PTP_1588 = <TimestampMode.TIME_FROM_PTP_1588: 3>

TIME_FROM_SYNC_PULSE_IN = <TimestampMode.TIME_FROM_SYNC_PULSE_IN: 2>

TIME_FROM_UNSPEC = <TimestampMode.UNKNOWN: 0>

UNKNOWN = <TimestampMode.UNKNOWN: 0>

from_string(): Create TimestampMode from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

class OperatingMode

Possible Operating modes of sensor.

See sensor documentation for details.

Members:

OPERATING_NORMAL

OPERATING_STANDBY

OPERATING_NORMAL = <OperatingMode.OPERATING_NORMAL: 1>

OPERATING_STANDBY = <OperatingMode.OPERATING_STANDBY: 2>

static from_string(): Create enum value from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

class MultipurposeIOMode

Mode of MULTIPURPOSE_IO pin.

See sensor documentation for details.

Members:

MULTIPURPOSE_OFF

MULTIPURPOSE_INPUT_NMEA_UART

MULTIPURPOSE_OUTPUT_FROM_INTERNAL_OSC

MULTIPURPOSE_OUTPUT_FROM_SYNC_PULSE_IN

MULTIPURPOSE_OUTPUT_FROM_PTP_1588

MULTIPURPOSE_OUTPUT_FROM_ENCODER_ANGLE

MULTIPURPOSE_INPUT_NMEA_UART = <MultipurposeIOMode.MULTIPURPOSE_INPUT_NMEA_UART: 2>

MULTIPURPOSE_OFF = <MultipurposeIOMode.MULTIPURPOSE_OFF: 1>

MULTIPURPOSE_OUTPUT_FROM_ENCODER_ANGLE = <MultipurposeIOMode.MULTIPURPOSE_OUTPUT_FROM_ENCODER_ANGLE: 6>

MULTIPURPOSE_OUTPUT_FROM_INTERNAL_OSC = <MultipurposeIOMode.MULTIPURPOSE_OUTPUT_FROM_INTERNAL_OSC: 3>

MULTIPURPOSE_OUTPUT_FROM_PTP_1588 = <MultipurposeIOMode.MULTIPURPOSE_OUTPUT_FROM_PTP_1588: 5>

MULTIPURPOSE_OUTPUT_FROM_SYNC_PULSE_IN = <MultipurposeIOMode.MULTIPURPOSE_OUTPUT_FROM_SYNC_PULSE_IN: 4>

static from_string(): Create enum value from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

class Polarity

Pulse Polarity.

Applicable to several Polarity settings on sensor.

Members:

POLARITY_ACTIVE_LOW

POLARITY_ACTIVE_HIGH

POLARITY_ACTIVE_HIGH = <Polarity.POLARITY_ACTIVE_HIGH: 2>

POLARITY_ACTIVE_LOW = <Polarity.POLARITY_ACTIVE_LOW: 1>

static from_string(): Create enum value from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

class NMEABaudRate

Expected baud rate sensor attempts to decode for NMEA UART input $GPRMC messages.

Members:

BAUD_9600

BAUD_115200

BAUD_115200 = <NMEABaudRate.BAUD_115200: 2>

BAUD_9600 = <NMEABaudRate.BAUD_9600: 1>

static from_string(): Create enum value from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

class UDPProfileLidar

UDP lidar profile.

Members:

PROFILE_LIDAR_LEGACY

PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16_DUAL

PROFILE_LIDAR_RNG19_RFL8_SIG16_NIR16

PROFILE_LIDAR_RNG15_RFL8_NIR8

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>

static from_string(): Create enum value from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

Data 

BufferT

Types that support the buffer protocol.

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

Packet

Packets emitted by a sensor.

alias of Union[ImuPacket, LidarPacket]

class ImuPacket(data, info, timestamp=None)[source]

Read IMU Packet data from a bufer.

This will always alias the supplied buffer-like object. Pass in a copy to avoid unintentional aliasing.

Parameters

data (Union[bytes, bytearray, memoryview, ndarray]) – Buffer containing the packet payload
info (SensorInfo) – Metadata associated with the sensor packet stream
timestamp (Optional[float]) – A capture timestamp, in seconds

Raises

ValueError – If the buffer is smaller than the size specified by the packet format

property sys_ts: int

System timestamp in nanoseconds.

Return type: int

property accel_ts: int

Accelerometer read time in nanoseconds.

Return type: int

property gyro_ts: int

Gyro read time in nanoseconds.

Return type: int

property accel: numpy.ndarray

Acceleration as a 3-D vector in G.

Return type: ndarray

property angular_vel: numpy.ndarray

Angular velocity as a 3-D vector in deg/second.

Return type: ndarray

class LidarPacket(data, info, timestamp=None)[source]

Read lidar packet data as numpy arrays.

The dimensions of returned arrays depend on the sensor product line and configuration. Measurement headers will be arrays of size matching the configured columns_per_packet, while measurement fields will be 2d arrays of size pixels_per_column by columns_per_packet.

This will always alias the supplied buffer-like object. Pass in a copy to avoid unintentional aliasing.

Parameters

data (Union[bytes, bytearray, memoryview, ndarray]) – Buffer containing the packet payload
info (SensorInfo) – Metadata associated with the sensor packet stream
timestamp (Optional[float]) – A capture timestamp, in seconds

Raises

ValueError – If the buffer is smaller than the size specified by the packet format, or if the init_id doesn’t match the metadata

property packet_type: int

Get the type header of the packet.

Return type: int

property frame_id: int

Get the frame id of the packet.

Return type: int

property init_id: int

Get the initialization id of the packet.

Return type: int

property prod_sn: int

Get the serial no header of the packet.

Return type: int

property fields: Iterator[ouster.client._client.ChanField]

Get available fields of LidarScan as Iterator.

Return type: Iterator[ChanField]

field(field)[source]

Create a view of the specified channel field.

Parameters: field (ChanField) – The channel field to view
Return type: ndarray
Returns: A numpy array containing a copy of the specified field values

header(header)[source]

Create a view of the specified column header.

This method is deprecated. Use the timestamp, measurement_id or status properties instead.

Parameters: header (ColHeader) – The column header to parse
Return type: ndarray
Returns: A numpy array containing a copy of the specified header values

property timestamp: numpy.ndarray

Parse the measurement block timestamps out of a packet buffer.

Return type: ndarray
Returns: An array of the timestamps of all measurement blocks in the packet.

property measurement_id: numpy.ndarray

Parse the measurement ids out of a packet buffer.

Return type: ndarray
Returns: An array of the ids of all measurement blocks in the packet.

property status: numpy.ndarray

Parse the measurement statuses of a packet buffer.

Return type: ndarray
Returns: An array of the statuses of all measurement blocks in the packet.

class ChanField

Channel data block fields

Members:

RANGE

RANGE2

SIGNAL

SIGNAL2

REFLECTIVITY

REFLECTIVITY2

NEAR_IR

FLAGS

FLAGS2

CUSTOM0

CUSTOM1

CUSTOM2

CUSTOM3

CUSTOM4

CUSTOM5

CUSTOM6

CUSTOM7

CUSTOM8

CUSTOM9

RAW32_WORD1

RAW32_WORD2

RAW32_WORD3

RAW32_WORD4

CUSTOM0 = <ChanField.CUSTOM0: 50>

CUSTOM1 = <ChanField.CUSTOM1: 51>

CUSTOM2 = <ChanField.CUSTOM2: 52>

CUSTOM3 = <ChanField.CUSTOM3: 53>

CUSTOM4 = <ChanField.CUSTOM4: 54>

CUSTOM5 = <ChanField.CUSTOM5: 55>

CUSTOM6 = <ChanField.CUSTOM6: 56>

CUSTOM7 = <ChanField.CUSTOM7: 57>

CUSTOM8 = <ChanField.CUSTOM8: 58>

CUSTOM9 = <ChanField.CUSTOM9: 59>

FLAGS = <ChanField.FLAGS: 8>

FLAGS2 = <ChanField.FLAGS2: 9>

NEAR_IR = <ChanField.NEAR_IR: 7>

RANGE = <ChanField.RANGE: 1>

RANGE2 = <ChanField.RANGE2: 2>

RAW32_WORD1 = <ChanField.RAW32_WORD1: 60>

RAW32_WORD2 = <ChanField.RAW32_WORD2: 61>

RAW32_WORD3 = <ChanField.RAW32_WORD3: 62>

RAW32_WORD4 = <ChanField.RAW32_WORD4: 63>

REFLECTIVITY = <ChanField.REFLECTIVITY: 5>

REFLECTIVITY2 = <ChanField.REFLECTIVITY2: 6>

SIGNAL = <ChanField.SIGNAL: 3>

SIGNAL2 = <ChanField.SIGNAL2: 4>

static from_string(): Create enum value from string.

property name: The name of the Enum member.

property value: The value of the Enum member.

values = <iterator object>

class ColHeader(value)[source]

Column headers available in lidar data.

This definition is deprecated.

TIMESTAMP = 0

ENCODER_COUNT = 1

MEASUREMENT_ID = 2

STATUS = 3

FRAME_ID = 4

class LidarScan

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
fields_dict – dict where keys are ChanFields and values are type, e.g., {client.ChanField.SIGNAL: np.uint32}

Returns

New LidarScan of specified dimensions expecting fields specified by dict

field()

Return a view of the specified channel field.

Parameters: field – The channel field to return
Returns: The specified field as a numpy array

property fields: Return an iterator of available channel fields.

property frame_id: Corresponds to the frame id header in the packet format.

property h: Height or vertical resolution of the scan.

header()

Return the specified column header as a numpy array.

This function is deprecated. Use the measurment_id, timestamp or status properties instead.

Parameters: header – The column header to return
Returns: The specified column header as a numpy array

property measurement_id: The measurement id header as a W-element numpy array.

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

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

property w: Width or horizontal resolution of the scan.

XYZLut(info)[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 as defined in the sensor documentation.

Parameters: info (SensorInfo) – sensor metadata
Return type: Callable[[Union[LidarScan, ndarray]], ndarray]
Returns: A function that computes a point cloud given a range image

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

Module ouster.client

Core

Metadata

Data

Module `ouster.client`

Core 

Metadata 

Data 