ouster.sdk.util¶

Module contents¶

This module provides generic utility functions and helpers for working with Ouster lidar data.

Classes¶

class ForwardSlicer

Functions¶

frame_to_packets(lf, info)
img_aspect_ratio(info)
progressbar(progress, total, prefix = '', suffix = '')
resolve_field_types(metadata : collections.abc.Sequence [ ouster.sdk.core.SensorInfo ], raw_headers : bool = False, raw_fields : bool = False, field_names : Optional [ collections.abc.Sequence [ str ] ] | None = None) → list [ list [ ouster.sdk.core.FieldType ] ]
resolve_metadata(data_path, meta_path = None)
resolve_metadata_multi(data_path)

ouster.sdk.util.forward_slicer¶

class ForwardSlicer[source]¶

Bases: object

ForwardSlicer provides slicing methods to slice up a container with step to containers that only support forward slicing

static normalize(key, L)[source]¶

Return type:

slice

Parameters:

key (slice)
L (int)

static slice(data_iter, key)[source]¶

Performs forward slicing on a dataset with step

Parameters: - key: must be a normalized slice key with relation to the used data_iter.

a normalized slice key is one where key.start < key.stop and no non-values

Returns:

a list of items scoped to the input key

Return type:

List

Parameters:

data_iter (Iterator)
key (slice)

static slice_iter(data_iter, key)[source]¶

Performs forward slicing on a dataset with step

Parameters: - key: must be a normalized slice key with relation to the used data_iter.

a normalized slice key is one where key.start < key.stop and no non-values

Returns:

an iterator scoped to the input key

Return type:

Iterator

Parameters:

data_iter (Iterator)
key (slice)

ouster.sdk.util.parsing¶

R/W implementation of packet parsing.

Doesn’t rely on custom C++ extensions (just numpy). Provides writable view of packet data for testing and development.

cut_raw32_words(lf)[source]¶

Return type:: LidarFrame
Parameters:: lf (LidarFrame)

frame_to_packets(lf, info)[source]¶

Converts LidarFrame to a lidar_packet buffers

Parameters:

lf (LidarFrame) – LidarFrame; if LidarFrame has RAW_HEADERS field, packet headers are recreated to how they were in the original packets
info (SensorInfo) – metadata of the lf frame

Return type:

List[Union[LidarPacket, ZonePacket, ImuPacket]]

Returns:

A set of lidar packets that will produce the same LidarFrame if passed through the FrameBatcher again (less fields data)

packets_to_frame(packets, info, *, fields=None)[source]¶

Batch buffers that belongs to a single frame into a LidarFrame object. :rtype: LidarFrame

Parameters:

packets (List[LidarPacket | ZonePacket | ImuPacket])
info (SensorInfo)
fields (List[FieldType] | None)

Return type:

LidarFrame

tohex(data)[source]¶

Makes a hex string for debug print outs of buffers.

Selects the biggest devisor of np.uint32, np.uint16 or np.uint8 for making a hex output of the provided data. (clunky but usefull for debugging)

Return type:: str
Parameters:: data (bytes | bytearray | memoryview | ndarray)

ouster.sdk.util.extrinsics¶

Miscellaneous utilities.

euler_to_rotation_matrix(roll, pitch, yaw)[source]¶

Convert Euler angles (roll, pitch, yaw) to a 3D rotation matrix.

Parameters:

roll – Rotation about the x-axis (rad)
pitch – Rotation about the y-axis (rad)
yaw – Rotation about the z-axis (rad)

Returns:

3x3 rotation matrix

Return type:

R

fov_horizontal(info)[source]¶

Return type:: float
Parameters:: info (SensorInfo)

fov_vertical(info)[source]¶

Return type:: float
Parameters:: info (SensorInfo)

img_aspect_ratio(info)[source]¶

Returns 2D image aspect ratio based on sensor FOV angles.

Return type:: float
Parameters:: info (SensorInfo)

Uses the order:: img_aspect_ratio = FOV_vertical / FOV_horizontal

parse_extrinsics_from_string(extrinsics, degrees=True)[source]¶

A utility method to parse extrinsics in multiple formats.

Parameters:

