OCP CAD Viewer for VS Code

OCP CAD Viewer for VS Code is an extension to show CadQuery and build123d objects in VS Code via the three-cad-viewer viewer component.

A typical session is just a few lines of Python:

# build123d
from build123d import Box
from ocp_vscode import show

show(Box(1, 2, 3))

# CadQuery
import cadquery as cq
from ocp_vscode import show

show(cq.Workplane().box(1, 2, 3))

Installation

Prerequisites

• Microsoft VS Code, 1.85.0 or newer
• The Python extension installed in VS Code
• Necessary tools: python and pip or uv pip/uv add available in the Python environment that will be used for CAD development.

Notes:

• To use OCP CAD Viewer, start VS Code from the commandline in the Python environment you want to use or select the right Python interpreter in VS Code first. OCP CAD Viewer depends on VS Code using the right Python interpreter (i.e. mamba / conda / pyenv / poetry / ... environment).
• For VSCodium, the extension is not available in the VS code market place. You need to download the the vsix file from the release folder and install it manually.

Installation within VS Code

1. Open the VS Code Marketplace, and search and install OCP CAD Viewer 4.0.0.

   Afterwards the OCP viewer is available in the VS Code sidebar:

   

2. Clicking on it shows the OCP CAD Viewer UI with the viewer manager and the library manager:

   

   You have 3 options:

   • Prepare OCP CAD Viewer for working with build123d: Press the Quickstart build123d button.

     This will install OCP, build123d, ipykernel (jupyter_client), ocp_tessellate and ocp_vscode via pip

     

   • Prepare OCP CAD Viewer for working with CadQuery: Press the Quickstart CadQuery button.

     This will install OCP, CadQuery, ipykernel (jupyter_client), ocp_tessellate and ocp_vscode via pip

     

   • Ignore the quick starts and use the "Library Manager" to install the libraries via pip (per default, this can be changed in the VS Code settings). Install the needed library by pressing the down-arrow behind the library name (hover over the library name to see the button) in the "Library Manager" section of the OCP CAD Viewer sidebar. For more details, see here

   Quickstart will also

   • (optionally) install the the Jupyter extension for VS Code from Microsoft
   • start the OCP viewer
   • create a demo file in a temporary folder to quickly see a simple usage example

Notes:

• Do not use the OCP CAD Viewer logo to verify your OCP CAD Viewer settings! The logo overwrites all your settings in VS Code with its own settings to always look the same on each instance. Use a simple own model for checking your configuration

• If you run into issues, see Troubleshooting

Installation via CLI

If you aren't using VS Code, you can install/use this extension via command line

Since this is a python extension, it is recommended to install/activate a virtual environment first, (e.g. uv, venv, poetry, conda, pip, etc)

• uv based virtual environemnts:

  source .venv/bin/activate  # to activate the uv virtual environment
  uv add ocp-vscode
  

• pip for other virtual environments:

  source .venv/bin/activate  # to activate venv virtual environments
  conda / mamba / micromamba activate <env>  # to activate conda like virtual environments
  pip install ocp-vscode
  

Notes:

• The extension is in pypi only pypi, so for conda, mamba or micromamba environments pip or uv pip needs to be used.
• If you want to use the Studio mode with MaterialX support, see PBR Studio

Installation in code-server

This extension is not available on the OpenVSX marketplace used by code-server. If you want to use it in code-server, you need to install it manually on the server running code-server:

1. Go to the releases page
2. Download the latest ocp-cad-viewer-<version>.vsix file, e.g. using wget <url of vsix file>
3. Run code-server --install-extension ocp-cad-viewer-<version>.vsix to install the extension

Usage

Running code with VS Code's "Run" menu

The simplest way to run a Python script with OCP CAD Viewer is via VS Code's built-in Run menu:

• Edit the file as usual. Make sure from ocp_vscode import ... (or import ocp_vscode) is somewhere in the file — this matches the default OcpCadViewer.advanced.autostartTriggers and starts the viewer automatically when the file is opened.
• Use Run > Run Without Debugging (Ctrl-F5 / on macOS ⌃F5) for a plain run, or Run > Start Debugging (F5) to run under the Python debugger with visual debugging enabled (see docs/debug.md).
• Each show(...) call in your script is sent to the running viewer. If more than one viewer is open, show prompts in the terminal to choose which port to send to; call set_port(<port>) explicitly to skip the prompt.

Running code using Jupyter extension

• Start the OCP CAD Viewer by pressing the box-arrow button in the "Viewer Manager" section of the OCP CAD Viewer sidebar (hover over the ocp_vscode entry to see the button).
• Import ocp_vscode and the CAD library by using the paste button behind the library names in the "Library Manager" section
• Use the usual Run menu to run the code

Standalone mode

Standalone mode allows you to use OCP CAD Viewer without VS Code: python -m ocp_vscode. This starts a Flask server reachable at http://127.0.0.1:<port> (default http://127.0.0.1:3939). See docs/standalone.md for details, including the full CLI reference and how to run it in Docker.

Debugging code with visual debugging

After each step, the debugger checks all variables in locals() for being CAD objects and displays them with their variable name. See docs/debug.md for details.

