point_viz.h

Functions

void ouster::viz::add_default_controls(viz::PointViz &viz, std::mutex *mx = nullptr)

Add default keyboard and mouse bindings to a visualizer instance

Controls will modify the camera from the thread that calls run() or run_once(), which will require synchronization when using multiple threads.

Parameters

• viz – [in] the visualizer instance

• mx – [in] mutex to lock while modifying camera

Classes

class ouster::viz::PointViz

A basic visualizer for sensor data.

Displays a set of point clouds, images, cuboids, and text labels with a few options for coloring and handling input.

All operations are thread safe when running rendering (run() or run_once()) in a separate thread. This is the intended way to use the visualizer library when a nontrivial amount of processing needs to run concurrently with rendering (e.g. when streaming data from a running sensor).

Public Functions

PointViz(const std::string &name, bool fix_aspect = false, int window_width = default_window_width, int window_height = default_window_height)

Creates a window and initializes the rendering context

Todo:

document me

Todo:

document me

Todo:

document me

Parameters

• name – [in] name of the visualizer, shown in the title bar

• fix_aspect – [in]

• window_width – [in]

• window_height – [in]

~PointViz()

Tears down the rendering context and closes the viz window

void run()

Main drawing loop, keeps drawing things until running(false)

Should be called from the main thread for macos compatibility

void run_once()

Run one iteration of the main loop for rendering and input handling

Should be called from the main thread for macos compatibility

bool running()

Check if the run() has been signaled to exit

Returns

true if the run() loop is currently executing

void running(bool state)

Set the running flag. Will signal run() to exit

Parameters

state – [in] new value of the flag

void visible(bool state)

Show or hide the visualizer window

Parameters

state – [in] true to show

bool update()

Update visualization state

Send state updates to be rendered on the next frame

Returns

whether state was successfully sent. If not, will be sent on next call to update(). This can happen if update() is called more frequently than the frame rate.

void push_key_handler(std::function<bool(const WindowCtx&, int, int)> &&f)

Add a callback for handling keyboard input

Parameters

f – [in] the callback. The second argument is the ascii value of the key pressed. Third argument is a bitmask of the modifier keys

void push_mouse_button_handler(std::function<bool(const WindowCtx&, int, int)> &&f)

Add a callback for handling mouse button input

Todo:

document me

Parameters

f – [in]

void push_scroll_handler(std::function<bool(const WindowCtx&, double, double)> &&f)

Add a callback for handling mouse scrolling input

Todo:

document me

Parameters

f – [in]

void push_mouse_pos_handler(std::function<bool(const WindowCtx&, double, double)> &&f)

Add a callback for handling mouse movement

Todo:

document me

Parameters

f – [in]

void push_frame_buffer_handler(std::function<bool(const std::vector<uint8_t>&, int, int)> &&f)

Add a callback for processing every new draw frame buffer.

NOTE: Any processing in the callback slows the renderer update loop dramatically. Primary use to store frame buffer images to disk for further processing.

Parameters

f – [in] function callback of a form f(fb_data, fb_width, fb_height)

void pop_key_handler()

Remove the last added callback for handling keyboard input

void pop_mouse_button_handler()

Remove the last added callback for handling keyboard input

void pop_scroll_handler()

Remove the last added callback for handling keyboard input

void pop_mouse_pos_handler()

Remove the last added callback for handling keyboard input

void pop_frame_buffer_handler()

Remove the last added callback for handling keyboard input

Camera &camera()

Get a reference to the camera controls

Todo:

document me

Returns

TargetDisplay &target_display()

Get a reference to the target display controls

Todo:

document me

Returns

void add(const std::shared_ptr<Cloud> &cloud)

Add an object to the scene

Todo:

document me

Parameters

cloud – [in]

void add(const std::shared_ptr<Image> &image)

Add an object to the scene

Todo:

document me

Parameters

image – [in]

void add(const std::shared_ptr<Cuboid> &cuboid)

Add an object to the scene

Todo:

document me

Parameters

cuboid – [in]

void add(const std::shared_ptr<Label> &label)

Add an object to the scene

Todo:

document me

Parameters

