ouster.sdk.viz.core module

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

Sensor data visualization tools.

Visualize lidar data using OpenGL.

class PointViz

Bases: pybind11_object

add()

Add an object to the scene.

Parameters:

obj – A cloud, label, image or cuboid.

property camera

Get a reference to the camera controls.

cursor_visible()

Toggle if the cursor is visible when over this window

property fps

Frames per second, updated every second in the draw() func

get_screenshot()

Gets a screenshot with an explicit width and height. Returns the pixels. Gets a screenshot using a scale factor, which is a multiplier over the window width and height. Returns the pixels.

property notifications_enabled

Enable or disable notifications.

pop_frame_buffer_resize_handler()

Remove the last added callback for window resize events.

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.

pop_scroll_handler()

Remove the last added callback for mouse scroll events.

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.

save_screenshot()

Saves a screenshot using a scale factor, which is a multiplier over the window width and height. Returns the resulting file name. Saves a screenshot with an explicit width and height. Returns the resulting file name.

set_background_color()

Set the background color of the viz.

Parameters:

rgba – 4 value tuple of RGBA color

set_notification()

Set a notification text to be displayed in the top-right corner of the window.

Parameters:

• text – Text to display. Empty string to clear.

• duration – Duration in seconds to display the text (default: 2.0 seconds). 0 means indefinitely.

property target_display

Get a reference to the target display.

toggle_screen_recording()

Toggle screen recording. Returns true if started, false if stopped Toggle screen recording with explicit width and height. Returns true if started, false if stopped.

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

class Cloud

Bases: pybind11_object

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:

• num_points – 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_rgb()

Set the key to RGB values, used for colouring.

Size must be: - 2 dimensions with last dimension 3 for unordered pointclouds - 3 dimensions with last dimension 3 for ordered pointclouds

Parameters:

key – array of RGB colors as many elements as there are points

set_key_rgba()

Set the key to RGBA values, used for colouring.

Size must be: - 2 dimensions with last dimension 4 for unordered pointclouds - 3 dimensions with last dimension 4 for ordered pointclouds

Parameters:

key – array of RGBA colors as many elements as there are points

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

Supports 3 formats: * 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.

• array of (N, 3) where N is the number of points

• array of (H, W, 3) where H*W is the number of points

property size

Number of points in a cloud

class Image

Bases: pybind11_object

Manages the state of an image.

clear_palette()

Removes the image palette and use keys as grey color in MONO

image_pixel_to_viewport_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

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

class Cuboid

Bases: pybind11_object

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

class Label

Bases: pybind11_object

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

property text_height

Get the height of the label text.

class WindowCtx

Bases: pybind11_object

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

class Camera

Bases: pybind11_object

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

Get roll in degrees.

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.

roll()

Roll the camera left or right about the camera target.

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

Set roll in degrees.

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

Bases: pybind11_object

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.

add_default_controls()

Add default keyboard and mouse bindings to a visualizer instance.

class ImageMode(*args, **kwargs)

Bases: FieldViewMode, Protocol

Applies the view mode key to the viz.Image

set_image(img, ls, return_num=0)

Prepares the key data and sets the image key to it.

Return type:

None

class CloudMode(*args, **kwargs)

Bases: FieldViewMode, Protocol

Applies the view mode key to the viz.Cloud

set_cloud_color(cloud, ls, *, return_num=0)

Prepares the key data and sets the cloud key to it.

Return type:

None

class CloudPaletteItem(name, palette)

Bases: object

Palette with a name

name: str

palette: ndarray

class VizExtraMode(func)

Bases: object

Image/Cloud mode factory func

Used to embed viz modes from external plugins.

func: Callable[[], Union[ImageCloudMode, ImageMode, CloudMode]]

create(info=None)

Return type:

Union[ImageCloudMode, ImageMode, CloudMode]

class LidarScanViz(metas, point_viz=None, accumulators_config=None, imu_viz_config=<ouster.sdk.viz.core.ImuVisualizationConfig object>, *, _img_aspect_ratio=0, _buflen=50)

Bases: object

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)

Bases: Enum

