cadquery/ocp-build-system

A system to build Python wheel PyPI packages for OCP.

CadQuery

---

Quick Links

Documentation | Cheatsheet | Discord | Google Group | GUI Editor

---

What is CadQuery

CadQuery is an intuitive, easy-to-use Python module for building parametric 3D CAD models. Using CadQuery, you can write short, simple scripts that produce high quality CAD models. It is easy to make many different objects using a single script that can be customized.

CadQuery is often compared to OpenSCAD. Like OpenSCAD, CadQuery is an open-source, script based, parametric model generator. However, CadQuery stands out in many ways and has several key advantages:

1. The scripts use a standard programming language, Python, and thus can benefit from the associated infrastructure. This includes many standard libraries and IDEs.
2. CadQuery's CAD kernel Open CASCADE Technology (OCCT) is much more powerful than the CGAL used by OpenSCAD. Features supported natively by OCCT include NURBS, splines, surface sewing, STL repair, STEP import/export, and other complex operations, in addition to the standard CSG operations supported by CGAL
3. Ability to import/export STEP and the ability to begin with a STEP model, created in a CAD package, and then add parametric features. This is possible in OpenSCAD using STL, but STL is a lossy format.
4. CadQuery scripts require less code to create most objects, because it is possible to locate features based on the position of other features, workplanes, vertices, etc.
5. CadQuery scripts can build STL, STEP, AMF and 3MF faster than OpenSCAD.

CadQuery was built to be used as a Python library without any GUI. This makes it great for use cases such as integration into servers, or creating scientific and engineering scripts. Options for visualziation are also available including CQ-Editor and JupyterLab.

For those who are interested, the OCP repository contains the current OCCT wrapper used by CQ.

Key features

• Build 3D models with scripts that are as close as possible to how you would describe the object to a human.
• Create parametric models that can be very easily customized by end users.
• Output high quality (loss-less) CAD formats like STEP and DXF in addition to STL, VRML, AMF and 3MF.
• Provide a non-proprietary, plain text model format that can be edited and executed with only a web browser.
• Offer advanced modeling capabilities such as fillets, curvilinear extrudes, parametric curves and lofts.
• Build nested assemblies out of individual parts and other assemblies.

Why this fork

The original version of CadQuery was built on the FreeCAD API. This was great because it allowed for fast development and easy cross-platform capability. However, we eventually started reaching the limits of the API for some advanced operations and selectors. This 2.0 version of CadQuery is based directly on a Python wrapper of the OCCT kernel. This gives us a great deal more control and flexibility, at the expense of some simplicity and having to handle the cross-platform aspects of deployment ourselves. We believe this is a worthwhile trade-off to allow CadQuery to continue to grow and expand in the future.

Getting started

To learn more about designing with CadQuery, visit the documentation, examples, and cheatsheet.

To get started playing around with CadQuery and see its capabilities, take a look at the CQ-editor GUI. This easy-to-use IDE is a great way to get started desiging with CadQuery. The CQ-editor installer bundles both CQ-editor and CadQuery (recommended). See the CQ-editor installation instructions.

The CadQuery library (with or without CQ-editor) and its dependencies may be installed using conda, or pip. Note that conda (or the CQ-editor installer) is the better supported option.

See the documentation for detailed CadQuery installation instructions.

There are also videos covering installation:

• Linux installation video
• Windows installation video

CadQuery Installation Via Conda

To first install the Conda package manager see Install the Conda Package Manager, and Mambaforge for a minimal installer.

mamba install is recommended over conda install for faster and less memory intensive cadquery installation.

# Set up a new environment
conda create -n cadquery

# Activate the new environment
conda activate cadquery

# Install the latest released version
mamba install -c conda-forge cadquery

# Or install the dev version to get the latest changes
mamba install -c conda-forge -c cadquery cadquery=master

CadQuery Installation Via Pip

