ouster.sdk.mapping

Module contents

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

This module provides tools and classes for SLAM, localization, and mapping utilities for Ouster lidar data in Python. It helps building maps, track poses, and process mapping results.

Classes

Functions

AbsolutePointConstraint

class AbsolutePointConstraint(self)
class AbsolutePointConstraint(self, timestamp: numpy.uint64, row: int, col: int, return_idx: int, absolute_position: numpy.ndarray, translation_weight: numpy.ndarray = ...)

Absolute point constraint.

Constrains a single 3D point from a LiDAR frame, identified by its 2D image coordinates (row, col) and return index at a given timestamp, to match a user-defined absolute 3D position in the world frame. The 3D point is computed the same way as in PointToPointConstraint (via RANGE/ RANGE2 and the XYZ LUT), but is compared to a provided global point instead of another frame point.

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp: numpy.uint64, row: int, col: int, return_idx: int, absolute_position: numpy.ndarray, translation_weight: numpy.ndarray = ...) -> None

    Constructor for AbsolutePointConstraint.

    Args:

    timestamp (int): Timestamp of the point’s pose (nanoseconds) row (int): Row index of the point col (int): Column index of the point return_idx (int): Return index of the point (1 or 2) absolute_position: Target world position (x, y, z) translation_weight: Weight for translation constraints (x, y, z)

__annotations__ = {'absolute_position': 'None', 'col': 'None', 'return_idx': 'None', 'row': 'None', 'timestamp': 'None', 'translation_weights': 'None'}
__init__(self) → None
__init__(self, timestamp: numpy.uint64, row: int, col: int, return_idx: int, absolute_position: numpy.ndarray, translation_weight: numpy.ndarray = ...) → None

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp: numpy.uint64, row: int, col: int, return_idx: int, absolute_position: numpy.ndarray, translation_weight: numpy.ndarray = ...) -> None

    Constructor for AbsolutePointConstraint.

    Args:

    timestamp (int): Timestamp of the point’s pose (nanoseconds) row (int): Row index of the point col (int): Column index of the point return_idx (int): Return index of the point (1 or 2) absolute_position (numpy.ndarray): Target world position (x, y, z) translation_weight (numpy.ndarray): Weight for translation constraints (x, y, z)

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
property absolute_position: None

(self) -> numpy.ndarray[dtype=float64, shape=(3), order=’C’]

property col: None

(self) -> int

property return_idx: None

(self) -> int

property row: None

(self) -> int

property timestamp: None

(self) -> int

property translation_weights: None

(self) -> numpy.ndarray[dtype=float64, shape=(3), order=’C’]

AbsolutePoseConstraint

class AbsolutePoseConstraint(self)
class AbsolutePoseConstraint(self, timestamp: numpy.uint64, pose: numpy.ndarray, rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...)

Absolute pose constraint - fixes a pose at a specific timestamp.

This constraint type enforces that the sensor pose at a given timestamp matches a specific target pose.

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp: numpy.uint64, pose: numpy.ndarray, rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...) -> None

    Constructor for AbsolutePoseConstraint.

    Args:

    timestamp (int): Timestamp of the pose to constrain (nanoseconds) pose: The 4x4 transformation matrix (SE3) to constrain to rotation_weight: Scalar weight applied to the quaternion axis-alignment residual translation_weight: Weight for translation constraints (x, y, z)

__annotations__ = {'pose': 'None', 'rotation_weight': 'None', 'timestamp': 'None', 'translation_weights': 'None'}
__init__(self) → None
__init__(self, timestamp: numpy.uint64, pose: numpy.ndarray, rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...) → None

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp: numpy.uint64, pose: numpy.ndarray, rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...) -> None

    Constructor for AbsolutePoseConstraint.

    Args:

    timestamp (int): Timestamp of the pose to constrain (nanoseconds) pose (numpy.ndarray): The 4x4 transformation matrix (SE3) to constrain to rotation_weight (float): Scalar weight applied to the quaternion axis-alignment residual translation_weight (numpy.ndarray): Weight for translation constraints (x, y, z)

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
property pose: None

(self) -> numpy.ndarray[dtype=float64, shape=(4, 4), order=’C’]

property rotation_weight: None

(self) -> float

property timestamp: None

(self) -> int

property translation_weights: None

(self) -> numpy.ndarray[dtype=float64, shape=(3), order=’C’]

