Skip to content

FAQ, Tips, and Tricks

Saving and restoring camera poses

Use look_at() and other functions to manually specify the viewing camera pose.

Or, you can interactively position the camera in the scene, copy it to your clipboard as a json string with ctrl-c, then restore it from the clipboard with ctrl-v. These strings can also be saved and restored programmatically.

Centering the view on an area of interest

See camera controls. You can use ctrl+shift+click (cmd+shift+click on macOS) to orbit the view about a point of interest, as well as zooming in relative to that point.

How do I take a screenshot / save an image?

See Screenshots. Call screenshot(), or click the [screenshot] button in the upper-left corner of the UI.

Positioning objects in the scene and reading back results

See Transforms for various options and to set and get per-structure transformations. In the GUI, you can use the [Options] --> [Transform] menu to enable a widget to interactively transform each object within the scene.

Managing large numbers of structures and quantities

Polyscope generally scales just fine with 100s or even 1000s of distinctly named structures in the scene. However, with this many structures, it may become difficult to select what you want in the UI. Polyscope has a few features which can help:

Every structure has controls in its options UI menu under Options --> Structure Selection and Options --> Quantity Selection which can be used to enable/disable all structures and quantities, or isolate to viewing a single structure.

Use Groups to group your structures in to categories which can be enabled/disabled all together. Notice the hide descendants and show details options on groups, which can totally hide structures from the UI while still offering some control via the group.

You can always use the Custom UIs to create your own interface buttons and selectors which programmatically enable or disable registered objects or adjust their settings.

How do I show animated data

There is no explicit built-in functionality for animated or time-series data, but it is easy and common to do it yourself with a per-frame callback function.

How do I create custom UIs with buttons, sliders, text boxes, etc

Polyscope integrates with the excellent Dear ImGui library for UI elements, and comes with its own bindings to use ImGui from Python. See the interactions page for how to use ImGui functions within polyscope, and see the ImGui docs for everything ImGui can do.

How do I set up mouse click interactions and callbacks

See Mouse Interactions. Polyscope follows an immediate-mode philosophy for interactions: rather than registering many callbacks for various IO events, you can test for mouse and keyboard state in your main loop, or in the per-frame callback (which is the only callback), to implement any behavior your would like. ImGui offers many functions for testing mouse/keyboard state, and there are also a few polyscope-specific functions to get information about scene at the location you clicked, such as constructing rays and querying depth.

Rendering figures for papers and presentations

Several settings can be customized to give a more polished appearance. Consider:

Visualizing colors as exact RGB values, without any shading or tonemapping

Normally, colors are shaded and tone-mapped for rendering, which means the colors and colormapped-values you specify are not exactly the colors Polyscope renders to the screen. Use the flat material to circumvent these effects, and ensure that colors are flat-shaded to the screen with exactly the RGB values specified.

How do I run Polyscope remotely in a browser, via a notebook, or on headless server?

See headless rendering.

In short, Polyscope does support headless rendering: it can be used on remote serves with no display attached to render images and videos to files or buffers, by initializing with a special EGL backend. However, Polyscope does not currently support any kind of client-server mode, or execution in the browser from remote machines, etc. It must be executing locally on the machine which you are using it from.

Polyscope does not currently support creating interactive visualizations inline in IPython/Jupyter notebooks when the kernel is executing on a remote server. If the kernel is executing on your local machine, you can use Polyscope, but the windows will be created directly on your desktop system outside of the notebook.