extrinsics (- A json with containing a per sensor) – a string representing a file or extrinsics in a supported format
degrees – whether angles should be parsed as degress (True by default)
formats (Acceptale extrinsics)
extrinsics
identity (- identity ; Use this to override any stored extrinsics with)
angles (- X Y Z R P Y ; 'R P Y' represent euler)
; (- X Y Z QX QY QZ QW)
order (- n1 n2 .. n16 ; 16 floats representing a 2D array in a row-major)

Returns:

4x4 transformation matrix or a filename

Return type:

R

position_quaternion_to_transform(p, q)[source]¶

Converts Quaternion + Pose [7] vector to homogeneous [4x4] matrix. :rtype: ndarray

Parameters:

p (ndarray)
q (ndarray)

Return type:

ndarray

quaternion_to_rotation_matrix(q)[source]¶

Converts Quaternion [w, x, y, z] to Rotation [3x3] matrix. :rtype: ndarray

Parameters:: q (ndarray)
Return type:: ndarray

rotation_matrix_to_quaternion(R)[source]¶

Converts a Rotation [3x3] matrix to Quaternion [w, x, y, z]. :rtype: ndarray

Parameters:: R (ndarray)
Return type:: ndarray

xyzq_to_matrix(px, py, pz, qx, qy, qz, qw)[source]¶

A method that takes position + quaternion (rad) and produces an equivalent 4x4 transform.

Parameters:

px – position
py – position
pz – position
qx – rotation expressed in a quaternion
qy – rotation expressed in a quaternion
qz – rotation expressed in a quaternion
qw – rotation expressed in a quaternion

Returns:

4x4 transformation matrix

Return type:

R

xyzrpy_to_matrix(px, py, pz, r, p, y)[source]¶

A method that takes position + euler angles (rad) and produces an equivalent 4x4 transform.

Parameters:

px – position
py – position
pz – position
r – rotation expressed in euler angles (rad)
p – rotation expressed in euler angles (rad)
y – rotation expressed in euler angles (rad)

Returns:

4x4 transformation matrix

Return type:

R

ouster.sdk.util.progress_bar¶

class ProgressBar(total, alpha=0.05, unit='')[source]¶

Bases: object

clear()[source]¶

update(progress, prefix='', suffix='')[source]¶

progressbar(progress, total, prefix='', suffix='')[source]¶

Displays progress in the console as a percentage.

Parameters:

progress – The current progress (number of items completed).
total – The total number of items.
prefix – A prefix string to display before the progress bar (optional).
suffix – A suffix string to display after the progress bar (optional).

ouster.sdk.util.metadata¶

Miscellaneous utilites.

resolve_metadata(data_path, meta_path=None)[source]¶

Look for a metadata file based on the data path if needed.

Convenient to use in CLI tools when –meta param can be omitted in lots of trivial cases when pcap filename has the same prefix as the metadata json filename.

Parameters:

data_path (str) – filename location with the data, usually .pcap or .bag that is used to search metadata with the most common prefix file
meta_path (Optional[str]) – the pass through metadata path, if set guessing and search for other metadata jsons is skipped

Return type:

Optional[str]

Returns:

metadata json paths guessed with the most common prefix match or passed through from meta_path parameter

resolve_metadata_multi(data_path)[source]¶

Look for a metadata files based on the pcap path with multi sensors.

Parameters:: data_path (str) – filename location with the data, usually .pcap or .bag
Return type:: List[str]
Returns:: list of metadata json paths guessed with the most common prefix match

resolve_field_types¶

resolve_field_types(metadata: collections.abc.Sequence[ouster.sdk.core.SensorInfo], raw_headers: bool = False, raw_fields: bool = False, field_names: Optional[collections.abc.Sequence[str]] | None = None) → list[list[ouster.sdk.core.FieldType]]¶

Resolve field types for a given set of metadata and field names.

This function determines the types of fields (e.g., signal, reflectivity) based on the provided sensor metadata and field names.

Parameters:

metadata (List[SensorInfo]) – A list of sensor metadata objects.
raw_headers (bool) – Whether to include raw headers in the resolution. Default is False.
raw_fields (bool) – Whether to include raw fields in the resolution. Default is False.
field_names (List[str]) – A list of field names to resolve. Default is an empty list.

