PartCAD Documentation

PartCAD is distributed across several packages depending on your use case:

• partcad: The core Python module for programmatic instantiation of parts, assemblies, and scenes.
• partcad-cli: The package containing PartCAD command-line tools.
• partcad-dev: Standalone PartCAD bundles.

In PartCAD, a package is addressed by its location (the path at which it is loaded, derived from its parent). For example, a package in the gobilda subfolder of //vendor is addressed as //vendor/gobilda.

• name field: This declares the package's identity (the path it expects to be seen at). This only takes effect when the package is loaded as the root.
• Vendoring: When you copy (vendor) a package into your own tree, it is loaded at its new location, not its declared name. PartCAD automatically redirects any internal references the package makes to its own name to its new location, ensuring the vendored copy uses itself rather than pulling in the original upstream version.

Interfaces define how parts and assemblies connect.

• Implementation: A part can implement one or more interfaces (and multiple instances of each).
• Inheritance: Interfaces can hierarchically inherit ports and properties.
• Mating: Compatibility information (mating) can be maintained within interfaces.
• Automatic Placement: If interfaces and mating are defined, PartCAD can often place parts and assemblies without user-provided coordinates.

The partcad Python module serves as the core engine for programmatic CAD management. You can use it in Python scripts to:

• Instantiate parts, assemblies, and scenes implemented as PartCAD packages.
• Integrate with [CadQuery] and [build123d] scripts.
• Power custom web, mobile, or desktop applications that render CAD models.
• Generate Bills of Materials (BoMs) and assembly instructions.

Note: If you need command-line tools, use the partcad-cli package instead of this module.

Ports are matched based on their logical center coordinates and their direction (orientation).

Matching Rules:

• For direct connections (e.g., male/female connectors) without offsets, coordinates should match and directions should be opposite (rotated 180 degrees around [1, 1, 0]).
• Convention: Use the Z-axis (blue) as the main direction.
  • Male ports: Z-axis points outwards.
  • Female ports: Z-axis points inwards.

Interchangeable Ports: To allow multiple ports to connect to any other (like NEMA-17 mounting holes), orient the ports in a circular direction. For example, set the X-axis (red) to point to the next port clockwise using the right-hand rule.

The sweep operation in PartCAD allows you to create complex 3D geometries by taking a 2D sketch (such as a circle, a DXF file, or a custom clock sketch) and sweeping it along a path to produce a 3D part.

Common use cases demonstrated in this example include:

• clock: Sweeping a clock sketch to create a 3D clock.
• dxf: Sweeping a DXF sketch to create a 3D part.
• pipe: Sweeping a circle sketch to create a pipe.

To avoid hardcoding sensitive or reusable values (like API keys or URLs) multiple times, you can reference parameters dynamically within the providers section of your configuration. Use the get_from_config() function within a parameter definition to pull values from the parameters section of ~/.partcad/config.yaml.

# ~/.partcad/config.yaml
parameters:
  my_api_url: "https://api.example.com"

providers:
  my_provider:
    type: store
    parameters:
      url:
        type: string
        default: {{ get_from_config() }}

PartCAD uses providers to implement supply chain operations. Common provider types include:

• store: Used to buy off-the-shelf parts by SKU.
• manufacturer: Used to manufacture parts following specific instructions.

To list existing providers in the PartCAD public repository, use the pc list providers command with the -r flag pointing to the commerce service.

pc init
pc list providers -r //pub/svc/commerce

When authoring scripts for build123d, cadquery, or sdf, follow these conventions:

• Imports: Import everything you use, including math and the specific CAD library.
• Exposing the part: Call show_object(<result>) to make the part visible in the renderer.
• Exports: Do not use export statements.
• CadQuery specific: Avoid using tetrahedron or hexahedron primitives.

OpenSCAD Convention:

• Provide a complete script defining all functions and constants.
• Do not use external modules.
• Do not use export statements.