Stp2Glb/CLAUDE.md

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

# 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

# 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