# CLAUDE.md

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

## Project Overview

STP2GLB is a C++20 command-line tool that converts STEP (CAD) files to GLB (glTF binary) format for 3D visualization. The core conversion pipeline uses OpenCASCADE Technology (OCCT) for CAD geometry processing and outputs to GLB via tinygltf.

## Build System and Commands

This project uses Pixi for package management and CMake with presets for building. All development should occur within Pixi environments.

### Essential Commands
```bash
# Setup environment
pixi install
pixi shell

# Development builds (with debugging symbols)
pixi run build                    # Windows dynamic release
pixi run install                  # Install after build
pixi run -e dynamic-debug build   # Debug build with symbols
pixi run -e dynamic-debug install

# Testing
pixi run test                     # Run all tests
pixi run -e dynamic-debug test    # Run tests with debug build
ctest --test-dir build/win-dynamic-release  # Direct CTest execution

# Production builds (static linking)
pixi run -e static build
pixi run -e static install
```

### Manual Testing
```bash
# Basic conversion
STP2GLB.exe --stp input.stp --glb output.glb

# Debug mode (provides detailed STEP entity failure information)  
STP2GLB.exe --stp input.stp --glb output.glb --debug

# Advanced options
STP2GLB.exe --stp input.stp --glb output.glb --lin-defl 0.1 --ang-defl 0.5 --solid-only --max-geometry-num 100
```

## Architecture Overview

### Core Data Flow
1. **CLI Parsing** (`main.cpp`) → **Configuration** (`config_structs.h`, `config_utils.cpp`)
2. **STEP Reading** (`cadit/occt/step_helpers.cpp`) → **Geometry Processing** (`cadit/occt/convert.cpp`)
3. **Tessellation & Filtering** → **GLB Output** (`cadit/occt/gltf_writer.cpp`)

### Key Modules
- **`src/cadit/occt/`**: OpenCASCADE integration layer
  - `convert.cpp`: Main conversion pipeline (`convert_stp_to_glb()`, `debug_stp_to_glb()`)
  - `step_tree.cpp`: STEP file hierarchical processing
  - `gltf_writer.cpp`: GLB format output generation
  - `step_helpers.cpp`: STEP entity manipulation utilities
  - `helpers.cpp`: OCCT geometry utilities

- **`src/geom/`**: Abstract geometry data structures
  - Mesh, Color, and geometric primitives
  - Bridge between OCCT and output formats

### Build Configurations
The project supports multiple build modes via CMake presets:
- **Dynamic builds**: For development (faster builds, shared libraries)
- **Static builds**: For distribution (single executable, slower builds)
- **Debug vs Release**: Debug includes detailed STEP entity failure reporting

### Dependencies Architecture
- **OpenCASCADE 7.8.1**: CAD kernel for STEP reading and geometry processing
- **CGAL 5.6.1**: Computational geometry algorithms  
- **CLI11**: Command-line argument parsing
- **tinygltf 2.8.19**: GLB/glTF file format handling
- **nlohmann_json**: JSON processing for glTF structure

## Development Patterns

### Error Handling Strategy
The codebase uses two conversion modes:
- **Standard mode**: Fast conversion with basic error handling
- **Debug mode** (`--debug` flag): Slower but provides detailed reporting of which STEP entities failed to convert and why

### Configuration Management
All runtime parameters flow through `GlobalConfig` struct, populated via CLI11 from command-line arguments. This centralized configuration pattern should be maintained for new features.

### Testing Strategy
Tests are defined in `tests/tests.cmake` and use actual STEP files from `files/` directory. New features should include corresponding test cases with real geometry files when possible.

### Code Style
- Snake_case for functions and variables (`convert_stp_to_glb`, `linear_deflection`)
- PascalCase for classes/structs (`GlobalConfig`, `BuildConfig`)
- Use RAII and C++20 features appropriately
- Prefer exceptions for error handling in conversion pipeline