polyscope

library2.6.1pypypi✓ verified 87d ago

Polyscope is a Python library that provides an interactive 3D viewer and user interface for visualizing a variety of 3D data types, including point clouds, surface meshes, volumes, and general purpose quantities. It is built on a C++ core for performance and offers an intuitive GUI. The current version is 2.6.1, and it maintains a frequent release cadence, typically with minor versions released every 1-2 months.

web-framework data

pip install polyscope

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · POLYSCOPE

polyscope

web-frameworkpythonv2.6.1

Install

4.2s avg

Import

421ms

Disk

117MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.6.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.337s · 119.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 4.2s · import 0.000s · 111MB

117MB installed

● package 117MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

polyscope

✓ import polyscope as ps

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()

polyscope --version

Debug

Known issues

breakingPolyscope 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.

affects: <2.0.0

gotchaHeadless 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.

affects: <2.4.0

gotchaInput 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.

affects: <2.4.0

gotchaThe 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.

affects: >=2.6.0

gotchaUsers 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.

affects: <2.5.0

Errors

Common errors & fixes

RuntimeError: Polyscope must be initialized before calling this function.

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'

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.

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.

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.

Upgrade

Version history

2.6.1latest on PyPI · released Feb 26, 2026

Audit

Dependencies

gsplatoptionalRequired for experimental Gaussian splat visualization support.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/nmwsharp/polyscope ↗

packagehttps://pypi.org/project/polyscope/ ↗

homepagehttps://polyscope.run ↗

docshttps://polyscope.run ↗