A code-driven approach to mechanical design without relying on GUI-based CAD workflows.
This repository explores a methodology for designing mechanical parts and assemblies
entirely through Python code using FreeCAD, focusing on:
- ♻️ reproducibility
- 🧠 clarity of design intent
- 🤖 automation
| Language | GitHub Pages 🌐 | GitHub 💻 |
|---|---|---|
| 🇺🇸 English |  |
 |
This repository explores a methodology for designing mechanical parts and assemblies
entirely through Python code using FreeCAD, focusing on reproducibility,
clarity of design intent, and automation.
📌 Persistent Identifier (DOI)
This work is published with a DOI via Zenodo (10.5281/zenodo.18134920)
and constitutes prior art for code-driven mechanical design methodologies.
Prototype fabrication → machining → dimensional measurement → drawing.
Three-dimensional objects are projected onto two-dimensional drawings
using orthographic projection, and conversely, three-dimensional form
is reconstructed mentally from two-dimensional drawings.
This bidirectional translation constituted a core skill
for traditional mechanical designers.
From this perspective, it is understandable that
generative design or code-driven approaches—where the designer
does not directly manipulate geometry—can feel intuitively
difficult to accept.
However, semiconductor layout design followed a similar trajectory.
There was a time when routing was performed manually,
with designers carefully accounting for process-specific behavior
based on experience and tacit knowledge.
As design rules were formalized and incorporated into PDKs,
the center of design activity shifted
from manual layout to logical description using Verilog.
Viewed in the context of technological history,
it may be unavoidable that mechanical design
will follow a comparable path.
Mechanical design should not be treated as a static artifact
(CAD data or drawings),
but as a reproducible, evolvable set of rules.
Full Code Mechanical Design shifts the core of mechanical design from
manual GUI operations to explicit, executable code.
In this approach:
- 🧮 Geometry is defined by code, not by mouse operations
- 📐 Dimensions are variables, not fixed values
- 🧠 Design intent is explicit and reviewable
- 🧪 Verification and design live in the same environment
- 🧱 Mechanical design becomes reusable intellectual property (IP)
This is not an efficiency improvement.
It is a structural transformation of mechanical design itself.
Once design logic is expressed as code,
there is no reason to return to GUI-driven workflows.
Traditional CAD workflows are heavily dependent on GUI operations,
feature histories, and constraint-based assemblies.
This project intentionally avoids those assumptions and adopts the following principles:
- 🔢 Dimensions are variables
- 🧩 Geometry is defined by functions
- 📦 Parts are treated as modules
- 📐 Assemblies are defined by placements, not constraints
- 👁 The GUI is used only as a viewer
The goal is to preserve design intent and reproducibility directly in code.
- ♻️ High reproducibility (identical results on every execution)
- 🔁 Easy generation of design variants and parametric families
- 🧠 Design intent is explicit and version-controlled
- 🤖 Strong compatibility with automation (CSV, optimization, FEM, CAM)
- 🏗 Suitable for complex systems and equipment-level design
This approach can be summarized as:
Mechanical Design as Code
- ❌ Do not rely on FreeCAD GUI operations
- ✅ Prefer direct OCCT-based geometry (Part module)
⚠️ Use Sketch / PartDesign only when strictly necessary- 📍 Define clear reference origins and orientations for all parts
- 🧭 Define assemblies using explicit coordinate placements
├─ src/
│ ├─ parts/ # Individual part generators (functions/modules)
│ ├─ assembly/ # Assembly and layout definitions
│ └─ build.py # Entry point to generate the complete model
├─ README.md
└─ LICENSE
This repository includes a minimal working example that generates
a simple 3D mechanical model using FreeCAD in headless (non-GUI) mode.
- FreeCAD 0.21 or later
- Python bundled with FreeCAD
Do NOT use system Python.
You must use the Python interpreter bundled with FreeCAD.
cd src
"C:\Program Files\FreeCAD 0.21\bin\FreeCADCmd.exe" build.pyThis will:
- 🧩 Generate a simple part defined in
parts/ - 🧭 Assemble it using placement logic in
assembly/ - 📄 Create a FreeCAD document (
.FCStd) as output
The FreeCAD GUI is not required for model generation.
It may be used only to inspect the generated result.
cd src
freecadcmd build.pyThis example is intentionally minimal.
Its purpose is not to demonstrate complex geometry,
but to prove that:
- Geometry can be generated entirely by code
- Design intent lives in Python, not GUI operations
- CAD is an execution engine, not an authoring environment
This repository currently focuses on defining the
conceptual and architectural principles
of Full Code Mechanical Design.
Python / FreeCAD implementation examples
will be added incrementally.
CAD is not a drawing tool.
It is an engine for executing design logic.
The following model was generated by running the provided Python code in FreeCAD
without any GUI-based modeling operations.
Figure 1. Mechanical assembly generated purely by Python code using FreeCAD as a geometry engine.
The following model demonstrates a purely geometric solid
generated from a continuous mathematical function,
without sketches, constraints, or GUI-based modeling steps.
Figure 2. A geometric solid generated from an explicit radius function
$r = f(z)$ using Python code and FreeCAD as a geometry engine.
This example is generated by the following script:
src/geometry/loft_twist.py
The solid is created by lofting multiple cross-sections whose orientation is continuously rotated as a function of axial position.
No Sketch, no constraints, no PartDesign features are used.
All geometry is defined explicitly in Python and executed by FreeCAD as a geometry engine.
Key characteristics:
- Cross-section defined by mathematical functions
- Continuous twist angle:
- Deterministic loft generation via OCCT (
Partmodule) - Fully reproducible from code execution
This geometry has no feature history.
The only source of truth is the Python code itself.
This example is generated by:
src/geometry/branched_spiral.py
The model demonstrates a branched spiral sweep, where multiple spiral paths diverge from a common origin and are swept with a function-defined cross-section.
Such geometry is extremely difficult to author or modify in conventional GUI-based CAD systems, but becomes a natural consequence of code-defined logic.
Key characteristics:
- Parametric spiral paths with explicit branching logic
- Sweep profiles defined by functions (no sketches)
- Branching handled in code, not as a CAD exception
- Geometry regenerated identically on every execution
Once geometry is expressed as code,
branching is not a special case — it is just control flow.
These figures are not mere visual examples.
They serve as:
- ✅ Proof of non-GUI, non-interactive CAD authoring
- ✅ Visual evidence of Executable Design Intent
- ✅ Direct linkage between code → geometry → DOI
- ✅ Prior art disclosure of code-driven mechanical design
The generated CAD files are artifacts.
The design itself lives in code.
| Script | Geometry Type | Core Idea |
|---|---|---|
loft_twist.py |
Twisted loft solid | Continuous function-defined orientation |
branched_spiral.py |
Branched sweep solid | Branch-aware parametric path logic |
These scripts demonstrate that mechanical geometry can be treated as an executable system, not a manually authored shape.
This approach is directly analogous to modern SoC design workflows.
- Geometry generation → layout
- OCCT → geometry engine
- Python → RTL
- Assemblies → floorplanning
- CAD → execution environment
In this sense:
Full Code Mechanical Design is to mechanical engineering
what RTL is to SoC design.
By expressing geometry, constraints, and design decisions
entirely in code, mechanical design itself becomes
a reusable and evolvable intellectual property (IP).
The generated CAD model is only a byproduct.
The true asset is the executable design knowledge.
| Aspect | Conventional Workflow | Full Code Mechanical Design |
|---|---|---|
| Design authoring | GUI-based CAD operations | Python code |
| Dimensions | Fixed | Variables |
| Design intent | Implicit | Explicit |
| Design change | Manual edits | Logic change |
| Reusability | Low | High |
| Review | Drawings | Code + model |
| Scalability | Limited | High |
| 📌 Item | Details |
|---|---|
| Name | Shinichi Samizo |
| Expertise | Semiconductor devices (logic, memory, high-voltage mixed-signal) Thin-film piezo actuators for inkjet systems Printhead productization, BOM management, ISO training |
| GitHub |  |
| Item | License | Description |
|---|---|---|
| Source Code | Apache License 2.0 | Free to use, modify, redistribute, with patent protection |
| Text Materials | CC BY 4.0 | Attribution required |
| Figures & Diagrams | CC BY-NC 4.0 | Non-commercial use only |
| Generated CAD Outputs | Same as source code | Derived from licensed code |
| External References | Original license applies | Cite properly |
This repository discloses a code-driven mechanical design methodology. The methodology itself is provided as prior art and may not be claimed as exclusive intellectual property by third parties.
This repository and its associated Zenodo record (DOI: 10.5281/zenodo.18134920) constitute a public disclosure of the Full Code Mechanical Design methodology.
Suggestions, improvements, and discussions are welcome via GitHub Discussions.
