mirror of
https://github.com/SoftFever/OrcaSlicer.git
synced 2025-12-30 19:30:40 -07:00
b16a6052cb
* re-enable tests * Add comprehensive testing guide for OrcaSlicer in CLAUDE.md * fix build errors on Win * fix appimage errors
257 lines
No EOL
9.8 KiB
Markdown
257 lines
No EOL
9.8 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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 -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:
|
|
```bash
|
|
cd build && ctest
|
|
```
|
|
|
|
Run tests with verbose output:
|
|
```bash
|
|
cd build && ctest --output-on-failure
|
|
```
|
|
|
|
Run individual test suites:
|
|
```bash
|
|
# From build directory
|
|
./tests/libslic3r/libslic3r_tests
|
|
./tests/fff_print/fff_print_tests
|
|
./tests/sla_print/sla_print_tests
|
|
```
|
|
|
|
## 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 |