57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
# NodeSlicer
|
|
|
|
NodeSlicer is a high-performance Blender extension providing a custom node-based interface for mesh slicing and G-code generation. It leverages NumPy for vectorized geometry processing and Pyclipper for robust 2D polygon operations.
|
|
|
|
## Project Overview
|
|
|
|
- **Purpose**: 3D printing slicing, CNC toolpathing, and procedural geometry tasks.
|
|
- **Main Technologies**: Python, Blender API (`bpy`), NumPy, Pyclipper, Shapely.
|
|
- **Architecture**: Separates Blender-specific UI and data capture (`infra/`) from core geometric and slicing algorithms (`core/`).
|
|
|
|
## Building and Running
|
|
|
|
### Requirements
|
|
- Blender 4.2 or newer (required for the Extension platform).
|
|
- `uv` for Python dependency management.
|
|
|
|
### Development Setup
|
|
1. Clone the repository.
|
|
2. Run `uv sync` to install development dependencies (like `fake-bpy-module`).
|
|
|
|
### Building the Extension
|
|
Run the build script to package the addon:
|
|
```bash
|
|
./build.sh
|
|
```
|
|
This generates a zip file in the `release/` directory using Blender's extension build system.
|
|
|
|
### Installation
|
|
1. Open Blender.
|
|
2. Go to `Edit > Preferences > Extensions`.
|
|
3. Click the arrow in the top right and select `Install from Disk`.
|
|
4. Select the generated zip from the `release/` folder.
|
|
|
|
## Project Structure
|
|
|
|
- `__init__.py`: Main entry point. Defines the `NodeSlicer Tree`, custom Sockets, and all Nodes.
|
|
- `registry.py`: Utility for automatic registration of Blender classes using the `@register_class` decorator.
|
|
- `core/`:
|
|
- `slice.py`: Core slicing engine (plane-mesh intersection), buffering (offsetting), and infill generation.
|
|
- `geometry.py`: Shared geometry utility functions.
|
|
- `infra/`:
|
|
- `blender_mesh_capture.py`: Logic for extracting mesh data from Blender objects into NumPy arrays.
|
|
- `blender_slice_nodes_generic.py`: Base classes for the node system and the evaluation logic (`resolve_input`).
|
|
- `doc/`: Comprehensive documentation on modules and nodes.
|
|
|
|
## Development Conventions
|
|
|
|
- **Registration**: All Blender classes (Nodes, Sockets, Operators, Menus) must be decorated with `@register_class` from `registry.py` to ensure they are registered correctly during initialization.
|
|
- **Node Evaluation**: Nodes follow a pull-based evaluation model. Use `resolve_input(self.inputs.get("SocketName"))` within a node's `evaluate_output` method to trigger the evaluation of upstream nodes.
|
|
- **NumPy First**: For any geometry processing, prioritize NumPy vectorized operations over standard Python loops to maintain high performance.
|
|
- **Scaling & Integer Math**: 2D polygon and geometric operations use a `SCALE = 1000` factor (defined in `core/slice.py`) representing 1 micron ($1\ \mu\text{m} = 0.001\text{ mm}$) integer math units to eliminate floating-point precision issues.
|
|
- **Type Hinting**: Use exhaustive type hints for all new functions and classes.
|
|
- **Documentation**: Update `doc/NODES.md` when adding new nodes and `doc/MODULES.md` when adding new modules.
|
|
- **Token-Efficient Testing**:
|
|
- Run specific test modules (e.g. `.venv/bin/python -m unittest tests.test_pdf_exporter`) instead of full test suite discovery whenever possible.
|
|
- Omit the `-v` (verbose) flag unless actively debugging a test failure.
|
|
- Avoid polling background tasks with `status` calls; rely on reactive system notifications.
|