{"id":10053,"library":"polyscope","title":"Polyscope 3D Viewer","description":"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.","status":"active","version":"2.6.1","language":"en","source_language":"en","source_url":"https://github.com/nmwsharp/polyscope","tags":["3d-visualization","mesh","point-cloud","gui","scientific-visualization"],"install":[{"cmd":"pip install polyscope","lang":"bash","label":"Install Polyscope"}],"dependencies":[{"reason":"Required for experimental Gaussian splat visualization support.","package":"gsplat","optional":true}],"imports":[{"symbol":"polyscope","correct":"import polyscope as ps"}],"quickstart":{"code":"import polyscope as ps\nimport numpy as np\n\n# Initialize polyscope\nps.init()\n\n# Register a point cloud\npts = np.random.rand(100, 3)\nps.register_point_cloud(\"my_points\", pts, color=[0.3, 0.5, 0.8])\n\n# Register a surface mesh\nV = np.array([[0,0,0.], [1,0,0.], [0,1,0.], [1,1,0.]])\nF = np.array([[0,1,2], [1,3,2]])\nps.register_surface_mesh(\"my_mesh\", V, F, color=[0.8, 0.5, 0.3])\n\n# Show the gui and keep it open\nps.show()","lang":"python","description":"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."},"warnings":[{"fix":"Consult the official documentation and release notes for v2.0.0 to identify specific API changes and update your code accordingly.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.4.0"},{"fix":"No fix needed, this is a behavior change. Users will need to adapt to the new default panning interaction.","message":"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.","severity":"gotcha","affected_versions":">=2.6.0"},{"fix":"Upgrade to Polyscope v2.5.0 or newer for improved UI scaling and text clarity on high-DPI monitors.","message":"Users with high-DPI displays might have experienced blurry text or incorrect UI scaling in versions prior to v2.5.0.","severity":"gotcha","affected_versions":"<2.5.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Call `ps.init()` at the beginning of your script, typically after imports and before any other Polyscope-specific functions are used.","cause":"The `ps.init()` function was not called before attempting to register data or interact with the Polyscope backend.","error":"RuntimeError: Polyscope must be initialized before calling this function."},{"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.","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).","error":"ImportError: cannot import name 'polyscope_bindings' from 'polyscope'"},{"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()`.","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.","error":"No Polyscope window appears, or the window immediately closes after running the script."},{"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.","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.","error":"Polyscope encountered a fatal error: Input data contains NaN or Inf values."}]}