fluencyCAD/WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

Fluency is a CAD (Computer Aided Design) application built with Python/PySide6 that provides parametric 3D modeling through a timeline-based project system. The application combines 2D sketching with constraint solving, 3D visualization using VTK, and SDF (Signed Distance Function) based mesh generation.

Common Commands

Development Environment Setup

# Activate virtual environment (if exists)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Running the Application

# Run the main application
python main.py

# Run with debugging
python -u main.py

UI Development

# Convert Qt Designer UI file to Python code
pyside6-uic gui.ui > Gui.py -g python

Building Executable

The project uses Nuitka for compilation (configured in main.py header):

# Build standalone executable
nuitka --standalone --plugin-enable=pyside6 --plugin-enable=numpy --macos-create-app-bundle main.py

Testing

# Run mesh generation test
python meshtest.py

Architecture Overview

Core Components

Main Application (main.py)

• MainWindow: Central UI controller that manages all widgets and user interactions
• Project System: Hierarchical structure: Project → Timeline → Component → Sketch/Body
• Signal-based Communication: Qt signals coordinate between 2D sketching and 3D rendering

Project Hierarchy

Project
├── Timeline (list of Components)
└── Component
    ├── Sketches (dict)
    ├── Bodies (dict) 
    └── Connectors (for assembly)

Drawing Modules (drawing_modules/)

• SketchWidget (draw_widget_solve.py): 2D parametric sketching with SolverSpace constraint solving
• VTKWidget (vtk_widget.py): 3D visualization and mesh interaction using VTK
• PyVistaWidget (vysta_widget.py): Alternative 3D rendering backend

Mesh Generation (mesh_modules/)

• VESTA (vesta_mesh.py): Multi-threaded SDF-to-mesh conversion using marching cubes
• Interactor Mesh (interactor_mesh.py): Simplified edge-based meshes for 3D selection
• Simple Mesh (simple_mesh.py): Basic mesh utilities

Data Flow Architecture

2D to 3D Pipeline

1. 2D Sketching: User draws in SketchWidget using Qt coordinate system
2. Constraint Solving: SolverSpace resolves geometric constraints
3. SDF Generation: Sketch converted to Signed Distance Functions for 3D operations
4. Mesh Generation: VESTA generates triangle meshes from SDF using marching cubes
5. 3D Rendering: VTK displays both solid meshes and interactive edges

Signal Flow (from doc/flow.md)

• 2D QPoint → cartesian space → SolverSpace dict → constraint solving → display
• 3D mesh selection → projection to 2D → sketch widget integration

Key Classes

Core Data Structures

• Sketch: 2D geometric data with origin, normal, points, and constraints
• Body: 3D mesh representation containing SDF objects and interactor meshes
• Component: Container grouping related sketches and bodies
• Interactor: Simplified edge-based mesh for 3D manipulation

Constraint Solving

The application uses python_solvespace for parametric constraint solving:

• Point-to-point constraints
• Distance constraints
• Horizontal/vertical line constraints
• Point-to-line constraints

Technology Stack

• GUI: PySide6 (Qt for Python)
• 3D Graphics: VTK for rendering, PyVista as alternative
• Constraint Solving: SolverSpace for parametric geometry
• Mesh Generation: SDF library with custom VESTA marching cubes implementation
• Scientific Computing: NumPy for mathematical operations

Development Workflow

Adding New Sketch Tools

1. Add UI button in gui.ui
2. Convert UI: pyside6-uic gui.ui > Gui.py -g python
3. Connect signal in MainWindow.__init__()
4. Implement tool logic in SketchWidget

Adding New 3D Operations

1. Extend operation buttons in the Modify group
2. Implement operation logic using SDF functions
3. Update Body creation and timeline management
4. Handle interactor mesh generation for selection

Debugging Tips

• Monitor solver results through SolverSystem status
• Use VTK's built-in debugging for rendering issues
• Check coordinate transformations between 2D sketch and 3D space
• Verify SDF function outputs before mesh generation

File Structure

• main.py: Application entry point and main window
• Gui.py: Auto-generated UI code (do not edit directly)
• gui.ui: Qt Designer UI definition file
• drawing_modules/: 2D and 3D rendering widgets
• mesh_modules/: Mesh generation and processing
• doc/: Architecture and command documentation

Dependencies

Primary external libraries:

• PySide6: Qt GUI framework
• vtk: 3D visualization toolkit
• python-solvespace: Constraint solving
• sdf: Signed Distance Function operations
• numpy: Numerical computations
• scikit-image: Marching cubes algorithm
• names: Random name generation for sketches