ActiveTimeCorrection

class ActiveTimeCorrection(self, infos: collections.abc.Sequence[ouster.sdk.core.SensorInfo])

Class for correcting timestamps of LiDAR frames based on active time correction.

ActiveTimeCorrection constructor. :param infos: List of sensor info objects for each

sensor in the system.

__init__(self, infos: collections.abc.Sequence[ouster.sdk.core.SensorInfo]) → None

ActiveTimeCorrection constructor. :param Sequence[ouster.sdk.core.SensorInfo] infos: List of sensor info objects for each

sensor in the system.

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)

AdaptiveThreshold

class AdaptiveThreshold(self, max_range: float, initial_threshold: float = 2.0, min_motion_threshold: float = 0.01)

KISS-ICP adaptive correspondence threshold estimator.

Tracks the deviation between predicted and registered motion to adapt the maximum correspondence distance used during frame-to-map ICP. Used internally by the LIO SLAM and localization backends.

Create an AdaptiveThreshold instance.

Parameters:

  • max_range (float) – Sensor maximum range in meters, used to scale rotational deviation into a distance-like error term.

  • initial_threshold (float) – Initial correspondence threshold in meters. Defaults to 2.0.

  • min_motion_threshold (float) – Minimum motion magnitude in meters required before a deviation sample is incorporated. Defaults to 0.01.

__annotations__ = {'max_range': 'None', 'min_motion_threshold': 'None'}
__init__(self, max_range: float, initial_threshold: float = 2.0, min_motion_threshold: float = 0.01) → None

Create an AdaptiveThreshold instance.

Parameters:

  • max_range (float) – Sensor maximum range in meters, used to scale rotational deviation into a distance-like error term.

  • initial_threshold (float) – Initial correspondence threshold in meters. Defaults to 2.0.

  • min_motion_threshold (float) – Minimum motion magnitude in meters required before a deviation sample is incorporated. Defaults to 0.01.

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
compute_threshold(self) → float

Return the current adaptive correspondence threshold in meters.

Returns:

Square root of the running mean squared deviation.

Return type:

float

property max_range: None

Sensor maximum range in meters used when converting rotational error to distance.

property min_motion_threshold: None

Minimum motion magnitude in meters before a deviation sample is recorded.

update_model_deviation(self, current_deviation: numpy.ndarray[dtype=float64, shape=(4, 4), order='C', writable=False]) → None

Incorporate a registration correction into the running deviation model.

Parameters:

current_deviation (numpy.ndarray) – (4, 4) homogeneous transform representing the ICP correction for the current frame.

ConstantVelocityDeskewMethod

class ConstantVelocityDeskewMethod(self, infos: collections.abc.Sequence[ouster.sdk.core.SensorInfo])

Deskew method that assumes constant velocity motion between poses.

ConstantVelocityDeskewMethod constructor.

Parameters:

infos (List[SensorInfo]) – List of sensor info objects for each sensor in the system.

__init__(self, infos: collections.abc.Sequence[ouster.sdk.core.SensorInfo]) → None

ConstantVelocityDeskewMethod constructor.

Parameters:

infos (List[SensorInfo]) – List of sensor info objects for each sensor in the system.

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
set_last_pose(self, ts: int, pose: ndarray[dtype=float64, shape=(*, *), order='C']) → None

Set the current pose to use for deskewing.

This method allows setting the current pose that will be used as a reference for deskewing incoming frames. The current pose should represent the sensor’s pose at the time of the most recent frame.

Parameters:

  • ts (int) – The timestamp (nanoseconds) associated with the pose.

  • pose (numpy.ndarray) – A 4x4 transformation matrix representing the current pose.

DeskewMethod

class DeskewMethod(self, infos: collections.abc.Sequence[ouster.sdk.core.SensorInfo])

Base class for all deskewing methods.

This is the abstract base class for all deskewing methods. Use specific derived classes like ConstantVelocityDeskewMethod instead of using this class directly.

ConstantVelocityDeskewMethod constructor.

Parameters:

infos (List[SensorInfo]) – List of sensor info objects for each sensor in the system.

__annotations__ = {}
__init__(self, infos: collections.abc.Sequence[ouster.sdk.core.SensorInfo]) → None

ConstantVelocityDeskewMethod constructor.

Parameters:

