OrcaSlicer/CLAUDE.md

CLAUDE.md

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

Overview

OrcaSlicer is an open-source 3D slicer application forked from Bambu Studio, built using C++ with wxWidgets for the GUI and CMake as the build system. The project uses a modular architecture with separate libraries for core slicing functionality, GUI components, and platform-specific code.

Build Commands

Building on Windows

# Build everything
build_release_vs2022.bat

# Build with debug symbols
build_release_vs2022.bat debug

# Build only dependencies
build_release_vs2022.bat deps

# Build only slicer (after deps are built)
build_release_vs2022.bat slicer

Building on macOS

# Build everything (dependencies and slicer)
./build_release_macos.sh

# Build only dependencies
./build_release_macos.sh -d

# Build only slicer (after deps are built)
./build_release_macos.sh -s

# Use Ninja generator for faster builds
./build_release_macos.sh -x

# Build for specific architecture
./build_release_macos.sh -a arm64    # or x86_64 or universal

# Build for specific macOS version target
./build_release_macos.sh -t 11.3

Building on Linux

# First time setup - install system dependencies
./build_linux.sh -u

# Build dependencies and slicer
./build_linux.sh -dsi

# Build everything (alternative)
./build_linux.sh -dsi

# Individual options:
./build_linux.sh -d    # dependencies only
./build_linux.sh -s    # slicer only  
./build_linux.sh -i    # build AppImage

# Performance and debug options:
./build_linux.sh -j N  # limit to N cores
./build_linux.sh -1    # single core build
./build_linux.sh -b    # Debug build
./build_linux.sh -e    # RelWithDebInfo build
./build_linux.sh -c    # clean build
./build_linux.sh -r    # skip RAM/disk checks
./build_linux.sh -l    # use Clang instead of GCC

Build System

• Uses CMake with minimum version 3.13 (maximum 3.31.x on Windows)
• Primary build directory: build/
• Dependencies are built in deps/build/
• The build process is split into dependency building and main application building
• Windows builds use Visual Studio generators
• macOS builds use Xcode by default, Ninja with -x flag
• Linux builds use Ninja generator

Testing

Tests are located in the tests/ directory and use the Catch2 testing framework. Test structure:

• tests/libslic3r/ - Core library tests (21 test files)
  • Geometry processing, algorithms, file formats (STL, 3MF, AMF)
  • Polygon operations, clipper utilities, Voronoi diagrams
• tests/fff_print/ - Fused Filament Fabrication tests (12 test files)
  • Slicing algorithms, G-code generation, print mechanics
  • Fill patterns, extrusion, support material
• tests/sla_print/ - Stereolithography tests (4 test files)
  • SLA-specific printing algorithms, support generation
• tests/libnest2d/ - 2D nesting algorithm tests
• tests/slic3rutils/ - Utility function tests
• tests/sandboxes/ - Experimental/sandbox test code

Run all tests after building:

cd build && ctest

Run tests with verbose output:

cd build && ctest --output-on-failure

Run individual test suites:

# From build directory
ctest --test-dir ./tests/libslic3r/libslic3r_tests
ctest --test-dir ./tests/fff_print/fff_print_tests
ctest --test-dir ./tests/sla_print/sla_print_tests
# and so on

Architecture

Core Libraries

• libslic3r/: Core slicing engine and algorithms (platform-independent)

  • Main slicing logic, geometry processing, G-code generation
  • Key classes: Print, PrintObject, Layer, GCode, Config
  • Modular design with specialized subdirectories:
    • GCode/ - G-code generation, cooling, pressure equalization, thumbnails
    • Fill/ - Infill pattern implementations (gyroid, honeycomb, lightning, etc.)
    • Support/ - Tree supports and traditional support generation
    • Geometry/ - Advanced geometry operations, Voronoi diagrams, medial axis
    • Format/ - File I/O for 3MF, AMF, STL, OBJ, STEP formats
    • SLA/ - SLA-specific print processing and support generation
    • Arachne/ - Advanced wall generation using skeletal trapezoidation

• src/slic3r/: Main application framework and GUI

  • GUI application built with wxWidgets
  • Integration between libslic3r core and user interface
  • Located in src/slic3r/GUI/ (not shown in this directory but exists)

Key Algorithmic Components

• Arachne Wall Generation: Variable-width perimeter generation using skeletal trapezoidation
• Tree Supports: Organic support generation algorithm
• Lightning Infill: Sparse infill optimization for internal structures
• Adaptive Slicing: Variable layer height based on geometry
• Multi-material: Multi-extruder and soluble support processing
• G-code Post-processing: Cooling, fan control, pressure advance, conflict checking

