3D CAD Toolkit

A high-performance, modular 3D Computer-Aided Design (CAD), procedural modeling, and visualization engine engineered for both interactive human workflows and autonomous AI agent collaboration.

Key Features

• Interactive 3D Viewport:

  • Built with Dear PyGui for responsive, lightweight cross-platform GUI.
  • Hardware-accelerated OpenGL offscreen rendering with true per-pixel depth buffering (Z-buffer), polygon offset shaded-wireframe overlays, and automatic CPU rasterizer fallback.
  • 3D translation/rotation/scale manipulator gizmos, flying and orbit camera controls, RGB coordinate axes, and build-plate grid.
  • Interactive measurement tools (point-to-point distance, angles, surface area).

• AI Agent CollabBridge (HTTP & CLI):

  • Built-in HTTP JSON API (port 8765) and CLI (bridge.py) designed specifically for AI pair programmers and autonomous agents.
  • Allows external processes to query scene state, select/inspect objects, trigger parametric tweaks, draw temporary 3D debug overlays, and command camera movements in real time without restarting the viewer.

• Procedural & Parametric Modeling:

  • Primitives: Box, Sphere, Cylinder, Capsule, Cone, Torus, Extruded Text, and 3D Polylines.
  • CSG Operations: Exact Boolean Union, Difference, Intersection, Chamfer, Fillet, Sweep, and Loft via Manifold3D.
  • Assembly Management: Hierarchical object groups, transformation hierarchies, and interactive exploded views.

• Signed Distance Fields (SDF) & Meshing:

  • Mathematical SDF representation with smooth polynomial CSG blending (smooth_union, smooth_difference, smooth_intersection).
  • High-resolution Marching Cubes and Dual Contouring meshing with integrated quadric mesh decimation/simplification.

• 3D Printability Analysis:

  • Watertight / manifold topology validation.
  • Critical overhang detection and support volume estimation.
  • Build-volume verification against popular printer presets (Bambu Lab, Prusa MK3/MK4, Ender 3, Voron 2.4/350).
  • Automatic print orientation optimization (--auto-orient) to minimize support requirements and maximize build-plate contact area.

• Multi-Format Export & Rendering:

  • 3D Formats: Binary/ASCII STL, OBJ, PLY, GLB, and DXF.
  • High-Resolution Snapshots: Anti-aliased (SSAA 1x/2x/4x) image snapshots in PNG (with alpha transparency), JPEG, WebP, TIFF, and BMP with customizable camera angles and backgrounds.

• Cross-Platform & Headless Compatibility:

  • Tested and supported across Linux (Ubuntu, Debian, and Android Termux/PRoot), macOS, and Windows.
  • Intelligent OpenGL driver probe and caching system to handle headless virtual machines and software rasterization environments.

Directory Structure

cad/
├── view.py                  # Main interactive 3D CAD viewer application
├── save.py                  # Headless scene exporter, snapshot generator & CLI
├── check.py                 # Dedicated headless scene validator & health analyzer
├── bridge.py                # CollabBridge CLI for external & AI agent control
├── remesh.py                # Standalone mesh decimation & remeshing tool
├── check.sh / check.bat     # Shell launchers for headless validation
├── requirements.txt         # Core runtime dependencies
├── requirements-dev.txt     # Development and testing dependencies
├── pytest.ini               # Pytest configuration (90% coverage enforcement)
│
├── core/                    # Core engine implementation
│   ├── analysis/            # 3D printability, overhangs, bed envelopes
│   ├── bridge/              # HTTP CollabBridge server & protocol
│   ├── common/              # Global constants and progress reporting
│   ├── geometry/            # Mesh representations, transforms, STL I/O
│   ├── io/                  # Multi-format mesh exporters (STL, OBJ, GLB, etc.)
│   ├── modeling/            # CSG booleans, assemblies, sketches, remeshing
│   ├── primitives/          # Parametric shapes, text, polyline sweeps
│   ├── rendering/           # OpenGL FBO renderer, DPG viewport, gizmo, camera
│   ├── scratchpad/          # Temporary geometric canvas for experiments
│   ├── sdf/                 # Mathematical SDF models and Marching Cubes mesher
│   └── spatial/             # Raycasting, BVH, and screen-space object picking
│
├── scenes/                  # Ready-to-run procedural scene definitions
│   ├── assembly_demo.py     # Multi-part mechanical assembly with exploded view
│   ├── parametric_demo.py   # Live slider-driven parametric model
│   ├── polyline.py          # Complex 3D swept path demonstrations
│   └── test.py              # 3D primitives, text, and SDF CSG / Gyroid models
│
├── scripts/                 # Modular helper scripts
│   ├── env.sh / env.bat     # Dynamic virtual environment and path discovery
│   ├── setup_base.sh/.bat   # Unified 5-step installer backend
│   ├── check_gl.sh          # Self-testing OpenGL compatibility probe & cache
│   └── probe_gl.py          # Micro-probe for OpenGL rasterization validation
│
├── ci/                      # Continuous Integration
│   └── action.yml           # GitHub Actions composite action for CAD
│
└── tests/                   # Test suite (223 unit & integration tests)

Installation & Setup

Automated setup scripts create an isolated .venv, upgrade pip, install all requirements, and verify core library imports.

Runtime Installation (Users)

• Linux / macOS / Termux:

  ./setup.sh
  