infos (List[SensorInfo]) – List of sensor info objects for each sensor in the system.

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
update(self, frames: ouster.sdk.core.FrameSet) → ouster.sdk.core.FrameSet

Update the pose (per_column_global_pose) variable in frame.

Parameters:

frame_set (FrameSet) – a FrameSet.

Returns:

The updated lidar frames with per_column_global_pose set

Return type:

FrameSet

DeskewMethodFactory

class DeskewMethodFactory

Factory class for creating DeskewMethod instances.

__init__(*args, **kwargs)
__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
create = <nanobind.nb_func object>

ICPRegistration

class ICPRegistration(self, max_num_iterations: int = 50, convergence_criterion: float = 0.0001, max_num_threads: int = 0)

Iterative Closest Point (ICP) registration for aligning a point cloud to a voxel map.

This class implements frame-to-map registration used by the LIO SLAM and localization pipelines. Given a LidarFrame (source points) and a pre-built ouster.sdk.core.VoxelHashMap3d or ouster.sdk.core.VoxelHashMapXd map, it iteratively estimates the SE(3) transform that best aligns the LidarFrame to the map using point-to-point correspondences and a Geman-McClure robust kernel.

Create a ICPRegistration instance.

Parameters:

  • max_num_iterations (int) – Maximum number of ICP iterations per call. Defaults to 50.

  • convergence_criterion (float) – Stop when the squared norm of the incremental pose update falls below this threshold. Defaults to 1e-4.

  • max_num_threads (int) – Maximum worker threads. When 0 (default), uses the TBB default concurrency.

__annotations__ = {'convergence_criterion': 'None', 'max_num_iterations': 'None', 'max_num_threads': 'None'}
__init__(self, max_num_iterations: int = 50, convergence_criterion: float = 0.0001, max_num_threads: int = 0) → None

Create a ICPRegistration instance.

Parameters:

  • max_num_iterations (int) – Maximum number of ICP iterations per call. Defaults to 50.

  • convergence_criterion (float) – Stop when the squared norm of the incremental pose update falls below this threshold. Defaults to 1e-4.

  • max_num_threads (int) – Maximum worker threads. When 0 (default), uses the TBB default concurrency.

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
align_points_to_map(self, frame: numpy.ndarray[dtype=float64, shape=(*, 3), order='C', writable=False], voxel_map: ouster.sdk.core.VoxelHashMap3d, max_distance: float, kernel_scale: float) → object
align_points_to_map(self, frame: numpy.ndarray[dtype=float64, shape=(*, 3), order='C', writable=False], voxel_map: ouster.sdk.core.VoxelHashMapXd, max_distance: float, kernel_scale: float) → object

Overloaded function.

  1. align_points_to_map(self, frame: numpy.ndarray[dtype=float64, shape=(*, 3), order='C', writable=False], voxel_map: ouster.sdk.core.VoxelHashMap3d, max_distance: float, kernel_scale: float) -> object

    Align a point cloud to a voxel hash map using ICP.

    The returned 4×4 homogeneous matrix transforms points from the input frame coordinate system into the map coordinate system.

    Args:

    frame (numpy.ndarray): Source points as an (N, 3) array. voxel_map (VoxelHashMap3d): Target map built from prior scans or a saved map. max_distance (float): Maximum correspondence distance in meters. Points

    without a map neighbor within this radius are ignored.

    kernel_scale (float): Scale parameter for the Geman-McClure robust kernel

    used to down-weight outlier correspondences.

    Returns:

    numpy.ndarray: (4, 4) float64 transform matrix. Returns identity when voxel_map is empty.

  2. align_points_to_map(self, frame: numpy.ndarray[dtype=float64, shape=(*, 3), order='C', writable=False], voxel_map: ouster.sdk.core.VoxelHashMapXd, max_distance: float, kernel_scale: float) -> object

    Align a point cloud to a dynamic-size voxel hash map using ICP.

    This overload supports ouster.sdk.core.VoxelHashMapXd maps that store per-point attributes alongside xyz coordinates. Correspondences use the xyz components of the closest map point returned by the voxel map lookup.

    Args:

    frame (numpy.ndarray): Source points as an (N, 3) array. voxel_map (VoxelHashMapXd): Target map with optional per-point attributes. max_distance (float): Maximum correspondence distance in meters. kernel_scale (float): Geman-McClure robust kernel scale parameter.

    Returns:

    numpy.ndarray: (4, 4) float64 transform matrix. Returns identity when voxel_map is empty.

