Polyscope 3D Viewer

Common errors

• RuntimeError: Polyscope must be initialized before calling this function.

  cause The `ps.init()` function was not called before attempting to register data or interact with the Polyscope backend.
  fix Call `ps.init()` at the beginning of your script, typically after imports and before any other Polyscope-specific functions are used.

• ImportError: cannot import name 'polyscope_bindings' from 'polyscope'

  cause This usually indicates that the underlying C++ library or its Python bindings failed to install or link correctly, often due to platform-specific build issues or missing system dependencies (e.g., C++ compiler, CMake).
  fix Ensure your environment meets the build requirements if installing from source. For pre-built wheels, try `pip install polyscope --no-cache-dir` to force a fresh install. Check GitHub issues for specific platform solutions if the problem persists.

• No Polyscope window appears, or the window immediately closes after running the script.

  cause The `ps.show()` function, which enters the main event loop and displays the GUI, was not called, or the script exited before `ps.show()` could keep the window open.
  fix Ensure `ps.show()` is called at the very end of your script to keep the GUI open. For advanced use cases or integration in existing loops, consider `ps.frame_tick()` instead of `ps.show()`.

• Polyscope encountered a fatal error: Input data contains NaN or Inf values.

  cause One or more NumPy arrays passed to Polyscope (e.g., for vertices, normals, or scalar quantities) contain Not-a-Number (NaN) or infinity (Inf) values.
  fix Inspect and sanitize your input data. Use `numpy.nan_to_num()` or similar methods to replace `NaN`/`Inf` values with zeros or other valid numbers before passing arrays to Polyscope.

Warnings

• breaking Polyscope v2.0.0 introduced significant API changes and a large accumulation of features, which may require code adjustments for users upgrading from pre-2.0.0 versions.
  Fix: Consult the official documentation and release notes for v2.0.0 to identify specific API changes and update your code accordingly.
• gotcha Headless rendering (without a display server) using Polyscope, especially on Linux, may require specific setup (e.g., EGL backend) and was experimental before v2.4.0. It may not work out-of-the-box.
  Fix: Ensure you are using Polyscope v2.4.0 or newer for improved headless rendering support. Refer to Polyscope documentation for platform-specific EGL or headless configuration instructions.
• gotcha Input data containing `NaN` (Not-a-Number) or `Inf` (infinity) values can lead to crashes or unexpected visual behavior. Polyscope v2.4.0 introduced checks and warnings for such data.
  Fix: Sanitize all input arrays (e.g., vertices, normals, scalar quantities) to ensure they do not contain `NaN` or `Inf` values using functions like `numpy.nan_to_num()` before passing them to Polyscope.
• gotcha The default camera panning behavior changed in v2.6.0. The turntable center now moves as you pan the camera, which might alter muscle memory for long-time users.
  Fix: No fix needed, this is a behavior change. Users will need to adapt to the new default panning interaction.
• gotcha Users with high-DPI displays might have experienced blurry text or incorrect UI scaling in versions prior to v2.5.0.
  Fix: Upgrade to Polyscope v2.5.0 or newer for improved UI scaling and text clarity on high-DPI monitors.

Install

• pip install polyscope Install Polyscope

Imports

• polyscope

  import polyscope as ps

Quickstart

This quickstart initializes the Polyscope viewer, registers a simple random point cloud and a basic surface mesh with distinct colors, then displays the interactive GUI.

import polyscope as ps
import numpy as np

# Initialize polyscope
ps.init()

# Register a point cloud
pts = np.random.rand(100, 3)
ps.register_point_cloud("my_points", pts, color=[0.3, 0.5, 0.8])

# Register a surface mesh
V = np.array([[0,0,0.], [1,0,0.], [0,1,0.], [1,1,0.]])
F = np.array([[0,1,2], [1,3,2]])
ps.register_surface_mesh("my_mesh", V, F, color=[0.8, 0.5, 0.3])

# Show the gui and keep it open
ps.show()