openvmp / partcad

The first package manager for CAD models and a framework for managing assemblies.

PartCAD

PartCAD is the first package manager for CAD models and a framework for managing assemblies. It aims to complement Git with everything necessary to substitute commercial Product Lifecycle Management (PLM) tools.

PartCAD maintains information about mechanical parts and how they come together to form larger assemblies. The same parts can be reused in multiple assemblies and multiple projects. And all of that is supercharged by the ultimate versioning and collaboration features of Git.

PartCAD features include:

• 3D part models using STEP, STL and 3MF files
• 3D part models using CadQuery, build123d and OpenSCAD scripting languages (including AI-generated: Gemini and GPT)
• 2D blueprints using DXF, build123d and SVG files
• Fully featured object-oriented approach to maintain part interfaces and mating information (with multiple class inheritance etc)
• Live preview of 3D models while coding in VS Code

Find more documentation here and visit our website.

Installation

Extension for Visual Studio Code

This extension can be installed by searching for PartCAD in VS Code extension search form, or by browsing its VS Code marketplace page.

Command-Line Interface

The recommended method to install PartCAD CLI tools for most users is:

pip install -U partcad-cli

For contributors:

git clone https://github.com/openvmp/partcad.git
cd partcad
python3 -m pip install -U -e ./partcad
python3 -m pip install -U -e ./partcad-cli

PartCAD works best when conda is installed. If that doesn't help (e.g. MacOS+arm64) then try mamba. On Windows, PartCAD requires at least a conda environment. On Ubuntu, try apt install libcairo2-dev if pip install fails to install cairo.

Architecture

Tools for Mechanical Engineering

Here is an overview of the open-source tools to maintain mechanical projects. It demonstrates where this framework fits in the modern mechanical development workflows.

flowchart TB

subgraph repo["Your project's GIT repository"]
  subgraph custom_repo["Custom parts"]
    direction TB
    custom_part_internet["A STEP file\ndownloaded from Internet\nor the vendor site"]
    custom_part_cad["A part exported as a solid\nfrom a CAD tool not\nsuitable for collaboration"]
    custom_part_cq["An individual reusable part\nmaintained as a script\nunder a version control system"]
    custom_part_os["Another reusable part\nmaintained as a script\nunder a version control system"]
  end

  model["Your project's model defined\nas ASSY or Python code\nfor version control\nand collaboration"]

  subgraph scenes["Scenes"]
    test1["Capability 1\ntest scene"]
    test2["Capability 2\ntest scene"]
  end
end

subgraph external_repos["Third-party GIT repositories,\nCDN-hosted files or OCCI servers"]
  subgraph external_repo["Repository of standard\nor popular parts"]
  end
end

subgraph external_tools["External tools"]
  freecad["FreeCAD"]
  cadquery["CadQuery / build123d"]
  openscad["OpenSCAD"]
  gazebo["Gazebo"]

  partcad["PartCAD library"]
  style partcad fill:#c00
end

custom_part_cad <--- |Individual\ncontributor|freecad
custom_part_cq <--- |Part design\nworkflow| cadquery
custom_part_os <--- |Part design\nworkflow| openscad

external_repo ---> |Import| model
custom_repo ---> |Import| model
model -.-> |Import| test1
model -.-> |Import| test2

custom_repo <-. Maintained\nusing\nPartCAD\nconvention .- partcad
external_repo <-. Maintained\nusing\nPartCAD\nconvention .- partcad
model <--- partcad
test1 <--- partcad
test2 <--- partcad

test1 -.-> |Export| gazebo
test2 -.-> |Export| gazebo

partcad's Issues

Migrate documentation from Markdown to RST

Copy all of the content from the top level README.md into the docs/ folder so that it's published on readthedocs.
Keep the top level README.md simple and concise, focused on listing the features with links to readthedocs for each feature.

Display git progress

Use GitPython.RemoteProgress to update the context initialization spinner from within ProjectFactoryGit.
In the Project class, access the spinner as a field in the Context object, do not pass it as a parameter.

Render markdown (including bill of materials)