property convergence_criterion: None

Convergence threshold on the squared norm of the incremental pose update.

property max_num_iterations: None

Maximum number of ICP iterations performed by align_points_to_map().

property max_num_threads: None

Maximum number of TBB threads used during correspondence search and linear system assembly.

LIOLocalizationConfig

class LIOLocalizationConfig(self)

Configuration options for the ICP-based Localization engine.

…

__annotations__ = {}
__init__(self) → None

…

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)

LIOSlamConfig

class LIOSlamConfig(self)

Configuration options for the SLAM engine.

This class extends SlamConfig with additional configuration options specific to the SLAM engine.

__annotations__ = {}
__init__(self) → None
__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)

LocalizationConfig

class LocalizationConfig

Configuration options for the Localization engine.

__annotations__ = {'deskew_method': 'None', 'initial_pose': 'None', 'max_iterations': 'None', 'max_range': 'None', 'min_range': 'None', 'voxel_size': 'None'}
__init__(*args, **kwargs)
__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
create = <nanobind.nb_func object>
property deskew_method: None

(self) -> str

property initial_pose: None

(self) -> numpy.ndarray[dtype=float64, shape=(4, 4), order=’C’]

property max_iterations: None

(self) -> int

property max_range: None

(self) -> float

property min_range: None

(self) -> float

property voxel_size: None

(self) -> float

LocalizationEngine

class LocalizationEngine

The Localization engine for processing LiDAR frames and computing body_to_world transforms based on prebuilt pointcloud map.

__init__(*args, **kwargs)
__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
create = <nanobind.nb_func object>

LossFunction

class LossFunction(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)
__nb_enum__ = <capsule object NULL>
HUBER_LOSS = 0
CAUCHY_LOSS = 1
SOFT_L_ONE_LOSS = 2
ARCTAN_LOSS = 3
TRIVIAL_LOSS = 4
from_string = <nanobind.nb_func object>
__repr__()

Return repr(self).

__module__ = 'ouster.sdk.mapping'

PointToPointConstraint

class PointToPointConstraint(self)
class PointToPointConstraint(self, timestamp1: numpy.uint64, row1: int, col1: int, return_idx1: int, timestamp2: numpy.uint64, row2: int, col2: int, return_idx2: int, translation_weight: numpy.ndarray = ...)

Point-to-point constraint - enforces correspondence between points.

This constraint type enforces that specific points in two different lidar frames correspond to the same physical location.

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp1: numpy.uint64, row1: int, col1: int, return_idx1: int, timestamp2: numpy.uint64, row2: int, col2: int, return_idx2: int, translation_weight: numpy.ndarray = ...) -> None

    Constructor for PointToPointConstraint.

    Args:

    timestamp1 (int): Timestamp of the first point’s pose (nanoseconds) row1 (int): Row index of the first point col1 (int): Column index of the first point return_idx1 (int): Return index of the first point (1 or 2) timestamp2 (int): Timestamp of the second point’s pose (nanoseconds) row2 (int): Row index of the second point col2 (int): Column index of the second point return_idx2 (int): Return index of the second point (1 or 2) translation_weight: Weight for translation constraints (x, y, z)

__annotations__ = {'col1': 'None', 'col2': 'None', 'return_idx1': 'None', 'return_idx2': 'None', 'row1': 'None', 'row2': 'None', 'timestamp1': 'None', 'timestamp2': 'None', 'translation_weights': 'None'}
__init__(self) → None
__init__(self, timestamp1: numpy.uint64, row1: int, col1: int, return_idx1: int, timestamp2: numpy.uint64, row2: int, col2: int, return_idx2: int, translation_weight: numpy.ndarray = ...) → None

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp1: numpy.uint64, row1: int, col1: int, return_idx1: int, timestamp2: numpy.uint64, row2: int, col2: int, return_idx2: int, translation_weight: numpy.ndarray = ...) -> None

    Constructor for PointToPointConstraint.

    Args:

    timestamp1 (int): Timestamp of the first point’s pose (nanoseconds) row1 (int): Row index of the first point col1 (int): Column index of the first point return_idx1 (int): Return index of the first point (1 or 2) timestamp2 (int): Timestamp of the second point’s pose (nanoseconds) row2 (int): Row index of the second point col2 (int): Column index of the second point return_idx2 (int): Return index of the second point (1 or 2) translation_weight (numpy.ndarray): Weight for translation constraints (x, y, z)

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
property col1: None

