search

bernhard-42 / jupyter-cadquery

An extension to render cadquery objects in JupyterLab via pythreejs
Apache License 2.0
307 stars 44 forks source link
cad cadquery ipywidgets jupyterlab python pythonocc

readme

Jupyter-CadQuery

View CadQuery objects in JupyterLab or in a standalone viewer for any IDE

Overview

Click on the "launch binder" icon to start Jupyter-CadQuery on binder:

Binder: Latest development version

Overview

Release 3 is a complete rewrite of Jupyter-CadQuery: While the selection of pythreejs and JupyterLab's sidecar looked reasonable in 2019, it turned out they had too many limitations. pythreejs is stuck with an outdated version of threejs and the sidecar project did not improve usability to a level I would have liked to have.

Jupyter-CadQuery is now a 3 layer project:

  1. three-cad-viewer This is the complete CAD viewer written in Javascript with threejs being the only dependency. There is are a bunch of live examples and an API documentation.

  2. cad-view-widget A thin layer on top of cad-viewer-widget that wraps the CAD viewer into an ipywidget. The API documentation can be found here

  3. jupyter-cadquery (this repository) The actual CadQuery viewer, collecting and tessellating CadQuery objects, using cad-view-widget to visualize the objects. It was written with the intent to be as compatible with Jupyter-CadQuery 2.x as reasonable.

    Note: For changes see the migration section at the end of this page.

Key Features

Release v3.5.2 (03.01.2023)

Changes

Fixes

Examples

Animation system in JupyterLab

Debugging

Installation

Using conda

  1. For using Jupyter-CadQuery in Jupyterlab

    • If you don't have it already, create a new conda environment with the latest CadQuery (e.g. master)

      conda create -n jcq3 -c conda-forge -c cadquery python=3.10 cadquery=master vtk=9.2.2
conda activate jcq3

    • Install Jupyter-CadQuery (note, matplotlib is only used for the examples)

      pip install jupyter-cadquery==3.5.2 cadquery-massembly==1.0.0 matplotlib

      Windows users should also install pywin32 again with conda to ensure it is configured correctly

      conda install pywin32

    • Start Jupyter-CadQuery

      conda activate jcq3
jupyter lab

    • If you use the dark theme of JuypterLab, add the following code in the first cell of your notebook:

      [1]: from jupyter_cadquery import set_defaults, open_viewer
     set_defaults(theme="dark")
     open_viewer("CadQuery")

  2. For running Jupyter-CadQuery as standalone viewer

    • Start the browser based viewer

      conda activate jcq3
jcv [-w width] [-h height]     # light theme
jcv [-w width] [-h height] -d  # dark theme

    • Use it from an IDE: In your code import the show or show_object function from the viewer:

      import cadquery as cq
from jupyter_cadquery.viewer.client import show, show_object
obj = cq. ...
show(obj) # or show_object(obj)

      show works as in JupyterLab, while show_object views objects incrementally as in CQ-Editor

Using a docker image

  1. For using Jupyter-CadQuery in Jupyterlab

    • Start Jupyter-Cadquery

      WORKDIR=/tmp/jupyter
mkdir -p "$WORKDIR"  # this has to exist, otherwise an access error will be thrown
docker run -it --rm -v $WORKDIR:/home/cq -p 8888:8888 bwalter42/jupyter_cadquery:3.5.2

      Jupyter in the container will start in directory /home/cq

    • To start with examples, you can

      • omit the volume mapping and just run docker run -it --rm -p 8888:8888 bwalter42/jupyter_cadquery:3.5.2 or
      • copy the example notebooks to your $WORKDIR. They will be available for Jupyter-CadQuery in the container.

    • If you want to change the Dockerfile, make docker will create a new docker image

  2. For running Jupyter-CadQuery as standalone viewer

    • Start the browser based viewer (eventually add cli options, see notes below):

      docker run -it --rm -p 8888:8888 --name jcq -p 5555:5555 bwalter42/jupyter_cadquery:3.5.2 -v

    • In your code import the show or show_object function from the viewer:

      import cadquery as cq
from jupyter_cadquery.viewer.client import show, show_object
obj = cq. ...
show(obj) # or show_object(obj)

      show works as in JupyterLab, while show_object views objects incrementally as in CQ-Editor

    • Execute your code using the Python interpreter located in the container:

      docker exec -i jcq bash -c ". /opt/conda/bin/activate cq; python" < my_project.py

Notes:

Demo Notebooks

Usage

a) Show objects

`show(cad_objs, kwargs)`**

Positional arguments args:

Keywork arguments kwargs:

b) Manage default values

c) Replay objects

Note, this is not supported in the standalone viewer for the time being.

d) Exports:

Jupyter-CadQuery classes

Migration from 2.x

Deprecations:

Changed behavior:

Parameters of function show and set_defaults not supported any more:

Credits

Known issues