Returns:

A list of resolved field types.

Return type:

List[FieldType]

ouster.sdk.util.pose_util¶

class Poser(*args, **kwargs)[source]¶

Bases: Protocol

Actor that adds poses to LidarFrames

class TrajectoryEvaluator(poses, *, time_bounds=0)[source]¶

Bases: Poser

Interpolates trajectory for a set of timestamps from knot poses.

TODO[pb]: Add function to add/remove knot poses from traj eval.

TODO: Optionally, we may want to implement these calculations in C++ and: use bindings to make it faster.

Parameters:

poses (Sequence[Tuple[Union[int, float, number], ndarray]]) – List of knot poses with timestamps. Every list item is a tuple (ts, pose).
time_bounds (Optional[float]) –
whether to restrict the pose interpolation to the timestamp range within the poses list: None - no restriction at all on the timestamps that can

be used to get pose from the trajectory

0 - strict bounds on the timestamp range in the
poses list

>0 - ratio that is allowed to go over the timestamp
bounds. ratio value is applied as the ratio of pose[1].ts - pose[0].ts for the left bound, and pose[N].ts - pose[N-1].ts for the right bound.

pose_at(ts)[source]¶

Calculates a single pose (4x4 matrix) at a given ts timestamp. :rtype: ndarray

Parameters:: ts (int | float | number)
Return type:: ndarray

poses_at(ts)[source]¶

Calculates multiple poses (4x4 matrices) at a given ts timestamps. :rtype: ndarray

Parameters:: ts (Sequence[int | float | number] | ndarray)
Return type:: ndarray

exp_pose6(pose6)[source]¶

Convert exponential poses to homogeneous matrix poses.

Parameters:: pose6 (ndarray) – vector [6] or matrix [N, 6] of exponential poses
Return type:: ndarray
Returns:: Homogeneous matrix poses of size [4, 4] or [N, 4, 4].

exp_rot_vec(vec)[source]¶

Converts so3 vector to a rotation matrix.

Parameters:: vec (ndarray) – so3 rotation vector [3] or vectors [N, 3] to rotation matrix [3, 3] or matrices [N, 3, 3]
Return type:: ndarray
Returns:: rotation matrix or matrices

load_kitti_poses(file)[source]¶

Loads the Kitti poses from the file.

Return type:: ndarray
Returns:: [N, 4, 4] array of homogeneous poses
Parameters:: file (str)

log_pose(pose)[source]¶

Convert homogeneous matrix(s) to exp pose coordinates.

Parameters:: pose (ndarray) – homogeneous pose [4, 4] or poses [N, 4, 4]
Return type:: ndarray
Returns:: exp pose coordinates [6] or [N, 6]

log_rot_mat(rm)[source]¶

Convert rotation matrix to so3 coordinates (i.e. log() operator)

Parameters:: rm (ndarray) – rotation matrix [3, 3] or matrices [N, 3, 3]
Return type:: ndarray
Returns:: so3 coordinate rotation vector [3] or [N, 3]

make_kiss_traj_poses(poses)[source]¶

Makes a traj poses from kiss poses.

Parameters:: poses (Union[Sequence[ndarray], ndarray]) – pose for every frame in the sequence as returned by KissICP
Returns:: 0.5 For example frame indexes 0, 1, 2 produce timestamps 0.5, 1.5, 2.5
Return type:: trajectory poses timestamped by the frame index mid point

no_scipy()[source]¶

Checks the scipy availability with a warning message. :rtype: bool

Return type:: bool

normalize_vector(v)[source]¶

Return type:: ndarray
Parameters:: v (ndarray)

pose_frames(source, *, poses=None)[source]¶

Add poses to LidarFrames stream.

Parameters:

source – one of: - Sequence[core.LidarFrame] - single frame sources - Sequence[core.FrameSet] - multi frame set sources
poses (Poser | None)

pose_frames_from_kitti(source, kitti_poses)[source]¶

Add poses to LidarFrames stream using the previously saved per frame poses.