(self) -> int

property col2: None

(self) -> int

property return_idx1: None

(self) -> int

property return_idx2: None

(self) -> int

property row1: None

(self) -> int

property row2: None

(self) -> int

property timestamp1: None

(self) -> int

property timestamp2: None

(self) -> int

property translation_weights: None

(self) -> numpy.ndarray[dtype=float64, shape=(3), order=’C’]

PoseOptimizer

class PoseOptimizer(self, osf_filename: str, options: ouster.sdk.mapping.SolverConfig)
class PoseOptimizer(self, osf_filename: str, config_filename: str)
class PoseOptimizer(self, osf_filename: str, key_frame_distance: float)

A class for optimizing LiDAR sensor trajectories using various geometric constraints.

This class allows adding different types of constraints (pose-to-pose, absolute pose, point-to-point) and solving the trajectory optimization problem to generate a more accurate and consistent sensor path. The optimization aims to minimize the error across all defined constraints while maintaining a physically plausible trajectory.

Overloaded function.

  1. __init__(self, osf_filename: str, options: ouster.sdk.mapping.SolverConfig) -> None

    Initialize PoseOptimizer with an OSF file and solver options.

    Args:

    osf_filename (str): Path to the OSF file containing trajectory data. options (SolverConfig): Solver configuration options. Set options.fix_first_node to True to fix the first node.

  2. __init__(self, osf_filename: str, config_filename: str) -> None

    Initialize PoseOptimizer with an OSF file and solver options loaded from a config file.

    Args:

    osf_filename (str): Path to the OSF file containing trajectory data. config_filename: Path to the configuration file (JSON) containing solver options. Set fix_first_node in the config file to True to fix the first node.

  3. __init__(self, osf_filename: str, key_frame_distance: float) -> None

    Initialize PoseOptimizer with an OSF file and a node gap.

    Args:

    osf_filename (str): Path to the OSF file containing trajectory data. key_frame_distance (float): The gap distance between nodes in the trajectory. To fix the first node, set fix_first_node in the SolverConfig after construction.

__init__(self, osf_filename: str, options: ouster.sdk.mapping.SolverConfig) → None
__init__(self, osf_filename: str, config_filename: str) → None
__init__(self, osf_filename: str, key_frame_distance: float) → None

Overloaded function.

  1. __init__(self, osf_filename: str, options: ouster.sdk.mapping.SolverConfig) -> None

    Initialize PoseOptimizer with an OSF file and solver options.

    Args:

    osf_filename (str): Path to the OSF file containing trajectory data. options (SolverConfig): Solver configuration options. Set options.fix_first_node to True to fix the first node.

  2. __init__(self, osf_filename: str, config_filename: str) -> None

    Initialize PoseOptimizer with an OSF file and solver options loaded from a config file.

    Args:

    osf_filename (str): Path to the OSF file containing trajectory data. config_filename (str): Path to the configuration file (JSON) containing solver options. Set fix_first_node in the config file to True to fix the first node.

  3. __init__(self, osf_filename: str, key_frame_distance: float) -> None

    Initialize PoseOptimizer with an OSF file and a node gap.

    Args:

    osf_filename (str): Path to the OSF file containing trajectory data. key_frame_distance (float): The gap distance between nodes in the trajectory. To fix the first node, set fix_first_node in the SolverConfig after construction.

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
add_absolute_gps_constraints(self, min_space_m: float, translation_weight: numpy.ndarray[dtype=float64, shape=(*), order='C', writable=False]) → int

Generate and add GPS-derived absolute pose constraints.

Reads POSITION_LAT_LONG and POSITION_TIMESTAMP fields from the source OSF and adds AbsolutePoseConstraints roughly every min_space_m meters of travel (estimated from frame poses). XY is constrained in a local WGS84 linearization; Z is copied from the frame pose when available, otherwise unconstrained. The Z weight is set to 0 when the frame pose is identity.

Parameters:

  • min_space_m (float) – Minimum spacing between constraints in meters.

  • translation_weight (numpy.ndarray) – Translation weights (x, y, z).

Returns:

Number of constraints added.

Return type:

int

add_constraint(self, constraint: object) → int

Add a constraint to the pose optimization problem.

