Module `ouster.sdk.viz`

Ouster sensor data visualization tools. Implemented in C++ OpenGL and wrapped with Python bindings.

For additional information please refer to PointViz Tutorial & API Usage.

Core 

class PointViz

add()

Add an object to the scene.

Parameters:: obj – A cloud, label, image or cuboid.

property camera: Get a reference to the camera controls.

property fps: Frames per second, updated every second in the draw() func

pop_frame_buffer_handler(): Remove the last added callback for handling frame buffers data.

push_frame_buffer_handler(): Add a callback for handling every frame buffer draw (super expensive).

push_key_handler(): Add a callback for handling keyboard input.

remove()

Remove an object from the scene.

Parameters:: obj – A cloud, label, image or cuboid.
Returns:: True if the object was in the scene and was removed.

run()

Run the visualizer rendering loop.

Must be called from the main thread. Will return when running(False) is called from another thread or when the visualizer window is closed.

run_once(): Run one iteration of the main loop for rendering and input handling.

running(): Check if the rendering loop is running. Shut down the visualizer and break out of the rendering loop.

property target_display: Get a reference to the target display.

update(): Show updated data in the next rendered frame.

update_on_input(): Will we update on user input. Set update_on_input state.

property viewport_height: Current viewport height in pixels

property viewport_width: Current viewport width in pixels

visible(): Toggle if the PointViz window is visible

property window_height: Current window height in screen coordinates

property window_width: Current window width in screen coordinates

add_default_controls(): Add default keyboard and mouse bindings to a visualizer instance.

class LidarScanViz(meta, viz=None, *, _img_aspect_ratio=0, _ext_modes=None, _ext_palettes=None)[source]

Visualize LidarScan data.

Uses the supplied PointViz instance to easily display the contents of a LidarScan. Sets up key bindings to toggle which channel fields and returns are displayed, and change 2D image and point size.

Parameters:

meta (SensorInfo) – sensor metadata used to interpret scans
viz (Optional[PointViz]) – use an existing PointViz instance instead of creating one

class FlagsMode(value)[source]: An enumeration.

cycle_img_mode(i, *, direction=1)[source]

Change the displayed field of the i’th image.

Return type:: None

cycle_cloud_mode(*, direction=1)[source]

Change the coloring mode of the 3D point cloud.

Return type:: None

cycle_cloud_palette(*, direction=1)[source]

Change the color palette of the 3D point cloud.

Return type:: None

toggle_cloud(i)[source]

Toggle whether the i’th return is displayed.

Return type:: None

update_point_size(amount)[source]

Change the point size of the 3D cloud.

Return type:: None

update_image_size(amount)[source]

Change the size of the 2D image.

Return type:: None

update_ring_size(amount)[source]

Change distance ring size.

Return type:: None

cicle_ring_line_width()[source]

Change rings line width.

Return type:: None

toggle_osd(state=None)[source]

Show or hide the on-screen display.

Return type:: None

toggle_camera_follow()[source]

Toggle the camera follow mode.

Return type:: None

toggle_scan_axis()[source]

Toggle the helper axis of a scan ON/OFF

Return type:: None

property metadata: SensorInfo: The sensor metadata of the scans.

property scan: LidarScan: The currently displayed scan.

property scan_num: int: The currently displayed scan number

draw(update=True)[source]

Process and draw the latest state to the screen.

Return type:: bool

run()[source]

Run the rendering loop of the visualizer.

See PointViz.run()

Return type:: None

class SimpleViz(arg, *, rate=None, pause_at=-1, on_eof='exit', scans_accum=None, _buflen=50)[source]

Visualize a stream of LidarScans.

Handles controls for playback speed, pausing and stepping.

Parameters:

arg (Union[SensorInfo, LidarScanViz, Any]) – Metadata associated with the scans to be visualized or a LidarScanViz instance to use.
rate (Optional[float]) – Playback rate. One of 0.25, 0.5, 0.75, 1.0, 1.5, 2.0, 3.0 or None for “live” playback (the default).
pause_at (int) – scan number to pause at, default (-1) - no auto pause, to stop after the very first scan use 0

Raises:

ValueError – if the specified rate isn’t one of the options

toggle_pause()[source]

Pause or unpause the visualization.

