CLAUDE - sliptonic/FreeCAD GitHub Wiki

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the FreeCAD Path Workbench Development Wiki - technical documentation for FreeCAD's Computer-Aided Manufacturing (CAM) module. It documents the architecture, design patterns, and development guidelines for the Path workbench, which generates CNC toolpaths from 3D models.

Key Architectural Concepts

Intent-Strategy-Operation Model

The Path workbench separates concerns into three levels:

  • Intent: What the user wants to accomplish (e.g., "clear a pocket", "drill holes")
  • Operation: A discrete unit of work that identifies geometry, tool, and strategy
  • Strategy/Path Generator: The algorithm that produces toolpaths from geometry and tool configuration

An operation aggregates multiple features (e.g., drilling multiple holes) and delegates to a strategy for each feature. Strategies return Path Blocks (indivisible command sequences) that can be interleaved but must maintain internal ordering.

Shape Taxonomy

Operations work with different geometric input types:

  • Spot Shapes: Single-point locations (drilling operations)
  • Line-Following: Wire/edge profiles (profiling operations)
  • Area Removal: Face/solid volume clearing (pocket operations)
  • Face Decoration: Surface engraving/hatching
  • RemovedShape: Material successfully removed by operation
  • RemainderShape: Material that operation couldn't remove

Operation Class Hierarchy

The wiki documents a multi-level inheritance structure:

  • Base.ObjectOp (root)
    • CircularHoleBase → Helix, Drilling, ThreadMilling, Tapping
    • EngraveBase → Engrave, Vcarve, Deburr
    • Area.ObjectOp → Pocket, MillFace, PocketShape
    • Profile.ObjectProfile (edge profiling)
    • Adaptive, Surface, Waterline (advanced 3D)
    • Custom, Slot, Probe, Stop (specialized)

Post-processing Pipeline

The post-processing flow converts Path commands to machine-specific G-code:

  1. CommandPathPost.Activated() - Triggered by user action
  2. buildPostList() - Constructs ordered list of postable objects based on job settings (orderBy: fixture/tool/operation)
  3. exportObjectsWith() - Resolves filename and postprocessor
  4. xxx_post.py - Machine-specific post processor with export() method
  5. Output optionally split into multiple files by fixture/tool/operation

PathArea Library

Core geometric operations use libarea (ClipperLib wrapper) for:

  • Polygon offsetting (shrink/grow boundaries)
  • Pocket clearing patterns: ZigZag, Offset, Spiral, ZigZagOffset, Line, Grid, Triangle
  • Section-based 3D toolpath generation
  • Arc fitting and discretization

Key functions documented:

  • Area.add() - Boolean operations on polygons
  • Area.makeOffset() - Offset boundary curves
  • Area.makePocket() - Generate pocket clearing patterns
  • Area.makeSections() - Create 3D step-down sections
  • fromShapes() - Convert FreeCAD shapes to Path-compatible geometry

Development Guidelines

Creating New Operations

Think carefully before creating a new operation. New toolpath algorithms should usually extend existing operations, not create new ones.

Required Files (all paths relative to FreeCAD source root):

  1. src/Mod/Path/PathScripts/PathXYZ.py - Main operation logic
  2. src/Mod/Path/PathScripts/PathXYZGui.py - GUI implementation (uses subclass framework)
  3. src/Mod/Path/Gui/Resources/panels/PageOpXYZEdit.ui - Task panel UI (edit with Qt Designer)
  4. src/Mod/Path/Gui/Resources/icons/Path-XYZ.svg - Operation icon (edit with Inkscape)

Files to Modify:

  • src/Mod/Path/PathScripts/PathSelection.py - Add selection gate
  • src/Mod/Path/CMakeLists.txt - Register files (alphabetical order)
  • src/Mod/Path/InitGui.py - Register GUI commands in menus/toolbars
  • src/Mod/Path/Gui/Resources/Path.qrc - Add UI and icon resources
  • src/Mod/Path/PathScripts/PathGUIInit.py - Import GUI file

Creating Dressups

Dressups modify existing toolpaths to compensate for real-world constraints (e.g., ramping, dogbone corners, lead-in/out).

Guidelines:

  • Does it modify an existing path?
  • Does it compensate for material/machine/tool limitations?
  • Is it applicable to multiple operation types?

Required Files:

  1. src/Mod/Path/PathScripts/PathDressupABC.py - Dressup logic

Files to Modify:

  • src/Mod/Path/CMakeLists.txt
  • src/Mod/Path/InitGui.py

Creating Post Processors

Create machine-specific post processors in:

src/Mod/Path/PathScripts/post/foo_post.py

Must implement export(objectslist, filename, argstring) method that returns G-code string.

Documentation Organization

/
├── Home.md                          # Navigation hub
├── Intent-vs-Strategy.md            # Core architectural concepts
├── Shapes-in-the-Path-Workbench.md  # Geometry taxonomy
├── Postprocessing.md                # G-code generation pipeline
├── Developing-for-Path.md           # Creating operations/dressups/postprocessors
├── TaskPanel-Design.md              # UI/UX guidelines
├── PathArea-API-Reference.md        # Quick API reference (consolidated)
├── PathArea-notes.md                # Comprehensive PathArea guide
├── fromShapes.md                    # Shape conversion function
├── libarea---clipper-notes.md       # ClipperLib integration
├── Current-State/                   # Implementation status
│   ├── README.md
│   ├── Operations.md                # Class hierarchy + refactoring notes
│   ├── Dressups.md                  # Feature matrix
│   └── Generators.md                # Generator status
├── Archive/                         # Historical content
│   ├── README.md
│   ├── Translation-Cleanup-Project.md
│   └── Path-Commands.md
└── CLAUDE.md                        # This file

Note: This is a living development wiki with WIP content and planning notes.

Important Notes

  • The wiki uses mermaid diagrams for class hierarchies
  • Empty placeholder files have been deleted (will be created when content exists)
  • This is a wiki repository, not the actual FreeCAD source code
  • The actual FreeCAD source is a separate repository
  • Documentation focuses on architecture requiring multiple files to understand
  • Heavy use of tables for comparing operations against geometry types
  • All pages have navigation breadcrumbs linking to Home, Current State, and API Reference