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.

pop_key_handler(): Remove the last added callback for handling keyboard input.

pop_mouse_button_handler(): Remove the last added callback for mouse button events.

pop_mouse_pos_handler(): Remove the last added callback for mouse position events. Remove the last added callback for window resize events.

pop_scroll_handler(): Remove the last added callback for mouse scroll events.

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

push_frame_buffer_resize_handler(): Add a callback for handling window resize events.

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

push_mouse_button_handler(): Add a callback for handling mouse button events.

push_mouse_pos_handler(): Add a callback for handling mouse position events.

push_scroll_handler(): Add a callback for handling mouse scroll events.

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.

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(metas, point_viz=None, accumulators_config=None, *, _img_aspect_ratio=0, _ext_modes=None, _ext_palettes=None)[source]

Multi LidarScan clouds visualizer

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:

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

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

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

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

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

property osd_state: OsdState: Returns the state of the on screen display.

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

toggle_sensor(sensor_index)[source]

Toggle whether the i’th sensor data 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 and position image labels.

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 scan: List[LidarScan | None]: The currently displayed scan.

property scan_num: int: The currently displayed scan number

update(scans, scan_num=None)[source]

Update the LidarScanViz state with the provided scans.

Return type:: None

draw(update=True)[source]

Process and draw the latest state to the screen.

Return type:: None

run()[source]

Run the rendering loop of the visualizer.

See PointViz.run()

Return type:: None

class SimpleViz(metadata, *, rate=None, pause_at=-1, on_eof='exit', 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, _override_pointviz=None, _override_lidarscanviz=None, _buflen=50)[source]

Visualize a stream of LidarScans.

Handles controls for playback speed, pausing and stepping.

Parameters:

arg – 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.

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

image_pixel_to_window_coordinates(): Returns the window pixel (x, y) given an image (row, col) pixel.

pixel_size(): Returns the pixel size (w, h) in window pixels.

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

window_coordinates_to_image_pixel(): Returns the image pixel as a (row, col) tuple given window coordinates, or None if the given window coordinate is not within the image.

`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.

aspect_ratio(): Return the aspect ratio of the viewport.

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

normalized_coordinates(): Return 2d normalized viewport coordinates given window coordinates.

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