CadQuery has a complex set of dependencies including OCP, which is our set of bindings to the OpenCASCADE CAD kernel. OCP is distributed as binary wheels for Linux, MacOS and Windows. However, there are some limitations. Only Python 3.8 through 3.10 are currently supported, and some older Linux distributions such as Ubuntu 18.04 are not supported. If the pip installation method does not work for your system, you can try the conda installation method.

It is highly recommended that a virtual environment is used when installing CadQuery, although it is not strictly required. Installing CadQuery via pip requires a up-to-date version of pip, which can be obtained with the following command line (or a slight variation thereof).

python3 -m pip install --upgrade pip

Once a current version of pip is installed, CadQuery can be installed using the following command line.

pip install cadquery

It is also possible to install the very latest changes directly from CadQuery's GitHub repository, with the understanding that sometimes breaking changes can occur. To install from the git repository, run the following command line.

pip install git+https://github.com/CadQuery/cadquery.git

CQ-editor GUI

CQ-editor is an IDE that allows users to edit CadQuery model scripts in a GUI environment. It includes features such as:

• A graphical debugger that allows you to step through your scripts.
• A CadQuery stack inspector.
• Export to various formats, including STEP and STL, directly from the menu.

More on CQ-editor:

• CQ-editor README
• Installation

Jupyter

CadQuery supports Jupyter out-of-the-box. Run your CadQuery code in the notebook and visualize the model by calling display(<CadQuery object>).

• JupyterLab installation.

Getting help

You can find the full CadQuery documentation at cadquery.readthedocs.io.

We also have a Google Group to make it easy to get help from other CadQuery users. We want you to feel welcome and encourage you to join the group and introduce yourself. We would also love to hear what you are doing with CadQuery.

There is a Discord server as well. You can ask for help in the general channel.

Projects using CadQuery

Here are just a few examples of how CadQuery is being used.

FxBricks Lego Train System

FxBricks uses CadQuery in the product development pipeline for their Lego train system. FxBricks has also given back to the community by creating documentation for their CAD pipeline. They have also assembled cq-kit, a library containing utility classes and functions to extend the capabilities of CadQuery. Thanks to @michaelgale and @fx-bricks for this example.

Hexidor Board Game Development

Hexidor is an expanded take on the Quoridor board game, and the development process has been chronicled here. CadQuery was used to generate the game board. Thanks to Bruce for this example.

Spindle assembly

Thanks to @marcus7070 for this example from here.

3D Printed Resin Mold

Thanks to @eddieliberato for sharing this example of an anti-kink resin mold for a cable.

License

CadQuery is licensed under the terms of the Apache Public License, version 2.0.

Contributing

Contributions from the community are welcome and appreciated.

You do not need to be a software developer to have a big impact on this project. Contributions can take many forms including, but not limited to, the following:

• Writing and improving documentation
• Triaging bugs
• Submitting bugs and feature requests
• Creating tutorial videos and blog posts
• Helping other users get started and solve problems
• Telling others about this project
• Helping with translations and internationalization
• Helping with accessibility
• Contributing bug fixes and new features

It is asked that all contributions to this project be made in a respectful and considerate way. Please use the Python Community Code of Conduct's guidelines as a reference.

Contributing code

If you are going to contribute code, make sure to follow this steps:

• Consider opening an issue first to discuss what you have in mind
• Try to keep it as short and simple as possible (if you want to change several things, start with just one!)
• Fork the CadQuery repository, clone your fork and create a new branch to start working on your changes
• Create a conda development environment with something like:
  • mamba env create -n cq-dev -f environment.yml
• Activate the new conda environment:
  • conda activate cq-dev
• If desired, install the master branch of cq-editor (Note; a release version may not be compatible with the master branch of cadquery):
  • mamba install -c cadquery -c conda-forge cq-editor=master Installing cq-editor adds another instance of cadquery which overrides the clone just added. Fix this by reinstalling cadquery using pip:
  • pip install -e .