Return type:: None

seek_relative(n_frames)[source]

Seek forward of backwards in the stream.

Return type:: None

modify_rate(amount)[source]

Switch between preset playback rates.

Return type:: None

toggle_osd(state=None)[source]

Show or hide the on-screen display.

Return type:: None

property scans_per_sec: float: Scans per second processing rate.

run(scans)[source]

Start reading scans and visualizing the stream.

Must be called from the main thread on macOS. Will close the provided scan source before returning.

Parameters:: scans (Iterable[LidarScan]) – A stream of scans to visualize.
Return type:: None
Returns:: When the stream is consumed or the visualizer window is closed.

class ScansAccumulator(metas, *, point_viz=None, accum_max_num=0, accum_min_dist_meters=0, accum_min_dist_num=1, map_enabled=False, map_select_ratio=0.001, map_max_points=1500000, map_overflow_from_start=False)[source]

Accumulate scans, track poses and overall map view

Could be used with or without PointViz immediate visualization. With PointViz it acts similarly to LidarScanViz and can be as a first argument passed to SimpleViz (or as a separate scans_accum parameter)

Every new scan (LidarScan or Tuple[Optional[LidarScan]]) is passed through update(scan, num).

Available visualization depends on whether poses are present or not and params set on init. View modes are combination of:

TRACK - scan poses (i.e. trajectories) of every scan “seen” (poses required)

ACCUM - set of accumulated scans (key frames) picked according to params

MAP - overall map with select ratio of random points from every scan passed through update()

Parameters:

metas (Union[SensorInfo, List[SensorInfo]]) – one or many sensor metadatas for scans that will be passed on update
point_viz (Optional[PointViz]) –
if present then the resulting ScansAccumulator could be used similar to LidarScanViz as first argument in SimpleViz or with scans_accum parameter.

Without point_viz ScansAccumulator is intended to be used as a separate standalone component to accumulate points and get the resulting point clouds/tracks with color keys back.

It’s possible to add PointViz later using the function set_point_viz(point_viz)
accum_max_num (int) – aka, --accum-num, the maximum number of accumulated (ACCUM) scans to keep
accum_min_dist_meters (float) – aka, --accum-every-m, the minimum distance between accumulated (ACCUM) key frames
accum_min_dist_num (int) – aka, --accum-every, the minimum distance in scans between accumulated (ACCUM) key frames
map_enabled (bool) – enable overall map accumulation (MAP) (--map)
map_select_ratio (float) – percent of points to select from the scans to the overall map (MAP), default 0.001
map_max_points (int) – maximum number of points to keep in overall map (MAP)
map_overflow_from_start (bool) – if True, on map overflow continue writing points from the beginning (as in ring buffer), if False, overwrite points randomly in the existing map

set_point_viz(point_viz)[source]: Initialize point viz and cloud components.

update_point_size(amount)[source]

Change the point size of the MAP/ACCUM point cloud.

Return type:: bool

toggle_mode_accum(state=None)[source]: Toggle ACCUM view

toggle_mode_track(state=None)[source]: Toggle TRACK view

toggle_mode_map(state=None)[source]: Toggle MAP view

cycle_cloud_mode(*, direction=1)[source]

Change the coloring mode of the point cloud for MAP/ACCUM clouds

Return type:: bool

cycle_cloud_palette(*, direction=1)[source]

Change the color palette of the point cloud for MAP/ACCUM clouds

Return type:: bool

toggle_osd(state=None)[source]

Show or hide the on-screen display.

Return type:: bool

osd_text()[source]

Prepare OSD text for use in draw_osd or elsewhere.

Return type:: str

update(scan, scan_num=None)[source]: Register the new scan and update the states of TRACK, ACCUM and MAP

property key_frames_num: int: Current number of accumulated ACCUM key frames

property key_frames_idxs: Iterable[int]: Indices of accumulated frames (ACCUM) in ScanRecords list

property track_visible: bool: Whether TRACK is visible

property accum_visible: bool: Whether accumulated key frames (ACCUM) is visible

property map_visible: bool: Whether overall map (MAP) is visible

property active_cloud_palette: CloudPaletteItem: Cloud palette used for ACCUM/MAP clouds

property active_cloud_mode: CloudMode: Current color mode of point ACCUM/MAP point clouds