Library Manager

The "Library Manager" in the OCP CAD Viewer sidebar lets you install or upgrade build123d, cadquery, ipykernel and ocp_tessellate from VS Code. See docs/install.md for the default install commands, placeholder substitution, and uv add override.

Extra topics

Getting started

• Quickstart experience on Windows
• Install Libraries
• Best practices

Working with the viewer

• Ports and connecting to a viewer
• Config files (~/.ocpvscode, ~/.ocpvscode_standalone)
• Use Jupyter to execute code
• Standalone mode (use without VS Code)
• Debug code with visual debugging
• Measurement tools
• Object selection tool
• Physical based rendering Studio
• ImageFace — use a 2-D image as a reference plane

Python show* commands

• Use the show command
• Use the show_object command
• Use the push_object and show_objects command
• Use the show_all command
• Use the set_viewer_config command

Python API reference

• Additional Python API (save_screenshot, status, set_port, …)
• Animation
• Color maps
• Enums reference (Camera, Collapse, Render, AnalysisTool, UiTab, Studio*)

VS Code reference

• VS Code Settings reference
• VS Code Commands reference

Examples and snippets

• Download examples for build123d or cadquery
• Use the build123d snippets

Other editors support

• Using OCP CAD Viewer with NeoVim

Help

• Troubleshooting

Development

Testing:

make tests

Changes

4.0.0

Major release — the picking/selection architecture has been rewritten in three-cad-viewer, leading to chages for OCP CAD Viewer:

• New picking system

  • Replace the CPU THREE.Raycaster and the duplicated "exploded" scene graph with GPU id-based picking over a single compact scene graph, highlighting is GPU shader-driven.
  • Hover, selection, measurement and double-click resolve the component under the cursor from an offscreen id buffer, selection behavior is unchanged, with much better scaling to large models.
  • The topology filter (All / Vertex / Edge / Face / Solid) is always available for CAD models, enabling whole-solid hover highlighting without a tool.
  • Renamed the "None" option in object filters to "All".

• New mesh based Measurement

  • Add a built-in TypeScript mesh-based measurement backend so the measure tools (distance / properties) work without the external Python (ocp_vscode) backend
  • Computes real values (area, length, volume, bounding box, min/center distance, angle) from the tessellated mesh; shape_type/geom_type are exact (taken from the tessellation face_types/edge_types).
  • The distance measurement's mesh minimum-distance search uses a BVH (AABB-tree branch-and-bound) — exact and sub-quadratic, so measuring between large or finely-tessellated faces (spheres, helices/springs) do not freeze the viewer for many seconds (resolved in milliseconds).

• New status bar

  • Always-on hover preselection for CAD models: hovering a component (no active tool required) highlights it and shows a status line with its fixed attributes — geom type, mesh-estimated length/area/volume, and for circular edges (holes, fillets) the center and radius (r ≈ …, c ≈ …); edge start/end are the exact BRep vertices. Not enabled for GDS (dense, stacked layout data).

• Other Features

  • Hide-undo: cmd/meta-double-click on an object hides it, and now cmd/meta-double-click on empty space brings back the most recently hidden object (one per click, in reverse order). This restores hidden objects without the tree — handy in Studio mode, where the tree isn't shown.

• Performance

  • Initial load time on large models roughly halved (zebra-stripe initialization is deferred to first use, and the default clip-plane setup is batched into a single update instead of re-rendering once per setter).
  • Clipping section caps now scale to large assemblies. The per-solid stencil and cap meshes are culled each frame to the on-screen, large-enough solids (sub-pixel solids are skipped and the total is bounded by a budget, largest-first), and are drawn only while the Clip tab is active.

• part_local, sketch_local, and line_Local support for build123d

  • build123d now also supports part_local and line_local. The viewer can show the local versions llike it did in the past with sketch_local. As a consequence show_sketch_local (now deprecated) is renamed to show_locals

• Fixes

  • Breaking: Shortcuts (keymap) weren't unique and consistent. Changed so that default action shortcuts:
    • the lowercase keys drive the always-on topology filter (a = All, v/e/f, s = Solid)
    • Copy-IDs (select tool) S → I,
    • Studio s → S,
    • Axes a → A
    • Axes-at-origin A → 0.
    • Button and tab tooltips reflect the configured keymap.
  • Rendering a new model now disables any active tool as the first step of render(); the incremental addPart/updatePart/removePart API keeps the tool.
  • Clipping section caps no longer leave stray "ghost" caps floating in empty space for non-watertight solids or for planes parked open — a cap is drawn only for a plane that actually cuts the solid.
  • Clip-plane sliders now use a finer, model-size-scaled step (e.g. 0.1 instead of 1 on a ~200-unit model), for more precise sectioning.
  • Studio: hiding a component with ⌘/double-click no longer leaves "ghost" edges behind after switching back to CAD.
  • The Clip and Studio tabs hide the measure and select tools (explode and z-scale remain available).
  • Clip settings are resolved purely from the options passed to render() — each provided field wins and missing fields fall back to defaults.
  • Fix color handling for builder objects to properly support bp.part.color, bs.sketch.color, and bl.line.color

For the change history see CHANGELOG