An enumeration.

NONE = (<enum.auto object>,)

DEFAULT = (<enum.auto object>,)

HELP = 1

class FlagsMode(value)

Bases: Enum

An enumeration.

NONE = 0

HIGHLIGHT_SECOND = 1

HIGHLIGHT_BLOOM = 2

HIDE_BLOOM = 3

HIGHLIGHT_ZONES = 4

class ImagesLayout(value)

Bases: Enum

An enumeration.

HORIZONTAL = 0

VERTICAL = 1

class CameraMode(value)

Bases: Enum

An enumeration.

FOLLOW = 0

FOLLOW_ROTATION_LOCKED = 1

FIXED = 2

class TrackViewMode(value)

Bases: Enum

An enumeration.

OFF = 0

TRACK_ONLY = 1

TRACK_PLUS_PER_SCAN_TRAJECTORY = 2

class ImageViewMode(value)

Bases: Enum

An enumeration.

ALL = 0

ALL_FLIPPED = 1

ONE = 2

ONE_FLIPPED = 3

imu_plot(scans, imu_viz_config)

mouse_button_handler(ctx, button, event, mods)

Return type:

bool

mouse_pos_handler(ctx, x, y)

Return type:

bool

frame_buffer_resize_handler(ctx)

property metadata: List[SensorInfo]

Metadatas for the displayed sensors.

property osd_state: OsdState

Returns the state of the on screen display.

cycle_osd_scale()

set_view(view)

MAX_SENSOR_TOGGLE_KEYS = 9

select_img_mode(i, mode)

Change the displayed field of the i’th image.

Return type:

bool

cycle_img_mode(i, *, direction=1)

Change the displayed field of the i’th image.

Return type:

None

select_cloud_mode(mode)

Change the coloring mode of the 3D point cloud.

Return type:

bool

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

toggle_sensor(sensor_index)

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

Return type:

None

toggle_flip_images()

Toggle if 2D images should be flipped or not.

Return type:

None

cycle_img_view_mode()

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

cycle_camera_mode(direction=1)

Toggle the camera follow mode.

Return type:

None

update_flags_mode(mode=None)

Return type:

None

toggle_track_view_mode()

Cycle through the track view modes

Return type:

None

toggle_axis_markers()

Toggle the helper axis of a scan ON/OFF

Return type:

None

property scan: LidarScanSet

The currently displayed scan.

property scan_num: int

The currently displayed scan number

update(scans, scan_num=None, last_n_scans=[])

Update the LidarScanViz state with the provided scans.

Return type:

None

draw(update=True)

Process and draw the latest state to the screen.

Return type:

None

run()

Run the rendering loop of the visualizer.

See PointViz.run()

Return type:

None

show_all_imu_plots()

hide_all_imu_plots()

show_all_sensor_labels()

hide_all_sensor_labels()

print_key_bindings()

Return type:

None

toggle_help()

Return type:

None

set_zone_selection_and_render_modes(sel_mode, render_mode)

Return type:

None

cycle_zone_selection_mode()

Return type:

None

cycle_zone_render_mode()

Return type:

None

push_point_viz_handler(viz, arg, handler)

Add a key handler with extra context without keeping it alive.

It’s often useful to add a key callback that calls a method of an object that wraps a PointViz instance. In this case it’s necessary to take some extra care to avoid a reference cycle; holding onto self in the callback passed to native code would cause a memory leak.

Parameters:

• viz (PointViz) – The PointViz instance.

• arg (TypeVar(T)) – The extra context to pass to handler; often self.

• handler (Callable[[TypeVar(T), WindowCtx, int, int], bool]) – Key handler callback taking an extra argument

Return type:

None

ls_show(scans, *, title=None)

[BETA] Display a set of LidarScans in an interactive window.

Parameters:

scans (Union[ScanSource, LidarScan, LidarScanSet, List[LidarScan], List[List[LidarScan]]]) – A set of LidarScans to visualize.

Return type:

None

Optional Args:

title: Title of the visualization window. If not provided,

it will be composed from the sensor serial numbers.

Note

This is a beta feature and its API may change in future releases.