There is currently dead code "Shape.render_markdown()" copied from OpenVMP's internal library.
It has to move to the "Assembly" class.
The "Part" class (the other child of "Shape") needs to get another implementation of "render_markdown()" that creates a simple description of the part.

Extend "Project.render()" to render markdown files if "render->markdown" is provided.
Render markdown for assemblies unless "render->markdown->assemblies==False".
Render markdown for parts if "render->markdown->parts==True".
Pass all other options necessary to render markdown files as other parameters in "render->markdown".

Package linting

Add "cli_lint.py" to implement "pc lint [-r]" to lint the current package or all of them recursively in case of "-r".
Not to be confused with assembly or part linting (to be implemented later).

"cli_lint()" would initialize the context and apply linting rules to all packages (call linting rules one by one passing packages as parameters).
Initialize the list of all linting rules in "lint_package_all.py".
Define the LintPackageRule class to be used by all package linting rules as the best class in "lint_package.py".
Implement a couple of basic linting rules in "link_package_<rule_name>.py".
For example:

• warn about missing "desc" fields in packages, parts and assemblies.
• warn about malformed or unreachable urls if "url" field is present (for now, better not attempt to figure out if "url" is expected to be present or not)

Export to JPEG

Add an option to export models to JPEG file.
Make it very similar to the way PNG is rendered, including moving the work with dependencies into a separate plugin.
All dependencies need to be installed in partcad-cli, but partcad itself should use importlib to check whether the dependencies are available (see how PNG works).

Extend examples/feature_export to render a JPEG file too.

Preferrably, use pure Python dependencies only. Otherwise, after completion create an issue to add another JPEG plugin with pure python dependencies only.

Add support for SDF

Implement 'part_factory_sdf.py' and the corresponding wrapper (to run SDF scripts in a sandbox) to support parts defined in SDF.

At least, run the script in a temporary folder and pick up the resulting file using the filename (a separate param).
At most, intercept the "save" function calls (load the class ahead of time and substitute the 'save' method?) and pick up the first object or the one which has the filename matching the filename parameter.

'''
parts:
syntax_example_part:
type: sdf
output: out.stl
'''

Enable automated testing of OpenSCAD features

Add one or more steps to the github action that tests PartCAD.
These steps should install OpenSCAD in the OS specific ways.
As a result, the executable "openscad" must appear in $PATH before the invocation of "pytest".

Purchasing and manufacturing proposal

Propose a convention/syntax to annotate the part declaration with sufficient data to order (SKU, API to order programatically) or to manufacture (what tools, materials are needed, url to instructions).

Ideally “pc order {-a} [part] {package}” should be able to purchase all parts, should they supply all the necessary data.

Load all this data into the Part object to enable search criteria (has ordering info, needs materials I have, etc). The implementation of search is outside of the scope of this issue.

More rendering params

Add rendering params (both the package configuration file and cli command options) for strokeWidth, marginLeft and marginTop.
They need to be stored in the context class next to "output_dir".
Perhaps rename "output_dir" to "render_output_dir" and store new options in "render_...".
While output_dir is used in all rendering functions (see shape.py),
these three options will need to be used for generating the SVG file and, thus,
influence other formats produced from SVG (at least PNG for now, more to follow).

Jinja templates

Preprocess package YAML files with Jinja. No support for passing parameters needed. Mostly for reusing and multiplying text.

Export to BREP

Add a feature to export to BREP exactly the same way export is already done for STEP.
Use build123d function called Shape.export_brep() for this purpose.

Fix Github Action test for Windows and Python 3.11

The github action in .github/workflows/python-test.yml has Windows with Python 3.11 disabled.
When enabled, the action fails even though the test cases all pass.
For some reason github claims that the testing step returns a non-zero exit code even though pytest was supposed to return zero.

Rename projects into packages

Most of documentation is already using the term "package" instead of "project".
However the source code still uses "project".
All the files, classes, variables etc need to be renamed to completely abandon the use of the work "project".
Let's call them packages from now on.

Add CLI options to configure logging

