Tutorial

Command Line

Create a package

First, the current directory needs to be initialized as a PartCAD package.

# Initialize the new PartCAD package in the current folder
pc init

If there is no -p flag passed to pc init then the dependency on the public PartCAD repository is added automatically.

pc init also adds a Render command to .vscode/launch.json, at the root of the git repository it is run in (next to the package, when there is no repository). It shows up in the “Run and Debug” view of the PartCAD IDE and of Visual Studio Code, and running it renders the package the same way pc render does from a terminal. An existing launch.json, with commands and comments of your own in it, is added to rather than replaced.

Alternatively, manually create partcad.yaml with the following content:

# partcad.yaml
dependencies:
  # Public PartCAD repository (reference it explicitly if required)
  pub:
    type: git
    url: https://github.com/partcad/partcad-index.git
    revision: main

Now launch pc list to see the list of packages currently available in the public PartCAD repository.

# Recursively iterate over all dependencies of the current package
pc list

Manage dependencies

PartCAD has to be provided with a configuration file which may declare parts and assemblies, but also declares all repositories that PartCAD is allowed to query.

PartCAD has no implicit dependencies built-in, so a dependency on the public PartCAD repository needs to be added if PartCAD is supposed to query it.

In the newly created package, comment out the “pub” dependency (prepend #) and see how the output of pc list changes.

Add a part

Let’s add a part defined using an OpenSCAD script.

First, create the OpenSCAD script which defines a cube of size 10mm.

# Create "test.scad"
echo "translate (v= [0,0,0])  cube (size = 10);" > test.scad

Now let’s add a declaration of this part to partcad.yaml.

pc add part scad test.scad

Import an existing part

The pc import part command allows you to import an existing part into a PartCAD project. You can also specify a target format to convert the part upon import.

Basic import:

# Import a STEP file
pc import part step my_part.step

Import and convert to STL:

# Import a STEP file and convert it to STL format
pc import part step my_part.step -t stl

Provide an optional description:

pc import part stl my_model.stl --desc "3D model of a mechanical part"

Example log output:

pc import part step my_part.step -t stl
INFO: Importing part: my_part.step (step)
INFO: Performing ad-hoc conversion: step → stl
INFO: Ad-hoc conversion successful: my_part.stl
INFO: Successfully imported part: my_part

Note

The imported part is added to the project directory.
If a target format is specified, the part is converted automatically.

Inspect the part

Once a part is created, it can be inspected in PartCAD Viewer.

pc inspect :test

Export the part

Now the part can be exported:

pc export -t stl :test

Convert a Part

The pc convert part command converts a part or assembly within a package into another format. It updates the type of the part if the format changes.

Usage:

# Convert part "cube" to STEP format
pc convert part cube -t step

# Convert an enrich-type part using its original format (no -t needed)
pc convert part enriched_part

# Save output in a specific directory
pc convert part cube -t step -O ./output

# Dry-run to preview changes
pc convert part cube -t step --dry-run

Options:

-t, --target-format: Output format (e.g., step, stl, obj, etc.)
-P, --package: Package name (default is current directory)
-O, --output-dir: Directory to save output files
--dry-run: Simulate the conversion process without modifying any files

Supported formats:

STEP
BREP
STL
3MF
ThreeJS (JSON)
OBJ
glTF (JSON)
IGES

Special behavior:

If the part is of type `enrich` or `alias`, the -t option is optional. In this case, the system automatically resolves the original format and converts to it:

# "alias_part" refers to a BREP-based part, so no format needed
pc convert part alias_part

Note

The part must be declared in the partcad.yaml file. If the output format is not supported or missing for non-enrich/alias, the command will fail.

Convert a Sketch

The pc convert sketch command converts a sketch (e.g., SVG or DXF) to another supported format. This command updates the sketch type in the project if applicable.

Usage:

# Convert sketch "circle_svg" to DXF format
pc convert sketch circle_svg -t dxf

# Convert an enrich-type sketch to its original format (no -t needed)
pc convert sketch enriched_sketch

# Save output in a specific directory
pc convert sketch circle_svg -t dxf -O ./output

# Simulate the conversion without writing files
pc convert sketch circle_svg -t dxf --dry-run

Options:

-t, --target-format: Output format (svg or dxf)
-P, --package: Package name (default is current directory)
-O, --output-dir: Output folder for the converted sketch
--dry-run: Perform a dry-run (no files are created or modified)

Supported formats:

SVG
DXF

Special behavior:

If the sketch is of type `enrich` or `alias`, the -t argument is optional. The system will convert it to the original underlying format automatically:

# "alias_sketch" refers to an SVG sketch
pc convert sketch alias_sketch

Note

The sketch must be listed in partcad.yaml and marked as a sketch. If the format is not supported or the resolution fails, the command will return an error.

Reset partcad

PartCAD maintains an internal state to keep track of dependencies of a project. This state can be reset using the command below.

pc system reset

VS Code Extension

Start new workspace

Open Visual Studio Code and create a new empty workspace.

Activate Python

If necessary, install the Python extension. Activate a Python environment (3.10 or above).

Install the extension

Install the PartCAD extension from the VS Code marketplace.

Install PartCAD

Switch to the PartCAD workbench (look for the PartCAD logo at the left edge of the screen). There is the PartCAD Explorer view on the left. Click Install PartCAD in the Explorer view if this button is shown to install PartCAD in the activated Python environment.

Create a package

Once PartCAD is initialized, it won’t detect any PartCAD package in the empty workspace. Click Initialize Package to create partcad.yaml.

Browse

Browse the imported packages in the Explorer view. Click on the parts and assemblies to see them in the PartCAD Viewer view that will appear on the right.

For example, navigate to //pub/std/metric/cqwarehouse and click on some part (e.g. fastener/hexhead-din931). The PartCAD Inspector view displays the part parameters. The parameter values can be changed and the part gets redrawn on Update.

Create a part

Click Add a CAD script in the Explorer view toolbar. Select build123d from the dropdown list. Then select Example 3: Bead as the template to use. An editor view with the newly created script will be shown.

Inspect the part

When you edit Python or OpenSCAD files that are used in the current PartCAD package, saving the file makes it displayed automatically. Press Save (Ctrl-S or Cmd-S) to save the script and trigger an automatic inspection of the part. The PartCAD Viewer view will appear on the right.

Import parts

In case you want to use existing PartCAD parts in the design of your part, then follow the following steps.

First, select the part you want to use in the PartCAD Explorer view. Then, add the following to the build123d script created during the previous steps of this tutorial:

import partcad as pc

other_part = pc.get_

Please, note, that after “pc.get_" a code completion suggestion appears. Use the suggested code completion option to insert the code that adds the selected part to this build123d script.

Here is an example of how to use the newly added solid:

...
# After "with BuildPart"
art = Compound([art, other_part])
# Before "show_object"
...

Import an Assembly

The pc import assembly command allows you to import an assembly from a STEP or URDF file. The format is taken from the file’s extension.

From a STEP file it extracts the individual parts and creates an assembly YAML file that records each part along with its placement. From a URDF it creates an stl part per link carrying the physical properties the URDF stated, a pair of interfaces per joint, and an assembly that connects the parts through them rather than placing them by coordinates - see Configuration.

An import leaves the package holding PartCAD’s own objects - parts it can render on their own and an assembly that places them - rather than a declaration that points back at the foreign file. Use pc add assembly when you want the latter: it declares a file where it lies, and the URDF stays a URDF.

Usage

# Import an assembly from a STEP file with an optional description
pc import assembly my_assembly.step --desc "Optional assembly description"

# Import a robot description; each link becomes a part, each joint an interface
pc import assembly robot.urdf

# Or keep the URDF as the assembly, reading it in place
pc add assembly urdf robot.urdf

Functionality

File Parsing: For a STEP file, the command first attempts to parse it using an XDE-based approach. If no parts are found via XDE, it falls back to a classic STEP parsing method. A URDF is parsed with ROS’s own urdf_parser_py.
Duplicate Filtering: Unique parts are identified by comparing the geometric data and applied transformations. Duplicate entries are discarded based on a composite key of shape identifier and transformation.
Part Extraction: Each unique SOLID is saved as a separate STEP file in a dedicated subfolder. The transformation (translation and rotation) of each part is recorded and later used in the assembly.
Assembly Creation: An assembly YAML file is generated, linking the parts (by file name) with their transformation data. This YAML file is then added to the project, finalizing the assembly import.

Example Log Output

INFO: Detected an assembly with 5 parts.
INFO: Saving parts in folder: ./my_assembly
INFO: Imported part: my_assembly_part1 → my_assembly/my_assembly_part1.step
INFO:   Location: [[tx, ty, tz], [rx, ry, rz], rotation_angle]
INFO: Assembly 'my_assembly_assy' successfully added with 5 parts.

Notes

The STEP file must contain more than one SOLID to be considered an assembly.
If the file does not represent an assembly (i.e. only a single SOLID is found), the command will raise an error.
The transformation data is recorded as a combination of translation and rotation (axis and angle), enabling precise placement of each part within the assembly.
Importing a URDF produces one stl part per link, carrying the mass, inertia, friction and colour the URDF stated, and one pair of interfaces per joint - so the generated assembly connects its parts through the joints rather than placing them by coordinates. See Simulation, URDF and SDFormat for what survives the conversion and what does not.

Create an assembly

This is what PartCAD (or, at least, its VS Code Extension) is actually for.

Click Add an assembly file to the current package in the PartCAD Explorer view. After that select an existing assembly file (*.assy) or enter a filename for the new file to be created.

ASSY (Assembly YAML) files use the YAML syntax. The list of parts has to be added as children under the links node. Here is how an empty assembly file looks like:

links:

Add a part to the assembly

Select the desired part or assembly in PartCAD Explorer. After that navigate to the next line under “links:” and type “- pa” (which is what you do when you want to add a child item with the name “part”) and, then, select the code completion suggestion from PartCAD.

This will add the selected part or assembly to the assembly file.

Inspect the assembly

When you edit ASSY files in the current PartCAD package, the assembly is displayed automatically on save. Press Save (Ctrl-S or Cmd-S) to save the assembly file and trigger an automatic inspection of the assembly. The PartCAD Viewer view will appear on the right if it’s not open yet.