label – [in]

bool remove(const std::shared_ptr<Cloud> &cloud)

Remove an object from the scene

Todo:

document me

Parameters

cloud – [in]

bool remove(const std::shared_ptr<Image> &image)

Remove an object from the scene

Todo:

document me

Parameters

image – [in]

bool remove(const std::shared_ptr<Cuboid> &cuboid)

Remove an object from the scene

Todo:

document me

Parameters

cuboid – [in]

bool remove(const std::shared_ptr<Label> &label)

Remove an object from the scene

Todo:

document me

Parameters

label – [in]

int viewport_width() const

Get a viewport width in pixels.

Returns

viewport width reported by glfw

int viewport_height() const

Get a viewport height in pixels.

Returns

viewport height reported by glfw

int window_width() const

Get a window width in screen coordinates.

NOTE: this value maybe different from the viewport size on retina displays

Returns

window width reported by glfw

int window_height() const

Get a window height in screen coordinates.

Note

this value maybe different from the viewport size on retina displays

Returns

window height reported by glfw

struct Impl

class ouster::viz::Camera

Controls the camera view and projection.

Public Functions

Camera()

Todo:

document me

impl::CameraData matrices(double aspect) const

Calculate camera matrices.

Parameters

aspect – [in] aspect ratio of the viewport

Returns

projection, view matrices and target location.

void reset()

Reset the camera view and fov.

void birds_eye_view()

Set camera view as looking from the top as a bird (Birds Eye View).

void yaw(float degrees)

Orbit the camera left or right about the camera target.

Parameters

degrees – [in] offset to the current yaw angle

void set_yaw(float degrees)

Set yaw in degrees.

Parameters

degrees – [in] yaw angle

float get_yaw() const

Get the yaw in degrees.

Returns

yaw in degrees

void pitch(float degrees)

Pitch the camera up or down.

Parameters

degrees – [in] offset to the current pitch angle

void set_pitch(float degrees)

Set pitch in degrees.

Parameters

degrees – [in] pitch angle

float get_pitch() const

Get the camera pitch in degrees.

Returns

pitch in degrees

void dolly(double amount)

Move the camera towards or away from the target.

Parameters

amount – [in] offset to the current camera distance from the target

void set_dolly(double log_distance)

Set dolly (i.e. log distance) from the target to the camera.

Parameters

log_distance – [in] log of the distance from the target

double get_dolly() const

Get the log distance from the target to the camera.

Returns

log_distance

void dolly_xy(double x, double y)

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

Coordinates are normalized so that 1 is the length of the diagonal of the view plane at the target. This is useful for implementing controls that work intuitively regardless of the camera distance.

Parameters

• x – [in] horizontal offset

• y – [in] vertical offset

void set_view_offset(const vec3d &view_offset)

Set view offset.

Parameters

view_offset – [in] view offset of the camera

vec3d get_view_offset() const

Get view offset.

Returns

view offset of the camera

void set_fov(float degrees)

Set the diagonal field of view.

Parameters

degrees – [in] the diagonal field of view, in degrees

float get_fov() const

Get field of fiew of a camera in degrees

Returns

fov in degrees

void set_orthographic(bool state)

Use an orthographic or perspective projection.

Parameters

state – [in] true for orthographic, false for perspective

bool is_orthographic() const

Get orthographic state.

Returns

true if orthographic, false if perspective

void set_proj_offset(float x, float y)

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

Parameters

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

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

vec2d get_proj_offset() const

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

Returns

(x, y) position of a camera target in the viewport

void set_target(const mat4d &target)

Directly set camera target object pose

Parameters

target – [in] target where camera is looking at

mat4d get_target() const

Get the pose of a camera target.

Returns

target camera pose

class ouster::viz::TargetDisplay

Manages the state of the camera target display.

Public Functions

void enable_rings(bool state)

Enable or disable distance ring display.

Parameters

state – [in] true to display rings

void set_ring_size(int n)

Set the distance between rings.

Parameters

n – [in] space between rings will be 10^n meters

void set_ring_line_width(int line_width)

Set the line width of the rings.

Parameters

line_width – [in] of the rings line

