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.

Installation

Prerequisites

• A fairly recent version of Microsoft VS Code, e.g. 1.76.0 or newer
• The Python extension installed in VS Code
• Necessary tools:
  • python and pip available in the Python enviroment that will be used for CAD development
  • The command git needs to be available
  • On a Silicon Apple computer the command mamba needs to be available. You might want to consider using Mambaforge.

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.
• Currently, on a Silicon Mac (ARM CPU), OCP and CadQuery can only be installed via mamba and Python 3.9 or 3.10. Prepare an environment with mamba create -n code_cad python=3.9 or mamba create -n code_cad python=3.10.

Breaking changes from v1.0.0

• IPython and the ipython extensions are not supported any more out of the box. Instead the Microsoft's Jupyter extension with ipykernel is supported. If you have the installation configs in your local VS Code settings.json file, you might want to remove the ipython installation commands.
• For the color maps, CM is replaced by ColorMap (to resolve the conflict with build123d CM)

Installation

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

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

   

2. Clicking on it shows the OCP CAD Viewer UI:

   

   You have 3 options:

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

     This will install OCP, build123d, ipykernel (jupyter_client), ocp_tessellate and ocp_vscode via pip (except for Apple Silicon machines that require mamba)

     

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

     This will install OCP, CadQuery, ipykernel (jupyter_client), ocp_tessellate and ocp_vscode via pip (except for Apple Silicon machines that require mamba)

     

   • Ignore the quick starts and use the "Library Manager" to install the libraries. Doing so, OCP CAD Viewer let's you select whether to use pip, mamba, conda or poetry. Install the needed library by pressing the green down-arrow behind the library name in the "Library Manager" section of the OCP CAD Viewer sidebar. For more details, see here

   The Quickstarts 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

Usage

Running code using Jupyter

• Start the OCP CAD Viewer by pressing the green box-arrow button in the "Viewer Manager" section of the OCP CAD Viewer sidebar
• Import ocp_vscode and the CAD library by using the paste button behing the library names in the "Viewer Manager" section
• Use the usual Run menu to run the code

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. Note:

• Check that OCP:on is visible in the status bar
• It also shows planes, locations and axis, so name your contexts
• It remembers camera position and unselected variables in the tree
• during debugging, show and show_object are disabled. They interfere with the visual debugging

Library Manager

You can also use "Library Manager" in the OCP CAD Viewer sidebar to manage the Python libraries for build123d, cadquery, ipython and ocp_tessellate (Presse the green arrow whenhovering over a library to install/upgrade it)

Extra topics

• Quickstart experience on Windows
• Use Jupyter to execute code
• Debug code with visual debugging
• Use the show command
• Use the show_object command
• Download examples for build123d or cadquery
• Use the build123d snippets

Best practices

• Use the Jupyter extension for a more interactive experience. This allows to have one cell (separated by # %%) at the beginning to import all libraries

  # %%
  from build123d import *
  from ocp_vscode import *
  
  # %%
  b = Box(1,2,3)
  show(b)
  # %%

  and then only execute the code in the cell you are currently working on repeatedly.

• The config system of OCP CAD Viewer

  There are 3 levels:

  • Workspace configuration (part of the VS Code settings, you can access them e.g. via the green gear symbol in OCP CAD Viewer's "Viewer Manager")
  • Defaults set with the command set_defaults per Python file
  • Parameters in show or show_object per command

  set_defaults overrides the Workspace settings and parameters in show and show_config override the other two.

  Note that not all parameters are available in the global Workspace config, since they don't make sense globally (e.g. helper_scale which depends on the size of the boundary box of the currently shown object)

  A common setup would be

  # %%
  from build123d import *
  import cadquery as cq
  
  from ocp_vscode import *
  set_port(3939)
  
  set_defaults(reset_camera=False, helper_scale=5)
  
  # %%
  ...

  Explanation

  • The first block imports build123d and CadQuery (omit what you are not interested in).
  • The second block imports all commands for OCP CAD Viewer. set_port is only needed when you have more than one viewer open and can be omitted for the first viewer)
  • The third block as an example sets helper_scale and reset_camera as defaults. Then every show_object or show command will respect it as the default

• Debugging build123d with show_all and the visual debugger

  • If you name your contexts (including Location contexts), the visual debugger will show the CAD objects assigned to the context.

  • Use show_all to show all cad objects in the current scope (locals()) of the Python interpreter (btw. the visual debugger uses show_all at each step)

    # %%
    from build123d import *
    set_defaults(helper_scale=0.5)
    
    with BuildPart() as bp:
        with PolarLocations(3,8) as locs:
            Box(1,1,1)
    
    show_all()
    # %%

    

• Keep camera orientation of an object with reset_camera

  Sometimes it is helpful to keep the orientation of an object across code changes. This is what reset_camera does:

  • reset_camera=Camera.Center will keep position and rotation, but ignore panning. This means the new object will be repositioned to the center (most robust approach)
  • reset_camera=Camera.KEEP will keep position, rotation and panning. However, panning can be problematic. When the next object to be shown is much larger or smaller and the object before was panned, it can happen that nothing is visible (the new object at the pan location is outside of the viewer frustum). OCP CAD Viewer checks whether the bounding box of an object is 2x smaller or larger than the one of the last shown object. If so, it falls back to Camera.CENTER. A notification is written to the OCP CAD Viewer output panel.
  • reset_camera=Camera.RESET will ensure that position, rotation and panning will be reset to the initial default

Changes

v1.2.2

• Replace the boolean values for reset_camera with the Camera enum; reset_camera now supports Camera.RESET (works like True before), Camera.CENTER (works like False before) and Camera.KEEP (additionally keeps the pan location). See best practices for details.
• Replace the values for collapse with the Collapse enum: Collapse.ALL (was "C"), Collapse.None (was "E"), Collapse.LEAVES (was "1" or 1) and Collapse.Root (was "R")
• Added a button to toggle the output panel for OCP CAD Viewer
• Visual debug is on by default now (workspace setting WatchByDefault to true)
• Changed behavior of show during debug session: show will be executed, however, visual debug step omitted
• Do not show Jupyter variables _, __, _1, _2, ... in show_all
• Fix an error where the orientation marker was partly or fully moved outside its view due to panning of the object (vscode-ocp-cad-viewer issue #22)

full change log see Changes.md