This is the new unified API for adding constraints. Use the constraint class constructors to create constraints, then pass them to this method. The constraint must already have a unique ID for later removal. Adding a constraint with a duplicate ID will fail.

Parameters:

constraint (object) – A constraint object created by one of the constraint constructors.

Returns:

The unique constraint ID of the added constraint.

Return type:

int

Raises:

RuntimeError – If the constraint cannot be added.

add_relative_loop_constraints(self, min_distance_m: float, cell_size_m: float = 1.0, icp_score_threshold: float = 0.0) → int

Automatically add relative loop-closure constraints using a spatial hash detector.

Parameters:

  • min_distance_m (float) – Minimum traveled distance (meters) required between successive loop-closure additions.

  • cell_size_m (float) – Spatial hash grid cell size (meters).

  • icp_score_threshold (float) – Minimum auto-ICP confidence in [0, 1] required to keep a detected loop pair. Use 0 to disable filtering.

Returns:

Number of loop-closure constraints added.

Return type:

int

get_constraints(self) → list

Get all constraints currently configured in the pose optimizer.

This method returns a copy of all constraints that are currently configured in the pose optimizer, including both constraints loaded from JSON files during construction and constraints added later via add_constraint().

Returns:

A list of Constraint objects representing all currently configured constraints.

Return type:

List[Constraint]

get_cost_value(self) → float

Get the last solver cost value (final cost from the last solve()).

Returns:

The last recorded solver cost value.

Return type:

float

get_key_frame_distance(self) → float

Return the configured key-frame distance (meters) used when constructing the trajectory.

get_node(self, timestamp: int) → ouster.sdk.mapping.PoseOptimizerNode

Get the node associated with a given timestamp (first-valid-column ts). Returns None if not found.

get_poses(self, type: ouster.sdk.mapping.SamplingMode) → numpy.ndarray[dtype=float64, shape=(*, *, *), order='C']

Retrieve poses as a NumPy array of 4x4 transformation matrices.

Parameters:

type (SamplingMode) – Sampling strategy to use. - SamplingMode.KEY_FRAMES: Returns poses at key-frame timestamps. - SamplingMode.COLUMNS: Returns poses of every LidarFrame’s columns.

Returns:

An (n, 4, 4) array of 4x4 poses.

Return type:

numpy.ndarray[np.float64]

get_sampled_nodes(self, count: int = 100) → list

Retrieve up to count frame nodes evenly sampled across the OSF.

Each node is guaranteed to have a downsampled point cloud; nodes are created on-demand if necessary.

get_timestamps(self, type: ouster.sdk.mapping.SamplingMode) → numpy.ndarray[dtype=uint64, shape=(*), order='C']

Retrieve timestamps corresponding to the selected sampling mode.

Parameters:

type (SamplingMode) – Sampling strategy to use. - SamplingMode.KEY_FRAMES: Returns timestamps at key-frame poses. - SamplingMode.COLUMNS: Returns timestamps of every LidarFrame’s columns.

Returns:

A 1D array of timestamps (nanoseconds).

Return type:

numpy.ndarray[np.uint64]

get_total_iterations(self) → int

Get the cumulative number of solver iterations executed so far.

Returns:

Total iterations across all calls to solve().

Return type:

int

initialize_trajectory_alignment(self) → numpy.ndarray[dtype=float64, shape=(4, 4), order='C']

Initialize trajectory alignment using average absolute constraints.

Computes a weighted average SE(3) transform from the currently loaded absolute pose and absolute point constraints (using their weights in Lie algebra space) and left-multiplies the entire trajectory by that transform as an initial alignment step before optimization.

Returns:

The applied 4x4 alignment transform. Returns

identity if skipped (e.g. no absolute constraints or a negligible delta).

Return type:

np.ndarray

remove_constraint(self, constraint_id: int) → None

Remove a constraint from the pose optimization problem.

Parameters:

constraint_id (int) – The unique ID of the constraint to remove.

Raises:

RuntimeError – If the constraint ID is not found.

save(self, osf_filename: str) → None

Save the optimized trajectory to an OSF file.

This method writes the current state of the optimized trajectory to a new OSF file, preserving all other data from the original file.

Parameters:

osf_filename (str) – The name of the output OSF file.

Returns:

True if the file was successfully saved, False otherwise.

Return type:

bool

save_config(self, config_filename: str) → None

