๐งฉ Full Code Mechanical Design
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
๐ Links
| 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)
๐ Citation & Prior Art
This work is published with a DOI via Zenodo (10.5281/zenodo.18134920)
and constitutes prior art for code-driven mechanical design methodologies.
๐ฐ Historical Context
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.
๐ Why Full Code Mechanical Design Wins
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.
๐ง Concept
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.
โ Why Code-Driven Mechanical Design?
- โป๏ธ 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
๐ Design Policy
- โ 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
๐ Repository Structure
โโ src/
โ โโ parts/ # Individual part generators (functions/modules)
โ โโ assembly/ # Assembly and layout definitions
โ โโ build.py # Entry point to generate the complete model
โโ README.md
โโ LICENSE
โถ Quick Start (Minimal Reproducible Example)
This repository includes a minimal working example that generates
a simple 3D mechanical model using FreeCAD in headless (non-GUI) mode.
๐ง Requirements
- FreeCAD 0.21 or later
- Python bundled with FreeCAD
โ ๏ธ Important
Do NOT use system Python.
You must use the Python interpreter bundled with FreeCAD.
โถ Execution (Windows example)
cd src
"C:\Program Files\FreeCAD 0.21\bin\FreeCADCmd.exe" build.py
This 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.
โถ Execution (Linux example)
cd src
freecadcmd build.py
๐ฏ Purpose of This Example
This 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
๐ง Status
This repository currently focuses on defining the
conceptual and architectural principles
of Full Code Mechanical Design.
Python / FreeCAD implementation examples
will be added incrementally.
๐งญ Philosophy
CAD is not a drawing tool.
It is an engine for executing design logic.
๐งฑ Example Output
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.
๐ Geometric Core Example (Function-Defined Geometry)
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.
๐ Advanced Geometry Examples (Executable Design Intent)
๐ Twisted Loft Solid โ Function-Defined, Code-Only Geometry
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.
๐ฟ Branched Spiral Sweep โ Branch-Aware Parametric Geometry
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.
๐ง Why These Screenshots Matter
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.
๐งฉ Design Pattern Summary
| 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.
๐ Analogy to SoC Design
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.
๐ Beyond CAD: Mechanical Design as IP
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.
๐ Practical Workflow Comparison
Conventional Mechanical Design vs Full Code Mechanical Design
| 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 |
๐ค Author
| ๐ 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 |  |
๐ License
| 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 |
Methodology Notice
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.
Prior Art Notice
This repository and its associated Zenodo record (DOI: 10.5281/zenodo.18134920) constitute a public disclosure of the Full Code Mechanical Design methodology.
๐ฌใFeedback
Suggestions, improvements, and discussions are welcome via GitHub Discussions.