property metadata: List[SensorInfo]: Metadatas for the displayed sensors.

draw(update=True)[source]: Process and draw the latest state to the screen.

viz.spezia_palette = spezia colors

viz.calref_palette = calref colors

Visual Primitives 

`Cloud` for 3D Point Cloud 

class Cloud

Manages the state of a point cloud.

Each point cloud consists of n points with w poses. The ith point will be transformed by the (i % w)th pose. For example for 2048 x 64 Ouster lidar point cloud, we may have w = 2048 poses and n = 2048 * 64 = 131072 points.

We also keep track of a per-cloud pose to efficiently transform the whole point cloud without having to update all ~2048 poses.

def __init__(self, n_points: int, extrinsics: np.ndarray) -> None:

Unstructured point cloud for visualization.

Call set_xyz() to update

Parameters:

n – number of points
extrinsics – sensor extrinsic calibration. 4x4 column-major homogeneous transformation matrix

def __init__(self, si: SensorInfo) -> None:

Structured point cloud for visualization.

Call set_range() to update

Parameters:: info – sensor metadata

property cols: Number of columns in a cloud (1 if point cloud is unstructured

set_column_poses()

Set scan poses (per every column).

Parameters:: column_poses – array of poses (Wx4x4) per every column.

set_key()

Set the key values, used for colouring.

Number of elements defines the type of Cloud coloration: - num elements == cloud.get_size(): MONO with palette - 3 dimensions with the last dimesion: 3 - RGB, 4 - RGBA,

no palette used

Parameters:: key – array of at least as many elements as there are points, preferably normalized between 0 and 1

set_key_alpha()

Set the key alpha values, color is not changed.

The set alpha will be applied for these forms of CLoud.set_key() calls:

MONO (palette used to pick a color)
RGB

However when set_key() is used with RGBA the previously set alpha with set_key_alpha() will be overwritten with the new values.

Parameters:: key_alpha – array of at least as many elements as there are points, normalized between 0 and 1

set_mask()

Set the RGBA mask values, used as an overlay on top of the key.

Parameters:: mask – array of at least 4x as many elements as there are points, preferably normalized between 0 and 1

set_palette()

Set the point cloud color palette.

Parameters:: palette – the new palette to use, must have size 3*palette_size

set_point_size()

Set point size.

Parameters:: size – point size

set_pose()

Set the ith point cloud pose.

Parameters:: pose – 4x4 column-major homogeneous transformation matrix

set_range()

Set the range values.

Parameters:: range – array of at least as many elements as there are points, representing the range of the points

set_xyz()

Set the XYZ values.

Parameters:: xyz (array of np.float32. Pybind should also cast other numpy types (but we haven't tested thoroughly)) – array of exactly 3n where n is the number of points, so that the xyz position of the ith point is i, i+n , i+2n

property size: Number of points in a cloud

`Image` for 2D image 

class Image

Manages the state of an image.

clear_palette(): Removes the image palette and use keys as grey color in MONO

set_hshift()

Set horizontal shift in normalized viewport screen width coordinate.

This may be used to “snap” images to the left/right screen edges.

Some example values:: 0 - default, image is centered horizontally on the screen -0.5 - image moved to the left for the 1/4 of a horizontal viewport -1 - image moved to the left for the 1/2 of a horizontal viewport +1 - image moved to the right for the 1/2 of a horizontal viewport +0.5 - image moved to the right for the 1/4 of a horizontal viewport

set_image()

Set the image data, MONO or RGB/RGBA depending on dimensions.

Color palette is applied for MONO mode if set_palette() was used to set the palette, otherwise MONO mode makes the monochrome image.

Parameters:: image – 2D array of floats for a monochrome image or 3D array with RGB or RGBA components for color image.

set_mask()

Set the RGBA mask.

Parameters:: mask – M x N x 4 array with RGBA mask

set_palette()

Set the image color palette.

Parameters:: palette – the new palette to use, must have size 3*palette_size

set_position()

Set the display position of the image.

Coordinates are {x_min, x_max, y_max, y_min} in sort-of normalized screen coordinates: y is in [-1, 1], and x uses the same scale (i.e. window width is ignored). This is currently just the same method the previous hard-coded ‘image_frac’ logic was using; I believe it was done this way to allow scaling with the window while maintaining the aspect ratio.

Parameters:

x_min – min x
x_max – max x
y_min – min y
y_max – max y

`Cuboid` for 3D enclosure 

class Cuboid

Manages the state of a single cuboid.

Creates cuboid.

Parameters:

pose – 4x4 pose matrix
rgba – 4 value tuple of RGBA color

set_rgba()

Set the color of the cuboid.

Parameters:: rgba – 4 value tuple of RGBA color

set_transform()

Set the transform defining the cuboid.

Applied to a unit cube centered at the origin.

Parameters:: pose – 4x4 pose matrix

`Label` for 2D and 3D text 

class Label

Manages the state of a text label.

def __init__(self, text: str, x: float, y: float, z: float) -> None:

Creates 3D Label.

Parameters:

text – label text
x – label location
y – label location
z – label location

def __init__(self, text: str, x: float, y: float, align_right: bool = ..., align_top: bool = ...) -> None:

Creates 2D Label.

Parameters:

text – label text
x – label 2D location in screen coords [0..1], corresponding to top left corner of label
y – label 2D location in screen coords [0..1], corresponding to top left corner of label
align_right – if True - anchor point of the label is the right side
align_top – if True - anchor point of the label is the top side

set_position()

def set_position(self, x: float, y: float, z: float) -> None:

Set label position. Position correspnods to top left (viewer’s left) of label.

Args:
x,y,z: label position in 3D

def set_position(self, x: float, y: float, align_right: bool = ...) -> None:

Set position of the 2D label.

Args:
x,y: label 2D position in screen coords [0..1] align_right: if True - anchor point of the label is the right side align_top: if True - anchor point of the label is the top side

set_rgba()

Set the color of the label.

Parameters:: rgba – 4 value tuple of RGBA color

set_scale()

Set scaling factor of the label.

Parameters:: scale – text scale factor

set_text()

Update label text.

Parameters:: text – new text to display

`Camera` and `TargetDisplay`

class Camera

Controls the camera view and projection.

dolly(): Move the camera towards or away from the target.

dolly_xy()

Move the camera in the XY plane of the camera view.

Parameters:

x – horizontal offset
y – vertical offset

get_dolly(): Get the dolly (i.e. log distance) of the camera from the target.

get_fov(): Get the diagonal field of view in degrees.

get_pitch(): Get pitch in degrees.

get_proj_offset(): Get the 2d position of a camera target in the viewport.

get_target(): Get a pose of the camera target.

get_view_offset(): Get view offset of a camera

get_yaw(): Get yaw in degrees.

is_orthographic(): Get the orthographic state.

pitch(): Pitch the camera up or down.

reset(): Reset the camera view and fov.

set_dolly(): Set the dolly (i.e. log distance) of the camera from the target.

set_fov(): Set the diagonal field of view.

set_orthographic(): Use an orthographic or perspective projection.

set_pitch(): Set pitch in degrees.

set_proj_offset()

Set the 2d position of camera target in the viewport.

Parameters:

x – horizontal position in in normalized coordinates [-1, 1]
y – vertical position in in normalized coordinates [-1, 1]

set_target()

Set the camera target pose (inverted pose).

Parameters:: pose – 4x4 column-major homogeneous transformation matrix

set_view_offset(): Set view offset of a camera

set_yaw(): Set yaw in degrees.

yaw(): Orbit the camera left or right about the camera target.

class TargetDisplay

Manages the state of the camera target display.

enable_rings(): Enable or disable distance ring display.

set_ring_line_width(): Set the line width of the rings.

set_ring_size(): Set the distance between rings.

Events `WindowCtx`

class WindowCtx

Context for input callbacks.

property lbutton_down: True if the left mouse button is held

property mbutton_down: True if the middle mouse button is held

property mouse_x: Current mouse x position

property mouse_y: Current mouse y position

property viewport_height: Current viewport height in pixels

property viewport_width: Current viewport width in pixels

property window_height: Current window height in screen coordinates

property window_width: Current window width in screen coordinates

Viz Utils 

class AxisWithLabel(point_viz, *, pose=array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]), label='', length=1.0, thickness=3, label_scale=None, enabled=True)[source]