PartCAD uses Python's logging module.
Add CLI parameters to change the logging value and to redirect output to file, syslog, and other popular options.

Offline mode for imported git repositories

Update the "git" project factory class so that the behavior changes if there is already a cloned copy of the repo:

• if the exact revision is specified and it is a tag, then do nothing
• if the exact revision is specified and it is a branch, then attempt to update it if the last update happened more than T1 time ago
• do not log any error (warning only) if the update attempt failed less than T2 time since the last successful update
• do not log any error and, preferrably, do not waste any time waiting, if it is determined with a high degree of likelihood that there is no Internet connectivity

Maintain default values for T1 (1 hour) and T2 (1 day) and allow the user to override the defaults in the "user config" (user_config.py).
Implement all of that without introducing any non-pure-Python dependencies.

Introduce the options to define "ports" for parts

Extend the "part" declaration syntax to include the option to specify a list of named "ports" that define the location, orientation and rotation of the ports/connectors/mounts withing the coordinate systems used to define that part. The expected result is that it should be possible to deterministically define the assembly by simply saying, for example, connect port1 of part1 to port2 of part2 at an angle A with distance D without specifying any other value (no coordinates etc). Make A and D default to 0. Make it optional to provide an additional parameter DE: the distance to be used in the exploded views.

Add support for packages with additional Python dependencies

Add support for packages with their own "requirements.txt" files.

Run dependency installation when the package is added or updated.

Installation (cortibutor type) on Windows 10

I can not get PartCAD and PartCAD-CLI installed without errors using the version 0.5.11.
(using VS Code Insider Build or VS Code )
This errors were thrown with Python 3.10 and 3.11

I used a clean conda environment. (Maybe conda could be the cause of the issue? Or is it the requirements.txt that tries to pull the package it from pypi.org ?)

PIP throws dependency errors for part-cad

partcad-cli 0.5.10 requires partcad==0.5.10, but you have partcad 0.5.11 which is incompatible.
Successfully installed partcad-0.5.11

and for partcad-cli

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
partcad-cli 0.5.10 requires partcad==0.5.10, but you have partcad 0.5.11 which is incompatible.

As expected the PartCAD client (VS Code Extensions) also throws error messages.

Tell me if you need more details or have an idea, what is going wrong here.

Lazy part initialization

Make sure the “Shape.shape” field is only accessed via “Shape.get_shape()”.
Delay the instantiation until the getter is called. For example, CQGI should only be invoked if “get_shape()” got called.

Add OpenSCAD support

Implement “part factory” that loads OpenSCAD files.
The way parts get declared should be identical to step files, but using “type: openscad”.

Automate CHANGELOG.md

Update GitHub Actions:

• to populate the changelog with pull request titles
• to update the changelog when bumping the version

PyPI documentation

Create a simplified version of REAME.md to be used in PyPI (see "readme.= " in "pyproject.toml").
At the moment PyPI poorly displays the package as the readme contains GitHub specific features.

Create video tutorial

Create a YouTube video and add it to the README.
The video should demonstrate VS Code IDE with an integrated terminal view, text view (to show examples and partcad.yaml files) and the “OCP CAD Viewer” view.
It should demonstrate “pc init”, “pc list”, “pc list-parts -r”, “pc show”.
Both when “pc show” is called and when examples are executed, the viewer should display the resulting model.

ASSY: Assemly YAML format

Introduce a YAML format that can be used to define assemblies. Not be confused with the existing YAML format "to declare" assemblies.

When the assembly is declared, the "type" parameter is set to "assy". The file must be pre-processed by Jinja before consuming.

Use SDF (from ROS/Gazebo) as an inspiration: use links and joints. Parts become links. Joints define how links are connected to each other. There must be a very simple way to define joints after #7 is implemented.

Multithreaded git cloning

Make the Context class spawn a separate thread in each “import_project()”. Be careful with synchronizing recursive import operations and ensure the same project does not get imported twice by different consumers.

Update the spinner accordingly, so that it displays the last project/package that was spawned in a separate thread. Display error messages through the spinner interface and prepend the repo name to all messages.