NodeSlicer Agent Instructions

Project Overview

NodeSlicer is a high-performance Blender extension providing a custom node-based interface for mesh slicing and G-code generation.

Critical Context

Purpose: 3D printing slicing, CNC toolpathing, and procedural geometry tasks
Main Technologies: Python, Blender API (bpy), NumPy, Pyclipper, Shapely
Blender Version: 4.2 or newer (required for the Extension platform)
Architecture: Separates Blender-specific UI and data capture (infra/) from core geometric and slicing algorithms (core/)

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.

Performance

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.

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.
core/geometry.py: Shared geometry utility functions.
infra/blender_mesh_capture.py: Logic for extracting mesh data from Blender objects into NumPy arrays.
infra/blender_slice_nodes_generic.py: Base classes for the node system and the evaluation logic (resolve_input).
doc/: Comprehensive documentation on modules and nodes.

Commands

Build the extension: ./build.sh (generates a zip file in the release/ directory)
Install dependencies: uv sync

Testing & Token Efficiency

Tests are located in the tests/ directory
Requires the virtual environment: source .venv/bin/activate or .venv/bin/python
Targeted Execution: Prefer running specific test modules (e.g. .venv/bin/python -m unittest tests.test_pdf_exporter) over running full test discovery.
Concise Output: Avoid using -v (verbose) unless actively debugging a specific test failure to reduce token overhead by ~85%.
Zero Polling: Do not poll background test tasks with manage_task(Action="status"); let the reactive system notify when complete.

2.9 KiB Raw Blame History