• Windows:

  setup.bat
  

Developer Installation (Includes Testing & Coverage Tools)

• Linux / macOS / Termux:

  ./setup_dev.sh
  

• Windows:

  setup_dev.bat
  

Quick Start

1. Launching the Interactive 3D Viewer

Viewing scenes in your active project folder or custom path (view.sh / view.bat):

# By default, discovers scenes in the current terminal directory:
./view.sh

# Or specify a target directory, relative or absolute path, or standalone scene file:
./view.sh path/to/scenes/
./view.sh path/to/my_scene.py
# Windows: view.bat [path]

Running bundled repository example scenes (run.sh / run.bat):

./run.sh
# Windows: run.bat

Load a specific scene:

./run.sh -s scenes/assembly_demo.py
./run.sh -s scenes/parametric_demo.py

Viewport Navigation Controls:

• Left Mouse Click / Drag: Rotate camera around focal point / select objects in pick mode.
• Right Mouse Drag: Pan camera horizontally and vertically.
• Mouse Wheel / Scroll: Zoom in and out.
• Toolbar: Switch between Move, Rotate, Scale, and Measure tools; toggle shaded and wireframe modes; inspect object geometry.

2. Headless Scene Exporting & Snapshot Generation (save.py)

Export a scene directly to binary STL:

./save.sh -s scenes/assembly_demo.py -o output.stl

Export to OBJ, GLB, or PLY format:

./save.sh -s scenes/parametric_demo.py -e model.glb

Generate a high-resolution 4K isometric preview image with anti-aliasing:

./save.sh -s scenes/assembly_demo.py -i preview.png --resolution 3840x2160 --cam-ori iso --supersample 4

Analyze 3D printability and optimize print orientation for a Bambu Lab bed:

./save.sh -s scenes/assembly_demo.py --analyze-print --printer-bed bambu --auto-orient

Merge scene objects using Smooth Boolean Union (SDF Marching Cubes):

./save.sh -s scenes/assembly_demo.py --sdf-merge smooth_union --sdf-k 3.0 -o merged.stl

3. AI Agent CollabBridge (bridge.py)

When view.py is running, the viewer hosts an HTTP JSON endpoint on port 8765. AI agents or terminal users can query and control the application live via ./bridge.sh:

# Check viewer status and active scene
./bridge.sh status

# List all available scenes
./bridge.sh scenes

# Load a new scene dynamically
./bridge.sh scene scenes/assembly_demo.py

# Select an object by name
./bridge.sh select "BasePlate"

# Translate selected object by [+10mm X, 0mm Y, +5mm Z]
./bridge.sh translate "10,0,5"

# Adjust exploded view ratio (0.0 = assembled, 1.0 = exploded)
./bridge.sh explode 0.5

# Request a 3D printability check
./bridge.sh print-check

# Export current viewer model to disk
./bridge.sh export "exported_model.stl"

4. Headless Scene Validation & Health Analyzer (check.py / check.sh / check.bat)

Verify CAD scene files headlessly without opening an OS window. Performs import validation, scene instantiation, UI dry-run via mock DearPyGui context, geometric evaluation, and 3D printability diagnostics:

# Validate a specific scene:
./check.sh scenes/parametric_demo.py
# Windows: check.bat scenes\parametric_demo.py

# Emit machine-parseable structured JSON output:
./check.sh scenes/parametric_demo.py --json

# Validate all scenes in the workspace or custom directory:
./check.sh --all --json

# Override scene parameters for validation:
./check.sh scenes/parametric_demo.py --param length=120 --param width=80

# Strict mode (exit with code 1 on non-watertight geometry or bed limit violation):
./check.sh scenes/parametric_demo.py --strict --bed 300x300x400

5. Running Tests & Code Coverage

Execute the complete test suite:

./run_tests.sh
# Windows: run_tests.bat

• Enforced Coverage: pytest.ini requires a minimum of 90% test coverage across the core/ package; test runs below this threshold automatically fail.
• Coverage Reports: HTML reports are generated at cad/htmlcov/index.html and XML reports at cad/coverage.xml.

OpenGL Driver Compatibility & Probing

In certain virtualized, containerized, or headless environments (e.g. Android PRoot, headless CI runners, or systems without GPU drivers), default OpenGL drivers may trigger errors or lack WGL/GLX support.

The toolkit includes an automated driver probe:

• Automatic Fallback: scripts/check_gl.sh tests OpenGL rasterization via scripts/probe_gl.py and caches the result in .venv/.gallium_probe. If default Mesa llvmpipe fails, it automatically selects softpipe.
• Force Re-testing: Pass --retest-gl to any launcher script to re-evaluate the host environment:

  ./run.sh --retest-gl
  ./run_tests.sh --retest-gl
  # Or via check_gl.sh directly:
  ./scripts/check_gl.sh --retest
  

• Inspect Status:

  ./scripts/check_gl.sh --status
  

Continuous Integration

Cross-platform CI is configured in .github/workflows/cad.yml and executes on every push and pull request to main, dev/**, and release/**:

• Matrix: Ubuntu 24.04 (with Xvfb), Windows Server 2022, and macOS 14/15 on Python 3.12.
• Action: Uses the self-contained composite action in ci/action.yml.
• Artifacts: Uploads HTML coverage reports on all platforms and submits to Codecov.