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/functions (Pure Logic & Reusable Functions)

• mesh_functions.py: Reusable mesh transformations, deep copying, attribute evaluation, naming templates, and PDF property assignment.
• path_functions.py: Pure-logic slicing functions (_slice_single_mesh_item, _finish_slice_paths, _slice_single_mesh_item_with_layers).
• gcode_functions.py: G-code generation, metadata formatting, regex replacement, command formatting, join logic, and file loading.
• math_functions.py: Math operations lookup and evaluation for float and int math nodes.
• preview_functions.py: G-code parsing logic extracting vertices, edges, extrusions, and preparation metadata.

/core/nodeslicer (Node Definitions & Tree Infrastructure)

• tree.py:

  • SLICETREE_NodeTree: Custom node tree type for NodeSlicer nodes.

• nodes/:

  • base.py: Base classes (SliceNode, SliceNodeJoiner, SliceNodeListJoiner, ExecSliceNode), geometry wrappers, and evaluation utilities.
  • inputs/: Individual input node modules (input_string, input_float, input_int, input_vector, input_vector_rotation, input_object, objects_to_list, collection_objects, input_settings, input_printer, input_intrinsics).
  • math/: Math node modules (float_math, int_math).
  • mesh/: Mesh processing node modules (arrange_mesh, assign_pdf_properties, assign_property_to_object, drop_geometry, get_mesh, get_transforms, group_to_list, join_mesh_groups, join_mesh, list_to_group, meshes_to_list, rename_mesh, separate_mesh_by_range, separate_mesh, transform_geometry).
  • path/: Slicing and toolpath generation node modules (anchor_paths, buffer_curve, buffer_shells, buffer_shells_multiple, flatten_path_list, get_paths, infill, layers, offset_curve, overhang_mask, path_offset, path_operations, paths_to_list, rotate_path, seam_placement, simplify_paths, slice_shells, slice_shells_layers).
  • gcode/: G-code operations and generation node modules (export_gcode, gcode_find_replace, gcode_to_list, gcode_to_path, join_gcode, load_gcode, modify_gcode, paths_to_gcode).
  • output/: Output and external export node modules (airtable_submit, baserow_submit, gcode_to_file, gcode_to_text_block, mesh_to_pdf, start_print).
  • system/: Execution and flow control node modules (executor, join_execution, join_settings, printer_list, test).
  • preview/: G-code preview and visualization node modules (gcode_to_mesh).

/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 & Infrastructure)

• error_reporting/:

  • formatter.py: Node description and socket introspection (get_node_input_names, format_node_failure_message, _format_node_description).
  • proxy.py: Operator error reporting proxy (NodeErrorReportingProxy, wrap_operator_for_node).
  • handler.py: Modular error handler (attach_node_failure_info, NodeErrorHandler, handle_node_errors, node_execution_scope).

• profiling/:

  • node_profiler.py: Core profiler class (NodeProfiler, get_node_type, global profiler tracking).
  • execution.py: Modular profiling execution context and decorator (profiler_context, profile_node_execution, NodeProfileExecution).
  • text_editor.py: Display profiler table in Blender Text Editor (show_in_text_editor).

• 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) and custom path picker sockets (SLICESOCK_DirPath, SLICESOCK_FilePath).
  • Socket creation utilities (add_input, add_output) with support for subtype='DIR_PATH' (folder picker) and subtype='FILE_PATH' (file picker).
  • Core evaluation logic (resolve_input, _resolve_output).

• 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() / sync_tree_socket_shapes(): Dynamic socket visual appearance management (LIST vs CIRCLE) and tree-wide propagation.