Blender | PY

Overview

Blender integration for trueform mesh operations.

The trueform.bpy module integrates trueform with Blender. It provides conversion utilities for standalone scripts and a scene module with caching for add-ons with live preview.

Installation

The Blender add-on bundles trueform, the trueform.bpy integration module, and an example Boolean plugin with live preview.

Download the latest release for your platform from the GitHub Releases page:

  • trueform-bpy-plugin-windows-py311.zip — Windows (64-bit)
  • trueform-bpy-plugin-macos-arm64-py311.zip — macOS (Apple Silicon)
  • trueform-bpy-plugin-linux-py311.zip — Linux (64-bit)

Install in Blender:

  1. Edit → Preferences → Add-ons
  2. Click "Install..." and select the downloaded zip
  3. Enable "Trueform Boolean" from the list

From Source

Building from source requires a Python version matching Blender's embedded Python (e.g., Python 3.11 for Blender 4.2+).

# Use Python 3.11 (must match Blender's Python)
pip install .

# Package the add-on
python python/tools/package_blender_plugin.py \
    --plugin-init python/examples/bpy-plugin/__init__.py \
    --output trueform-bpy-plugin.zip

Then install trueform-bpy-plugin.zip in Blender as above.


Convert

Convert between Blender and trueform mesh formats.

Scene

Cached mesh operations for Blender add-ons.

Boolean Plugin

Example add-on with live preview and boolean operations.

Quick Tour

Standalone Scripts

For scripts that process meshes without live preview, use tbpy.convert to convert between formats and call trueform functions directly:

import trueform as tf
from trueform import bpy as tbpy

# Convert Blender meshes to trueform
mesh_a = tbpy.convert.from_blender(obj_a)
mesh_b = tbpy.convert.from_blender(obj_b)

# Boolean difference - returns (faces, points) tuple and labels array
# labels indicates which input mesh (0 or 1) each face originated from
(result_faces, result_points), labels = tf.boolean_difference(mesh_a, mesh_b)

# Optionally get intersection curves
(result_faces, result_points), labels, (paths, curve_points) = tf.boolean_difference(
    mesh_a, mesh_b, return_curves=True
)

# Create result mesh and convert back to Blender
result = tf.Mesh(result_faces, result_points)
new_obj = tbpy.convert.to_blender(result, name="Result")

# Optionally create curves object
curves_obj = tbpy.convert.to_blender_curves(paths, curve_points, name="Curves")

Add-ons with Live Preview

For add-ons that need cached meshes with automatic updates, use tbpy.scene:

from trueform import bpy as tbpy

def register():
    tbpy.register()  # Register scene handlers

def unregister():
    tbpy.unregister()  # Clean up handlers

# In operator/handler - uses cached meshes with world transforms
result_obj = tbpy.scene.boolean_difference(obj_a, obj_b, name="Result")

# Or with intersection curves
result_obj, curves_obj = tbpy.scene.boolean_union(obj_a, obj_b, return_curves=True)

# Low-level access to cached mesh
mesh = tbpy.scene.get(obj)  # tf.Mesh with world transform applied

The scene module:

  • Caches tf.Mesh instances per mesh datablock
  • Automatically tracks geometry changes via depsgraph
  • Rebuilds structures lazily on access (not on every change)
  • Only works for objects linked to the active scene/view layer

For detailed API documentation, see Convert and Scene.