Every pose is considered to be in the middle of the frame. We assume that very first frame starts at t = 0 and ends at t = 1, thus the first pose is timestamped as 0.5, second pose is timestamped at 1.5 (middle of the second frame), and so on … to the very last pose N which timestamped at N + 0.5 for the last N frame.

Parameters:

source – one of: - Sequence[core.LidarFrame] - single frame sources - Sequence[core.FrameSet] - multi frame set sources
kitti_poses (str) – path to the file with in kitti poses format, i.e. every line contains 12 floats of 4x4 homogeneous transformation matrix ([:3, :] in numpy notation, row-major serialized)

pose_interp(p1, p2, t, *, delta_pose6=None)[source]¶

Pose interpolation between pose1 and pose2 at time t as ratio.

Parameters:

p1 (ndarray) – starting pose
p2 (ndarray) – ending pose
t (float) – ratio between pose p1 and p2 at what point to interpolate, not restricted between [0, 1] and can be extended for out of bounds
delta_pose6 (Optional[ndarray]) – pre-calculated difference inv(p1) @ p2, saves computation if it’s available already

Return type:

ndarray

Returns:

pose of the point at time t on the line defined by p1 and p2 on SE3 manifold

traj_interp(traj_poses, ts)[source]¶

Trajectory interpolation for points in between.

TODO[pb]: Extend with time_bounds args for traj evaluator when needed :rtype: ndarray

Parameters:

traj_poses (Sequence[Tuple[int | float | number, ndarray]])
ts (Sequence[int | float | number] | ndarray)

Return type:

ndarray

ouster.sdk.util.studio¶

class BearerTokenRedirectAdapter(token_provider, *args, **kwargs)[source]¶

Bases: HTTPAdapter

Custom adapter to ensure the bearer token is passed along in redirects.

send(request, **kwargs)[source]¶

Sends PreparedRequest object. Returns Response object.

Parameters:

request – The PreparedRequest being sent.
stream – (optional) Whether to stream the request content.
timeout (float or tuple or urllib3 Timeout object) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use
cert – (optional) Any user-provided SSL certificate to be trusted.
proxies – (optional) The proxies dictionary to apply to the request.

Return type:

requests.Response

class DataAppClient(org_id)[source]¶

Bases: object

auth()[source]¶: Authenticates

get(url, *, params=None)[source]¶

get_drive(id)[source]¶: Gets information about a specific drive.

get_output_files(id)[source]¶: Get output file information about a specific drive.

get_url_from_id(id)[source]¶

post(url, *, data=None)[source]¶

class DataAppFile(id, recording_url, client, output_type, type)[source]¶

Bases: object

get_signed_url()[source]¶

property url¶

class KeycloakPKCETokenProviderV1(client_id, base_url, keycloak_url, realm_name, organization_id)[source]¶

Bases: object

auth()[source]¶: Call to refresh the tokens and initiate the authorization process.

code_verifier()[source]¶

current()[source]¶

exchange_code_for_token(code)[source]¶

get_authorization_url()[source]¶

get_token()[source]¶

init_tokens(client=None)[source]¶: Initialize the token provider.

make_handler(outer_self)[source]¶

refresh_tokens()[source]¶

exception RetryableException[source]¶

Bases: Exception

Exception used for driving retries in the requests. Internal use.

exception TokenExpiredException[source]¶: Bases: Exception

exception UnAuthorizedException[source]¶

Bases: Exception

Exception used when user’s Access token is invalid. Internal use.

check_and_raise(response, token_provider)[source]¶

delete_tokens_file()[source]¶

get(url, *, params=None, token_provider)[source]¶

get_common_headers(token_provider)[source]¶

get_json(response)[source]¶

Helper for getting json out of response. If the response is not json or the json is invalid it returns None

Parameters:: response (Response) – Response from the API
Returns:: json response
Return type:: dict

get_osf_from_data_app_link(link)[source]¶

Get OSF download link for a data-app drive link

Parameters:: link (str)

get_session_with_redirect(token_provider)[source]¶

get_url_from_share_link(link)[source]¶

Parameters:: link (str)

load_tokens()[source]¶

post(url, *, data, token_provider)[source]¶

save_tokens(keycloak_url, realm_name, client_id, base_url, token)[source]¶