• Before making any changes verify that the current tests pass. Run pytest from the root of your cadquery clone, there should be no failures and the output will look similar to this:
  • ======= 215 passed, 57 warnings in 13.95s =======
• Start with the tests! How should CadQuery behave after your changes? Make sure to add some tests to the test suite to ensure proper behavior
• Make sure your tests have assertions checking all the expected results
• Add a nice docstring to the test indicating what the test is doing; if there is too much to explain, consider splitting the test in two!
• Go ahead and implement the changes
• Add a nice docstring to the functions/methods/classes you implement describing what they do, what the expected parameters are and what it returns (if anything)
• Update the documentation if there is any change to the public API
• Consider adding an example to the documentation showing your cool new feature!
• Make sure nothing is broken (run the complete test suite with pytest)
• Run black to autoformat your code and make sure your code style complies with CadQuery's
• Push the changes to your fork and open a pull-request upstream
• Keep an eye on the automated feedback you will receive from the CI pipelines; if there is a test failing or some code is not properly formatted, you will be notified without human intervention
• Be prepared for constructive feedback and criticism!
• Be patient and respectful, remember that those reviewing your code are also working hard (sometimes reviewing changes is harder than implementing them!)

How to Report a Bug

When filing a bug report issue, please be sure to answer these questions:

1. What version of the software are you running?
2. What operating system are you running the software on?
3. What are the steps to reproduce the bug?

How to Suggest a Feature or Enhancement

If you find yourself wishing for a feature that does not exist, you are probably not alone. There are bound to be others out there with similar needs. Open an issue which describes the feature you would like to see, why you need it, and how it should work.

ocp-build-system's Issues

cadquery-ocp 7.6.3a0 not working on Windows 7

The cadquery-ocp 7.6.3a0 version included a compiled vtk 9.1, which used the tbb12-XXX.dll. This dll had a call to Kernel32.dll for function "GetCurrentThreadStackLimits", and windows7 does not have it. It is only available on Windows 8+.
The offical vtk 9.1 package does not have this depenedency, thus, it can be executed on windows 7.
The old cadquery-ocp 7.5.3.0's tbb dll does not have this function call.

cadquery-ocp overwrites vtkmodules

Issue

Installing cadquery-ocp from PyPI silently overwrites vtkmodules, which might conflict with an existing installation of vtk. Here's a minimum working example that demonstrates this behavior:

$ python -m venv ocp-venv
$ source ocp-venv/bin/activate
$ pip install vtk==9.2.6
$ pip install cadquery-ocp==7.7.0
$ python -c "import vtk"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/tmp/ocp-venv/lib/python3.10/site-packages/vtk.py", line 5, in <module>
    from vtkmodules.vtkWebCore import *
ImportError: Initialization failed for vtkWebCore, not compatible with vtkmodules.vtkCommonCore

Suggested Resolution

Require vtk when installing cadquery-ocp. It seems you'll have to pin the version of vtk.

Fixing 7.7.0 manylinux build

Following on from #7, it looks like the Linux wheel built, but it's broken. The only fix I can think of is to bump the manylinux requirement from manylinux_2_31 to manylinux_2_35 (fedora 36+, ubuntu 22.04+, etc.). I'm inclined to say this isn't too restrictive and we should just go ahead. @jmwright Thoughts?

Underlying issue (I think)

