CadQuery

Warnings

• breaking CadQuery has complex dependencies, particularly OCP (OpenCASCADE Python bindings). While Python 3.9 through 3.12 are supported for version 2.7.0, using bleeding-edge Python versions (e.g., newer than 3.12) might encounter lagging support from these underlying dependencies, leading to installation or runtime failures.
  Fix: Refer to the official documentation for supported Python versions. Consider using a `conda` environment or `miniforge` for more robust dependency management, as binary wheels for OCP are more reliably distributed via `conda-forge`.
• gotcha While `pip install cadquery` is available, the official documentation and community often recommend `conda` (or installing via the `CQ-editor` GUI bundle) for managing CadQuery's complex dependencies. This can prevent common installation issues related to `OCP` on certain operating systems or Python configurations.
  Fix: If `pip` installation fails, try `conda create -n cqenv python=3.10 && conda activate cqenv && mamba install -c conda-forge -c cadquery cadquery` (using `mamba` for faster resolution).
• gotcha CadQuery's API is designed for chaining operations (a 'fluent' API), where most methods return a *new* `Workplane` object. Directly modifying attributes of a `Workplane` or expecting side effects on previous objects in the chain can lead to unexpected behavior. Always assign the result of an operation to a variable if you need to reference that specific state.
  Fix: Always treat `Workplane` operations as returning new objects. For example, `box = cq.Workplane().box(10,10,10)` then `hole_added = box.faces('>Z').hole(5)`. Do not expect `box` to be modified by `hole_added` operations.
• gotcha When integrating CadQuery with external visualization tools or GUIs like `Jupyter CadQuery`, be aware that the default view orientation (e.g., 'Z-up' vs. 'Y-up' for the 'front' plane) can change between versions of the visualization tool. This can make your models appear rotated or misaligned from expectations if explicit orientation settings are not used.
  Fix: Consult the documentation of your visualization tool. For `Jupyter CadQuery`, explicitly set the `up` parameter in `show_object` (e.g., `show_object(result, up='Z')` or `up='Y'`) to ensure consistent viewing behavior.
• deprecated Older CadQuery tutorials or scripts might use direct imports like `from cadquery import Workplane, Vector`, or even `from cadquery import *`. While these may still function, the recommended and more robust practice is to `import cadquery as cq` and access components via `cq.Workplane`, `cq.Vector`, etc. This prevents potential naming conflicts and clearly indicates the source of the objects.
  Fix: Update imports to `import cadquery as cq` and fully qualify calls (e.g., `cq.Workplane`).

Install

• pip install cadquery Install with pip

Imports

• Workplane

  import cadquery as cq
  result = cq.Workplane(...)

  While 'from cadquery import *' might work, it can lead to namespace pollution. The convention 'import cadquery as cq' and using 'cq.Workplane' is clearer and safer.

Quickstart

This quickstart creates a simple rectangular box using the `Workplane` object, which is the primary entry point for 2D sketching and 3D modeling in CadQuery. The generated `result` object can be viewed in `CQ-editor` or exported to various CAD formats like STEP.

import cadquery as cq

# Define dimensions for a simple box
length = 80.0
height = 60.0
thickness = 10.0

# Create a rectangular box starting on the XY plane
result = cq.Workplane("XY").box(length, height, thickness)

# If running in CQ-editor, 'result' will be automatically displayed.
# For headless use or export, you would typically save it:
# cq.exporters.export(result, "my_box.step")

# This line is for testing/headless environments to confirm an object exists
assert result.isValid()