File Format Support

• 3MF/BBS_3MF: Native format with extensions for multi-material and metadata
• STL: Standard tessellation language for 3D models
• AMF: Additive Manufacturing Format with color/material support
• OBJ: Wavefront OBJ with material definitions
• STEP: CAD format support for precise geometry
• G-code: Output format with extensive post-processing capabilities

External Dependencies

• Clipper2: Advanced 2D polygon clipping and offsetting
• libigl: Computational geometry library for mesh operations
• TBB: Intel Threading Building Blocks for parallelization
• wxWidgets: Cross-platform GUI framework
• OpenGL: 3D graphics rendering and visualization
• CGAL: Computational Geometry Algorithms Library (selective use)
• OpenVDB: Volumetric data structures for advanced operations
• Eigen: Linear algebra library for mathematical operations

File Organization

Resources and Configuration

• resources/profiles/ - Printer and material profiles organized by manufacturer
• resources/printers/ - Printer-specific configurations and G-code templates
• resources/images/ - UI icons, logos, calibration images
• resources/calib/ - Calibration test patterns and data
• resources/handy_models/ - Built-in test models (benchy, calibration cubes)

Internationalization and Localization

• localization/i18n/ - Source translation files (.pot, .po)
• resources/i18n/ - Runtime language resources
• Translation managed via scripts/run_gettext.sh / scripts/run_gettext.bat

Platform-Specific Code

• src/libslic3r/Platform.cpp - Platform abstractions and utilities
• src/libslic3r/MacUtils.mm - macOS-specific utilities (Objective-C++)
• Windows-specific build scripts and configurations
• Linux distribution support scripts in scripts/linux.d/

Build and Development Tools

• cmake/modules/ - Custom CMake find modules and utilities
• scripts/ - Python utilities for profile generation and validation
• tools/ - Windows build tools (gettext utilities)
• deps/ - External dependency build configurations

Development Workflow

Code Style and Standards

• C++17 standard with selective C++20 features
• Naming conventions: PascalCase for classes, snake_case for functions/variables
• Header guards: Use #pragma once
• Memory management: Prefer smart pointers, RAII patterns
• Thread safety: Use TBB for parallelization, be mindful of shared state

Common Development Tasks

Adding New Print Settings

1. Define setting in PrintConfig.cpp with proper bounds and defaults
2. Add UI controls in appropriate GUI components
3. Update serialization in config save/load
4. Add tooltips and help text for user guidance
5. Test with different printer profiles

Modifying Slicing Algorithms

1. Core algorithms live in libslic3r/ subdirectories
2. Performance-critical code should be profiled and optimized
3. Consider multi-threading implications (TBB integration)
4. Validate changes don't break existing profiles
5. Add regression tests where appropriate

GUI Development

1. GUI code resides in src/slic3r/GUI/ (not visible in current tree)
2. Use existing wxWidgets patterns and custom controls
3. Support both light and dark themes
4. Consider DPI scaling on high-resolution displays
5. Maintain cross-platform compatibility

Adding Printer Support

1. Create JSON profile in resources/profiles/[manufacturer].json
2. Add printer-specific start/end G-code templates
3. Configure build volume, capabilities, and material compatibility
4. Test thoroughly with actual hardware when possible
5. Follow existing profile structure and naming conventions

Dependencies and Build System

• CMake-based with separate dependency building phase
• Dependencies built once in deps/build/, then linked to main application
• Cross-platform considerations important for all changes
• Resource files embedded at build time, platform-specific handling

Performance Considerations

• Slicing algorithms are CPU-intensive, profile before optimizing
• Memory usage can be substantial with complex models
• Multi-threading extensively used via TBB
• File I/O optimized for large 3MF files with embedded textures
• Real-time preview requires efficient mesh processing

Important Development Notes

Codebase Navigation

• Use search tools extensively - codebase has 500k+ lines
• Key entry points: src/OrcaSlicer.cpp for application startup
• Core slicing: libslic3r/Print.cpp orchestrates the slicing pipeline
• Configuration: PrintConfig.cpp defines all print/printer/material settings

Compatibility and Stability

• Backward compatibility maintained for project files and profiles
• Cross-platform support essential (Windows/macOS/Linux)
• File format changes require careful version handling
• Profile migrations needed when settings change significantly

Quality and Testing

• Regression testing important due to algorithm complexity
• Performance benchmarks help catch performance regressions
• Memory leak detection important for long-running GUI application
• Cross-platform testing required before releases