Save the current SolverConfig (including constraints) to a JSON file.

This method serializes the current solver configuration and all constraints to a JSON file. The resulting file can be used later with Pose Optimizer construction to restore the exact same optimization setup.

Parameters:

config_filename (str) – Path where the JSON file should be saved.

Raises:

RuntimeError – If the file cannot be saved.

set_constraints(self, constraints: list) → None

Set all constraints for the pose optimizer.

This method replaces all existing constraints with the provided set of constraints. Any constraints previously loaded from JSON files or added via add_constraint() will be removed and replaced with the new constraint set.

Parameters:

  • constraints (List[Constraint]) – A list of Constraint objects to set as the

  • set. (complete constraint)

Raises:

RuntimeError – If the constraints cannot be set.

set_solver_step_callback(self, callback: collections.abc.Callable) → None

Register a Python callable to be invoked at each solver iteration.

The callable runs on the same thread as solve(), once per ceres iteration. Use this to hook visualization or logging.

Parameters:

callback (Callable[[], None]) – Function to call each iteration.

solve(self, steps: int = 0) → float

Incrementally optimize the trajectory.

This method performs a fixed number of iterations of the optimization algorithm, continuing from the current state. It can be called repeatedly to gradually refine the trajectory. The number of iterations to execute is specified by ‘steps’.

Parameters:

steps (int, optional) – The number of iterations to run for this incremental optimization. Defaults to 0 (uses whatever max_num_iterations was already set).

Returns:

The cost value from the last solve call.

Return type:

float

PoseToPoseConstraint

class PoseToPoseConstraint(self)
class PoseToPoseConstraint(self, timestamp1: numpy.uint64, timestamp2: numpy.uint64, relative_pose: numpy.ndarray = ..., rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...)

Relative pose-to-pose constraint - enforces relative transformation between two poses.

This constraint type enforces a specific relative transformation between two poses at different timestamps.

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp1: numpy.uint64, timestamp2: numpy.uint64, relative_pose: numpy.ndarray = ..., rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...) -> None

    Constructor for PoseToPoseConstraint.

    Args:

    timestamp1 (int): Timestamp of the first pose (nanoseconds) timestamp2 (int): Timestamp of the second pose (nanoseconds) relative_pose: Expected relative transformation from pose1 to pose2.

    Use the identity matrix to let PoseOptimizer auto-estimate it via ICP.

    rotation_weight: Scalar weight applied to the quaternion axis-alignment residual translation_weight: Weight for translation constraints (x, y, z)

__annotations__ = {'relative_pose': 'None', 'rotation_weight': 'None', 'timestamp1': 'None', 'timestamp2': 'None', 'translation_weights': 'None'}
__init__(self) → None
__init__(self, timestamp1: numpy.uint64, timestamp2: numpy.uint64, relative_pose: numpy.ndarray = ..., rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...) → None

Overloaded function.

  1. __init__(self) -> None

Default constructor

  1. __init__(self, timestamp1: numpy.uint64, timestamp2: numpy.uint64, relative_pose: numpy.ndarray = ..., rotation_weight: float = 1.0, translation_weight: numpy.ndarray = ...) -> None

    Constructor for PoseToPoseConstraint.

    Args:

    timestamp1 (int): Timestamp of the first pose (nanoseconds) timestamp2 (int): Timestamp of the second pose (nanoseconds) relative_pose (numpy.ndarray): Expected relative transformation from pose1 to pose2.

    Use the identity matrix to let PoseOptimizer auto-estimate it via ICP.

    rotation_weight (float): Scalar weight applied to the quaternion axis-alignment residual translation_weight (numpy.ndarray): Weight for translation constraints (x, y, z)

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
property relative_pose: None

(self) -> numpy.ndarray[dtype=float64, shape=(4, 4), order=’C’]

property rotation_weight: None

(self) -> float

property timestamp1: None

(self) -> int

property timestamp2: None

(self) -> int

property translation_weights: None

(self) -> numpy.ndarray[dtype=float64, shape=(3), order=’C’]

SamplingMode

class SamplingMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)
__nb_enum__ = <capsule object NULL>
KEY_FRAMES = 0
COLUMNS = 1
__repr__()

Return repr(self).

__module__ = 'ouster.sdk.mapping'

SlamConfig

class SlamConfig

Configuration options for the SLAM engine.