class ouster::viz::Image

Manages the state of an image.

Public Functions

Image()

Todo:

document me

void clear()

Clear dirty flags.

Resets any changes since the last call to PointViz::update()

void set_image(size_t width, size_t height, const float *image_data)

Set the image data.

Parameters

• width – [in] width of the image data in pixels

• height – [in] height of the image data in pixels

• image_data – [in] pointer to an array of width * height elements interpreted as a row-major monochrome image

void set_image_rgb(size_t width, size_t height, const float *image_data_rgb)

Set the image data (RGB).

Parameters

• width – [in] width of the image data in pixels

• height – [in] height of the image data in pixels

• image_data – [in] pointer to an array of width * height elements interpreted as a row-major RGB image

void set_image_rgba(size_t width, size_t height, const float *image_data_rgba)

Set the image data (RGBA).

Parameters

• width – [in] width of the image data in pixels

• height – [in] height of the image data in pixels

• image_data – [in] pointer to an array of width * height elements interpreted as a row-major RGBA image

void set_mask(size_t width, size_t height, const float *mask_data)

Set the RGBA mask.

Not required to be the same resolution as the image data

Parameters

• width – [in] width of the image data in pixels

• height – [in] height of the image data in pixels

• mask_data – [in] pointer to array of 4 * width * height elements interpreted as a row-major rgba image

void set_position(float x_min, float x_max, float y_min, float y_max)

Set the display position of the image.

TODO: this is super weird. 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 – [in]

• x_max – [in]

• y_min – [in]

• y_max – [in]

void set_hshift(float 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

Parameters

hshift – [in] shift in normalized by width coordinates from 0 at the center [-1.0..1.0]

void set_palette(const float *palette, size_t palette_size)

Set the image color palette.

Parameters

• palette – [in] the new palette to use, must have size 3*palette_size

• palette_size – [in] the number of colors in the new palette

void clear_palette()

Removes the image color palette.

class ouster::viz::Cuboid

Manages the state of a single cuboid.

Public Functions

Cuboid(const mat4d &transform, const vec4f &rgba)

Todo:

document me

void clear()

Clear dirty flags.

Resets any changes since the last call to PointViz::update()

void set_transform(const mat4d &pose)

Set the transform defining the cuboid.

Applied to a unit cube centered at the origin.

Todo:

document me

Parameters

pose – [in]

void set_rgba(const vec4f &rgba)

Set the color of the cuboid.

Todo:

document me

Parameters

rgba –

class ouster::viz::Label

Manages the state of a text label.

Public Functions

Label(const std::string &text, const vec3d &position)

Todo:

document me

Label(const std::string &text, float x, float y, bool align_right = false, bool align_top = false)

Todo:

document me

void clear()

Clear dirty flags.

Resets any changes since the last call to PointViz::update()

void dirty()

Set all dirty flags.

Re-sets everything so the object is always redrawn.

void set_text(const std::string &text)

Update label text.

Parameters

text – [in] new text to display

void set_position(const vec3d &position)

Set label position.

Parameters

position – [in] 3d position of the label

void set_position(float x, float y, bool align_right = false, bool align_top = false)

Set position of the 2D label.

Parameters

• x – [in] horizontal position [0, 1]

• y – [in] vertical position [0, 1]

• align_right – [in] interpret position as right of the label

• align_top – [in] interpret position as top of the label

void set_scale(float scale)

Set scaling factor of the label.

Parameters

scale – [in] text scaling factor

void set_rgba(const vec4f &rgba)

Set the color of the label.

Parameters

rgba – [in] color in RGBA format

Structs

struct ouster::viz::WindowCtx

Context for input callbacks.

Public Members

bool lbutton_down = {false}

True if the left mouse button is held.

bool mbutton_down = {false}

True if the middle mouse button is held.

double mouse_x = {0}

Current mouse x position.

double mouse_y = {0}

Current mouse y position.

int viewport_width = {0}

Current viewport width in pixels.

int viewport_height = {0}

Current viewport height in pixels.

int window_width = {0}

Current window width in screen coordinates.

int window_height = {0}

Current window height in screen coordinates.