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
.jsonformat, so that version control such asgitcan properly track changes in a node tree rather than a single binary.blendfile - 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 collaboration between users
More to come once we actually finish building.
The following features are already available:
- Enables export/import of node trees,
Geometry-,Shader-,Compositor-, andTextureNodeTrees. - Either plain JSON or compressed strings of the form
TreeClipper::<base64>. - The trees' interfaces are included.
- For compositor trees, scene attributes are stored and verified on import.
- Explicit interface for referenced "external" items that are not part of the export.
- The core logic is available as PyPI Package.
We aim to maintain backwards compatibility, and in principle custom node trees can also be supported.
We plan to support the remaining, more niche node trees as well. For example, node based worlds.
We plan to publish the extension on the official site soon.
In the meantime, you can download the latest release: scroll down and download the tree_clipper-x.x.x.zip file, then drag and drop into Blender.
Alternatively, you can add a repository and get automatic updates, for the URL use:
https://github.com/Algebraic-UG/tree_clipper/releases/latest/download/index.json
There are several projects that are similar, the ones we're aware of include
Node To Python differs in that it uses Python code as storage. While this alleviates the need of a dependency for import (other than Blender itself), it is inherently not backwards-compatible and doesn't allow reading without Blender. (There is a plan to support JSON export)
NodeKit is not developed actively anymore, and the author instead advises development of Tree Clipper.
Copy/Paste Nodes appears to have a different scope. It supports copying nodes into a tree directly. Tree Clipper doesn't do this, see also this issue. There's also no documented way to re-use the core logic in another addon.
Node Kit appears to be similar. It differs in distribution, as it is sold on Superhive ($15 at the time of writing).
In comparison to Tree Clipper, nodebpy, geometry-script, and geonodes are different as they do not support exporting trees from Blender, but rather make it easier to define nodes from Python.
The core logic is available as a PyPI package. For more info, check out this README.md.
Testing leverages pytest, also see the CI setup.
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 within Git LFS are optional unless you want to test Tree Clipper.
| 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 |
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.
It is recommended to use vscode with these extensions:
uv is also required for this workflow.
Ideally, the core logic of Tree Clipper should not be used directly as a dependency in downstream addons, 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 potentially 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:
- The editable core logic is in packages/tree_clipper/, and the vendorized code 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.
- Depending on your version of the Blender Development addon (whether it has this change), the task
run-python-vendormust run before starting Blender. Subsequent reloads will do this automatically.