nodeslicer/doc/MODULES.md

Module Reference

This file provides a mapping of modules to their primary responsibilities and key symbols.

Root

• __init__.py:

  • Entry Point: Extension registration (register, unregister).
  • Node Tree: SLICETREE_NodeTree class.
  • Sockets: Definitions for all SLICESOCK_* classes.
  • Nodes: Definitions for all SLICENODE_* classes.
  • Evaluation Engine:
    • resolve_input(): Recursively evaluates linked sockets.
    • _resolve_output(): Computes node outputs with a caching system (_EvalCache) to avoid redundant calculations.
    • _follow_reroute(): Handles Blender's Reroute nodes during evaluation.

• registry.py:

  • Auto-Registration: Utility to track classes decorated with @register_class.

• blender_manifest.toml:

  • Metadata for the Blender Extension platform.

• pyproject.toml:

  • Standard Python project configuration.

/core (Geometry & Slicing)

• slice.py:

  • slice_at_range(): Top-level slicing function that iterates through Z-heights using manifold3d for guaranteed watertight solid slicing (resolving coplanar and floating-point degeneracies) with a fallback to trimesh multiplane slicing for open sheets (supports ignore_holes option).
  • _slice_single_mesh(): Mesh slicer implementing manifold3d solid slicing and trimesh multiplane intersection with micro-epsilon perturbation at boundary faces.
  • align_path_seam_sharpest(): High-performance vectorized heuristic that positions the start vertex (seam) of closed polygon loops at the back of the object (+Y) with corner sharpness preference.
  • SlicePaths.align_seams(): Method on SlicePaths to align path seams to the back (+Y) while preserving per-vertex attributes and metadata.
  • Pather: Class that converts toolpaths into G-code strings. Supports per-segment extrusion rates, feedrates, and custom extra attributes.
  • segments_to_slice(): Utility to convert raw intersection segments into continuous paths (closed polygons are processed via Pyclipper, supports ignore_holes, open paths remain open).
  • link_segments(): Logic for joining loose segments into continuous paths.
  • buffer_slice(): Offset utility using PyclipperOffset. Supports rotated offsetting.
  • buffer_multiple_slice(): High-performance single-pass multi-shell concentric offset utility for slicing layers.
  • infill_slice(): Generates rotated grid or rectilinear infill patterns, ensuring layer-to-layer consistency.
  • boolean_slice(): Performs 2D boolean operations (Union, Intersection, Subtract, XOR) on slice sets with hole support.
  • path_operations_slice(): Unified dispatcher for multi-input path operations (ZIP, EXTEND, MAX_COVERAGE, MIN_COVERAGE, SUBTRACT, XOR). Supports acquire_transforms to align secondary paths with primary transforms.
  • apply_transforms_to_slice_paths(): Applies a list of transformation dicts (scale, rotation, translation) to a SlicePaths object.
  • extract_geometry_transforms(): Consolidates transformation metadata from SlicePaths, SlicingObject, SlicingCollection, SlicingGroup, or Blender objects into translation, rotation (radians), and scale tuples.
  • minimum_coverage_slice(): Computes layer-by-layer intersection across multiple inputs while preserving single-path/input layers.
  • maximum_coverage_slice(): Computes layer-by-layer union across multiple inputs.

• geometry.py:

  • Geometry utility functions.

/core/pdf_exporter (PDF Export & Technical Marking Engine)

• sa2_measures.py:
  • render_sa2_measures_pdf(): ISO 129-1 technical marking engine.
  • extract_slicing_object_features(): Feature detection for circular bores (Ø), arcs (R), chamfers (C), and steps.
• writer.py:
  • export_mesh_to_pdf: Class for building scalable 1:1 vector PDF files. Uses a modular element architecture with element subclasses (PDFElement, PDFLegendElement, PDFHeaderTableElement, PDFGridElement, PDFGeometryElement, PDFBoundingBoxElement, PDFSA2MeasuresElement, PDFObjectLabelsElement, PDFBackgroundElement).
  • format_pdf_filename_template: Formats file naming templates with placeholders for object names, whole PDF dimensions in mm ({size_x_mm}, {size_y_mm}), and ISO dates ({today_date_iso}).

/infra (Blender Integration)

• blender_mesh_capture.py:

  • PdfProperties: Dataclass holding PDF line width and line color attributes for a SlicingObject.
  • SlicingObject: Represents a single mesh as a NumPy triangle array.
  • capture_mesh_edges(): Extracts edges from a Blender mesh for path-based workflows. Supports capturing extra per-vertex attributes.

• blender_slice_nodes_generic.py:

  • Base classes for NodeSlicer nodes (SliceNode) and sockets (SliceNodeSocket).
  • Native Blender socket type mappings (NodeSocketFloat, NodeSocketInt, NodeSocketVector, NodeSocketRotation, NodeSocketString, NodeSocketObject, NodeSocketGeometry).
  • Core evaluation logic (resolve_input).
  • Profiling tools (NodeProfiler, profile_node_execution).

• debug.py:

  • @debug: Decorator for Node classes, evaluate_output methods, or functions to dump execution state, input sockets, properties, outputs, and errors.
  • dump_node_execution(): Serializes node execution state to JSON, formatted text report, and Python pickle.
  • get_last_debug_dump() / get_last_debug_text() / load_last_inputs(): Utilities to review and reload the most recent execution dump for debugging.
  • debug_session(): Context manager enabling execution capture across node evaluations.
  • SLICENODE_OT_DebugDump: Blender operator (slicenode.debug_dump) to dump the active node's inputs on demand.

• list_utils.py:

  • is_list_data(): Type discrimination distinguishing list/tuple collections from atomic objects (such as SlicePaths).
  • is_vector_value(): Distinguishes atomic 3D vectors/rotations from lists of vectors.
  • is_input_a_list(): Determines if a raw input is a list, accounting for vector socket types.
  • flatten_list(): Recursive flattener for multi-input joiners and batch sinks.
  • eval_element_wise(): Vectorized applicator executing operations element-wise on lists or directly on single items.
  • prepare_indexed_inputs(): Normalizes and matches secondary inputs index-per-index against the primary input, broadcasting single values or validating that list lengths match exactly (raising ValueError on mismatch).
  • eval_element_wise_multivalue(): General element-wise operator executing multi-argument operations with index matching and broadcasting.
  • set_socket_shape() / is_socket_linked_to_list() / is_output_socket_a_list() / sync_node_list_sockets(): Dynamic socket visual appearance management (LIST vs CIRCLE).