Tree Clipper

Easier version control and sharing of node trees via .json or copy-pasteable strings.

Sharing node trees between users and in communities usually involves screenshots of node setups (which a user has to try and exactly re-create manually) or .blend files which can be cumbersome (and a security risk) to download and append relevant data blocks to scenes.

Tree Clipper aims to improve two main workflows:

• Storage of large collections of nodes in .json format, so that version control such as git can properly track changes in a node tree rather than a single binary .blend file
• Sharing of node groups in communities like Discord and Stack Exchange. Users can share a 'magic string' which will be de-serialized into a node tree by the add-on, enabling rapid sharing and collaborating between users

More to come once we actually finish building.

PyPI Package

The core logic is available as a PyPI package. For more info check out this README.md.

Testing

Testing leverages pytest, also see the CI setup.

Binary Blend Files

The directory packages/tree_clipper/tests/binary_blend_files/ contains binary blend files with relatively big node groups from various sources. In certain cases, the files are generated from an add-on.

Note that these files are within Git LFS and optional unless you want to test Tree Clipper.

Sources & Attribution

Source	Description	License	Link
Erindale’s Nodevember	Procedural awesomeness	CC0 (public domain)	Patreon Collection
Molecular Nodes	Molecular animation toolbox	GPLv3	GitHub
Microscopy Nodes	Microscopy data handling	GPLv3	GitHub
Typst Importer	Render Typst content in Blender	GPLv3	GitHub
Squishy Volumes	Material Point Method (MPM) in Blender	GPLv3	GitHub

Licensing/permission

Included assets are used with permission from the respective authors for testing purposes in this repository. If you reuse or redistribute them, please follow each project’s license/terms and attribution requirements.

Development

It is recommended to use vscode with these extensions:

• ruff
• ty
• Python Debugger
• Blender Development

uv is also required for this workflow.

Vendorizing Tree Clipper

Ideally, the core logic of Tree Clipper is not used as dependency in downstream addons directly and it should be vendorized instead. This is what the Tree Clipper Addon does as well.

The motivation for this is that we expect other addons like Squishy Volumes to use an incompatible version of Tree Clipper. Vendoring avoids version conflicts and ensures that all addons can load.

Important

Vendoring currently has two drawbacks developers must be aware of:

1. There is the editable code of the core logic in packages/tree_clipper/ and there's the vendorized code which will reside in packages/tree_clipper_addon/src/tree_clipper_addon/_vendor/. The vendorized code runs and can be debugged, but should not be edited directly.
2. Depending on your version of the Blender Development addon (whether it has this change), the task run-python-vendor must run before starting Blender. Subsequent reloads will do this automatically.