Skip to content

FAQ, Tips, and Tricks

Saving and restoring camera poses

Use lookAt() 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.

How do I take a screenshot / save an image?

See Screenshots. Call polyscope::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 set up mouse click interactions and callbacks

See Mouse Interactions. There are no special callbacks for creating mouse events. Instead, you can implement almost any behavior you want via ImGui’s built-in functions. 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 on a remote or headless server?

It may not not be possible to use Polyscope on a remote headless machine which does not have a physical monitor.

If the machine does have a display attached, there should be no problem. You can run and initialize Polyscope, and even if you are working remotely via script or SSH you can programmatically capture screenshots of the rendered scene.

However, Polyscope will only work if it can create an operating system-level display window, which generally means having a physical monitor attached. Various virtual windowing systems and X-servers exist as a hypothetical workaround, however users have reported limited success with these tools, usually because they use software openGL renderers which do not support the openGL features required by Polyscope.

In implementation terms, this limitation comes from needing to initialize an OpenGL 3.3 core-profile context using GLFW. Currently, GLFW can only create an openGL context when a display is present. If you find a good workaround for Polyscope on headless machines, please share! One day, we hope to implement an alternate EGL backend, which would support headless machines.