Ctrl+K

Python API#

Basic Usage#

JupyterCAD provides a Python API that can be used for opening CAD documents, create and edit primitives (cones, boxes, spheres etc.) and apply boolean operations on them (cut, union, intersection etc.).

You can open an existing file and display it in your Jupyter Notebook:

from jupytercad import CadDocument

doc = CadDocument('file.FCstd')

doc

Opening an existing file would connect to the collaborative session of the file, meaning that anyone working on the same file from either the dedicated CAD app of the JupyterLab extension would see the edit you perform from the Python API.

Creating a CadDocument object without providing a path to an existing file would create a new empty document:

from jupytercad import CadDocument

doc = CadDocument()

doc

Once the document is opened/created, you can start creating primitives and apply boolean operations. The CadDocument does method chaining, allowing you to perform multiple operations in one line:

from jupytercad import CadDocument

doc = CadDocument()

# Create a box, create a sphere, then cut the box using the sphere as a tool
doc.add_box().add_sphere().cut()

doc

You can also make use of the OpenCascade Python API using the pythonocc-core package:

from jupytercad import CadDocument
...
# Create a prism shape with OpenCascade
prism = BRepPrimAPI_MakePrism(profile, vec).Shape()
doc = CadDocument()
doc.add_occ_shape(prism)
display(doc)
JupyterCAD Python OpenCascade API support

CadDocument API Reference#

class jupytercad.CadDocument(path=None)#

Create a new CadDocument object.

Parameters:

path (Optional[str]) – the path to the file that you would like to open.

If not provided, a new empty document will be created.

add_annotation(parent, message, *, position=None, user=None)#

Add an annotation to the document.

Parameters:

  • parent (str) – The object which holds the annotation.

  • message (str) – The first messages in the annotation.

  • position (Optional[List[float]]) – The position of the annotation.

  • user (Optional[Dict]) – The user who create this annotation.

Return type:

Optional[str]

Returns:

The id of the annotation if it is created.

add_box(name='', length=1, width=1, height=1, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Add a box to the document.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • length (float) – The length of the box.

  • width (float) – The width of the box.

  • height (float) – The height of the box.

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

add_cone(name='', radius1=1, radius2=0.5, height=1, angle=360, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Add a cone to the document.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • radius1 (float) – The bottom radius of the cone.

  • radius2 (float) – The top radius of the cone.

  • height (float) – The height of the cone.

  • angle (float) – The revolution angle of the cone (0: no cone, 180: half cone, 360: full cone).

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

add_cylinder(name='', radius=1, height=1, angle=360, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Add a cylinder to the document.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • radius (float) – The radius of the cylinder.

  • height (float) – The height of the cylinder.

  • angle (float) – The revolution angle of the cylinder (0: no cylinder, 180: half cylinder, 360: full cylinder).

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

add_occ_shape(shape, name='', position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Add an OpenCascade TopoDS shape to the document. You need pythonocc-core installed in order to use this method.

Parameters:

  • shape – The Open Cascade shape to add.

  • name (str) – The name that will be used for the object in the document.

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

add_sphere(name='', radius=5, angle1=-90, angle2=90, angle3=360, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Add a sphere to the document.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • radius (float) – The radius of the sphere.

  • angle1 (float) – The revolution angle of the sphere on the X axis (0: no sphere, 180: half sphere, 360: full sphere).

  • angle2 (float) – The revolution angle of the sphere on the Y axis (0: no sphere, 180: half sphere, 360: full sphere).

  • angle3 (float) – The revolution angle of the sphere on the Z axis (0: no sphere, 180: half sphere, 360: full sphere).

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

add_torus(name='', radius1=10, radius2=2, angle1=-180, angle2=180, angle3=360, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Add a torus to the document.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • radius1 (float) – The outer radius of the torus.

  • radius2 (float) – The inner radius of the torus.

  • angle1 (float) – The revolution angle of the torus on the X axis (0: no torus, 180: half torus, 360: full torus).

  • angle2 (float) – The revolution angle of the torus on the Y axis (0: no torus, 180: half torus, 360: full torus).

  • angle3 (float) – The revolution angle of the torus on the Z axis (0: no torus, 180: half torus, 360: full torus).

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

cut(name='', base=None, tool=None, refine=False, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Apply a cut boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • base (str | int) – The base object that will be used for the cut. Can be the name of the object or its index in the objects list.

  • tool (str | int) – The tool object that will be used for the cut. Can be the name of the object or its index in the objects list.

  • refine (bool) – Whether or not to refine the mesh during the cut computation.

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

fuse(name='', shape1=None, shape2=None, refine=False, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Apply a union boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • shape1 (str | int) – The first object used for the union. Can be the name of the object or its index in the objects list.

  • shape2 (str | int) – The first object used for the union. Can be the name of the object or its index in the objects list.

  • refine (bool) – Whether or not to refine the mesh during the union computation.

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

intersect(name='', shape1=None, shape2=None, refine=False, position=[0, 0, 0], rotation_axis=[0, 0, 1], rotation_angle=0)#

Apply an intersection boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.

Parameters:

  • name (str) – The name that will be used for the object in the document.

  • shape1 (str | int) – The first object used for the intersection. Can be the name of the object or its index in the objects list.

  • shape2 (str | int) – The first object used for the intersection. Can be the name of the object or its index in the objects list.

  • refine (bool) – Whether or not to refine the mesh during the intersection computation.

  • position (List[float]) – The shape 3D position.

  • rotation_axis (List[float]) – The 3D axis used for the rotation.

  • rotation_angle (float) – The shape rotation angle, in degrees.

Return type:

CadDocument

Returns:

The document itself.

property objects: List[str]#

Get the list of objects that the document contains as a list of strings.

remove_annotation(annotation_id)#

Remove an annotation from the document.

Parameters:

annotation_id (str) – The id of the annotation

Return type:

None

set_color(object_name, color)#

Set object color.

Parameters:

  • object_name (str) – Object name.

  • color (Optional[List]) – Color value, set it to None to remove color.

Return type:

None

On this page
Show Source