nodeslicer/GEMINI.md

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:

./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: 2D polygon operations via Pyclipper use a SCALE factor (defined in core/slice.py) to convert floats to integers, as Pyclipper operates in integer space.
• 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.