Skip to content

Controlling the Viewer#

In The Basics, you already learned how to open a new octarine.Viewer and add a simple mesh, and Managing Objects showed you how to inspect and access objects on the viewer.

Here we will demonstrate various ways to programmatically control the viewer.

Closing the viewer#

Use octarine.Viewer.close() to close the viewer:

>>> import octarine as oc
>>> v = oc.Viewer()
>>> v.close()

Adjust size#

Use octarine.Viewer.resize() to adjust the size of the viewer:

>>> v = oc.Viewer()
>>> v.resize((1000, 1000))

Camera#

Use octarine.Viewer.center_camera() to center the camera onto objects in the scene:

>>> v = oc.Viewer()
>>> v.center_camera()

Use octarine.Viewer.set_view() to set the camera view:

>>> v = oc.Viewer()
>>> v.set_view('XY')  # set view to frontal

Found a nice view? You can save the camera state and re-apply later to get the exact same view again:

>>> state = v.get_view()  # get the current view
>>> v.set_view(state)  # re-apply the view

Colors#

Use octarine.Viewer.colorize() to randomize colors:

>>> v = oc.Viewer()
>>> v.colorize(palette='seaborn:tab10')

Use octarine.Viewer.set_colors() to set colors for given objects:

>>> v = oc.Viewer()
>>> v.add(cube, name='cube')
>>> v.set_colors('w')  # set color for all objects
>>> v.set_colors({'cube': 'r'})  # set colors for individual objects

Use octarine.Viewer.set_bgcolor() to change the background color:

>>> v = oc.Viewer()
>>> v.set_bgcolor("white")

Hotkeys#

While the viewer or widget is active you can use a set of hotkeys to control the viewer:

Hotkey Description
1 Set frontal (XY) view
2 Set dorsal (XZ) view
3 Set lateral (YZ) view
f Show/hide frames per second
c Show/hide control panel (requires PySide6)

You can bind custom keys using the octarine.Viewer.bind_key() method:

>>> v = oc.Viewer()
>>> # Bind `x` key to clearing the viewer
>>> v.bind_key(key="x", func=v.clear)

Overlay message#

Need to communicate with the user? Try the octarine.Viewer.show_message():

>>> v = oc.Viewer()
>>> v.show_message("Hi User!",
...                duration=2,  # fade out after 2s
...                position='center')

user message

GUI Controls#

Shell/IPython#

Octarine GUI controls when run from the shell currently require PySide6 to be installed and you may have to use %gui qt6 when inside IPython.

To activate them you can either press the c hotkey or:

>>> v = oc.Viewer()
>>> v.show_controls()
shell controls

Jupyter#

For GUI controls in Jupyter/lab you won't need any additional dependencies.

To activate them you can either press the c hotkey or:

>>> # Show viewer widget with `toolbar=True`
>>> v = oc.Viewer()
>>> v.show(toolbar=True)

>>> #... or do this afterwards
>>> v.show_controls()
jupyter toolbar

What next?#