__annotations__ = {'deskew_method': 'None', 'initial_pose': 'None', 'max_iterations': 'None', 'max_range': 'None', 'min_range': 'None', 'voxel_size': 'None'}
__init__(*args, **kwargs)
__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
create = <nanobind.nb_func object>
property deskew_method: None

(self) -> str

property initial_pose: None

(self) -> numpy.ndarray[dtype=float64, shape=(4, 4), order=’C’]

property max_iterations: None

(self) -> int

property max_range: None

(self) -> float

property min_range: None

(self) -> float

property voxel_size: None

(self) -> float

SlamEngine

class SlamEngine

The SLAM engine for processing LiDAR frames and computing body_to_world transforms.

__init__(*args, **kwargs)
__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
create = <nanobind.nb_func object>
get_point_cloud(self) → numpy.ndarray[dtype=float32, shape=(*, 3), order='C']

Get the current point cloud from the SLAM engine.

Returns:

The point cloud generated by the SLAM engine.

Return type:

Nx3

SolverConfig

class SolverConfig(self)

Configuration options for the non-linear optimization solver used in trajectory refinement.

This class encapsulates the configuration options for the solver used in the PoseOptimizer.

key_frame_distance

The distance between nodes in the trajectory (in meters). Controls trajectory discretization.

Type:

float

traj_rotation_weight

The weight for rotational constraints during trajectory optimization. Higher values enforce stronger rotation consistency.

Type:

float

traj_translation_weight

The weight for translational constraints during trajectory optimization. Higher values enforce stronger position consistency.

Type:

float

max_num_iterations

The maximum number of iterations the solver will perform before terminating.

Type:

int

function_tolerance

The tolerance threshold for changes in the cost function. Solver stops when improvements fall below this value.

Type:

float

gradient_tolerance

The tolerance threshold for changes in the gradient. Solver stops when gradient magnitude falls below this value.

Type:

float

parameter_tolerance

The tolerance threshold for changes in parameters. Solver stops when parameter changes fall below this value.

Type:

float

process_printout

Flag to enable or disable detailed printout of the optimization process.

Type:

bool

loss_function

The name of the robust loss function to use (e.g., “HUBER_LOSS”, “CAUCHY_LOSS”, “SOFT_L_ONE_LOSS”, “ARCTAN_LOSS”, “TRIVIAL_LOSS”).

Type:

str

loss_scale

The scaling parameter for the chosen loss function. Higher values make the loss less sensitive to outliers.

Type:

float

fix_first_node

Flag to fix the first node of the trajectory during optimization. Default is False.

Type:

bool

Initialize SolverConfig with default values.

__annotations__ = {'fix_first_node': 'None', 'function_tolerance': 'None', 'gradient_tolerance': 'None', 'key_frame_distance': 'None', 'loss_function': 'None', 'loss_scale': 'None', 'max_num_iterations': 'None', 'parameter_tolerance': 'None', 'process_printout': 'None', 'traj_rotation_weight': 'None', 'traj_translation_weight': 'None'}
__init__(self) → None

Initialize SolverConfig with default values.

__module__ = 'ouster.sdk.mapping'
__new__(**kwargs)
property fix_first_node: None

(self) -> bool

property function_tolerance: None

(self) -> float

property gradient_tolerance: None

(self) -> float

property key_frame_distance: None

(self) -> float

property loss_function: None

(self) -> ouster::sdk::mapping::LossFunction

property loss_scale: None

(self) -> float

property max_num_iterations: None

(self) -> int

property parameter_tolerance: None

(self) -> float

property process_printout: None

(self) -> bool

property traj_rotation_weight: None

(self) -> float

property traj_translation_weight: None

(self) -> float

save_trajectory

save_trajectory(filename: str, timestamps: numpy.ndarray[dtype=uint64, shape=(*), order='C', writable=False], poses: numpy.ndarray[dtype=float64, shape=(*, *, *), order='C', writable=False], file_type: str = 'csv') → None

Submodules

ouster.sdk.mapping.ply_to_png

convert_ply_to_png(ply_files, screenshot_path, is_plot)[source]
get_doll_dist(points)[source]
output_ext_verify(filename)[source]
peak_start_point(ply_files)[source]
scale_rgb_channel(channel)[source]
screenshot_and_save_png(viz, screenshot_path)[source]
Parameters:

screenshot_path (str)