Module ouster.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.

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)

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)

An enumeration.

cycle_img_mode(i, *, direction=1)

Change the displayed field of the i’th image.

Return type

None

cycle_cloud_mode(*, direction=1)

Change the coloring mode of the 3D point cloud.

Return type

None

cycle_cloud_palette(*, direction=1)

Change the color palette of the 3D point cloud.

Return type

None

toggle_cloud(i)

Toggle whether the i’th return is displayed.

Return type

None

update_point_size(amount)

Change the point size of the 3D cloud.

Return type

None

update_image_size(amount)

Change the size of the 2D image.

Return type

None

update_ring_size(amount)

Change distance ring size.

Return type

None

cicle_ring_line_width()

Change rings line width.

Return type

None

toggle_osd(state=None)

Show or hide the on-screen display.

Return type

None

toggle_camera_follow()

Toggle the camera follow mode.

Return type

None

toggle_scan_axis()

Toggle the helper axis of a scan ON/OFF

Return type

None

property metadata: ouster.client._client.SensorInfo

The sensor metadata of the scans.

Return type

SensorInfo

property scan: ouster.client._client.LidarScan

The currently displayed scan.

Return type

LidarScan

property scan_num: int

The currently displayed scan number

Return type

int

draw(update=True)

Process and draw the latest state to the screen.

Return type

bool

run()

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)

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()

Pause or unpause the visualization.

Return type

None

seek_relative(n_frames)

Seek forward of backwards in the stream.

Return type

None

modify_rate(amount)

Switch between preset playback rates.

Return type

None

toggle_osd(state=None)

Show or hide the on-screen display.

Return type

None

property scans_per_sec: float

Scans per second processing rate.

Return type

float

run(scans)

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)

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) (--accum-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)

Initialize point viz and cloud components.

update_point_size(amount)

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

Return type

bool

toggle_mode_accum(state=None)

Toggle ACCUM view

toggle_mode_track(state=None)

Toggle TRACK view

toggle_mode_map(state=None)

Toggle MAP view

cycle_cloud_mode(*, direction=1)

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

Return type

bool

cycle_cloud_palette(*, direction=1)

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

Return type

bool

toggle_osd(state=None)

Show or hide the on-screen display.

Return type

bool

osd_text()

Prepare OSD text for use in draw_osd or elsewhere.

Return type

str

update(scan, scan_num=None)

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

Return type

int

property key_frames_idxs: Iterable[int]

Indices of accumulated frames (ACCUM) in ScanRecords list

property track_visible: bool

Whether TRACK is visible

Return type

bool

property accum_visible: bool

Whether accumulated key frames (ACCUM) is visible

Return type

bool

property map_visible: bool

Whether overall map (MAP) is visible

Return type

bool

property active_cloud_palette: ouster.viz.view_mode.CloudPaletteItem

Cloud palette used for ACCUM/MAP clouds

Return type

CloudPaletteItem

property active_cloud_mode: ouster.viz.view_mode.CloudMode

Current color mode of point ACCUM/MAP point clouds

Return type

CloudMode

property metadata: List[ouster.client._client.SensorInfo]

Metadatas for the displayed sensors.

Return type

List[SensorInfo]

draw(update=True)

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)

Coordinate axis with a text label.

property enabled: bool

True if label is added to the viz

Return type

bool

enable()

Enable the label and make it added to the viz

Return type

None

disable()

Disable the label and remove it from the viz

Return type

None

toggle()

Toggle the label visibility (i.e. presence in the viz)

Return type

bool

property pose: numpy.ndarray

Label pose, 4x4 matrix

Return type

ndarray

property label: str

Label text, 4x4 matrix

Return type

str

update()

Update label component viz states.

Return type

None