Roughly, I think the issue is as follows. With 7.6 we were bundling the VTK 9.1 manylinux wheel, which required manylinux_2_31, to avoid using VTK from conda, which required manylinux_2_35. (Back then, manylinux_2_35 wasn't even defined. It is now.) This replacement no longer works with 7.7, and so we are forced to use VTK from conda, which forces us to use manylinux_2_35.

Not that I really understand this, but in case it's useful to others, one observed difference between manylinux and conda VTK is as follows:

manylinux

nm -CD vtkmodules/libvtkCommonCore-9.2.so | grep GetObjectDescription
000000000065b550 T vtkObjectBase::GetObjectDescription() const
0000000000659320 T vtkObject::GetObjectDescription() const

conda

nm -CD lib/libvtkCommonCore-9.2.so | grep GetObjectDescription
00000000005bc3f0 T vtkObjectBase::GetObjectDescription[abi:cxx11]() const
00000000005ba570 T vtkObject::GetObjectDescription[abi:cxx11]() const
                                                   ^^^^^^^^^

This difference is perhaps causing the error:

ImportError: /usr/share/miniconda3/envs/cadquerytest/lib/python3.10/site-packages/cadquery_ocp.libs/libTKIVtk-d72fb669.so.7.7.0:
    undefined symbol: _ZNK9vtkObject20GetObjectDescriptionB5cxx11Ev

The undefined symbol demangles to vtkObject::GetObjectDescription[abi:cxx11]() const. So it appears that opencascade (from conda) is expecting an "abi:cxx11" VTK, which the manylinux VTK isn't. This conflict is also consistent with various discussions of whether manylinux wheels should be compiled with _GLIBCXX_USE_CXX11_ABI=1 (example).

So the conclusion is that there is no easy way to keep manylinux_2_31 compat. We can revisit if VTK manylinux wheels are made to be "abi:cxx11".

Building For Other Architectures

I think this Dockerfile (at least the contents) may be of interest to us for building for other platforms. It was mentioned in this discussion. @fpq473

No hash found for file 'LICENSES_bundled.txt'

cadquery-ocp 7.7.0a0 has a missing or invalid hash for LICENSES_bundled.txt.

This can be demonstrated with the wheel command line tool:

$ wheel unpack cadquery_ocp-7.7.0a0-cp311-cp311-manylinux_2_31_x86_64.whl 
Unpacking to: cadquery_ocp-7.7.0a0...No hash found for file 'LICENSES_bundled.txt'

And it also presents as an error when attempting to install with Poetry 1.4.0:

$ poetry add --allow-prereleases cadquery-ocp
Using version ^7.7.0a0 for cadquery-ocp

Updating dependencies
Resolving dependencies... (0.1s)

Writing lock file

Package operations: 1 install, 0 updates, 0 removals

  • Installing cadquery-ocp (7.7.0a0): Failed

  AssertionError

  In cadquery_ocp-7.7.0a0-cp39-cp39-manylinux_2_31_x86_64.whl, LICENSES_bundled.txt is not mentioned in RECORD

  at ~/.local/share/pypoetry/venv/lib/python3.8/site-packages/installer/sources.py:158 in get_contents
      154│             if item.filename[-1:] == "/":  # looks like a directory
      155│                 continue
      156│ 
      157│             record = record_mapping.pop(item.filename, None)
    → 158│             assert record is not None, "In {}, {} is not mentioned in RECORD".format(
      159│                 self._zipfile.filename,
      160│                 item.filename,
      161│             )  # should not happen for valid wheels
      162│ 

Poetry 1.4.0 introduces a "modern installer" which verifies hashes. The modern installer can be disabled with:

poetry config --local installer.modern-installation false

which writes to poetry.toml in the project directory:

[installer]
modern-installation = false

Pip does not check hashes in wheel RECORD contents during installation, see pypa/pip#4705 which is currently triaged as a bug.

Poetry is checking hashes in compliance with PEP 0427:

During extraction, wheel installers verify all the hashes in RECORD against the file contents. Apart from RECORD and its signatures, installation will fail if any file in the archive is not both mentioned and correctly hashed in RECORD.

Mac arm64 build for 7.7.x

According to CadQuery/cadquery#1236 (comment) OCP now can build arm64 libs for Mac as conda packages.
Will Mac arm64 be supported by the upcoming 7.7.x wheel too?

Error Saying We Need to Compile Wheel On Older Toolchain

@fpq473 and @roipoussiere

I'm trying to update the wheel builds in CI to support OCP 7.6.*, and I'm getting this error. Did either of you experience this when you were originally figuring out this build method?