Ad/Pr3tz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Getting ready for deploy

Browse Source
This commit is contained in:
Stefan Cepko
2026-06-04 03:49:56 -04:00
parent 61e8889354
commit c3936955ea
12 changed files with 1085 additions and 420 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+178
View File
@@ -0,0 +1,178 @@
# Pr3tz — Procedural Torus-Knot Animation for Blender
A Blender add-on that generates a continuously morphing parade of procedural [torus knots](https://en.wikipedia.org/wiki/Torus_knot) with configurable shaders, geometry transitions, and render-farm export — all driven by a non-destructive playlist inside Blender's N-panel.
---
## Features
- **20 built-in shader presets** — Gloss Blue, Neon Glow, Metallic, Glass, Hologram, Lava, Iridescent, Matte Clay, Ghost, Car Paint, Chrome, Ruby Glass, Frosted Ice, Lichen Rough, Copper Patina, Zebra Stripes, Wood Veneer, Carbon Fiber, Pearlescent, Plasma Glow
- **Playlist-based animation** — add, remove, reorder any number of knots; each entry controls its own topology, geometry, material, and animation rates
- **Smooth transitions** — configurable per-knot morph windows with Linear, Quadratic In/Out, or Smoothstep easing
- **Audio-reactive hooks** — drive the global Reactivity factor from a sound driver to pulse spin, height, and scale rates in sync with audio
- **Random playlist generator** — configure min/max ranges for every parameter and generate an entire playlist in one click
- **Bake & Export** — bake the procedural animation to a standalone `.blend` with per-frame mesh visibility keyframes; no addon required at render time; supports split-file export for SheepIt / distributed render farms
- **Blender 5.0+ native** — uses the layered Action API (`action → layers → strips → channelbag → fcurves`) and Blender 5 Principled BSDF input names directly
---
## Requirements
| Requirement | Version |
|---|---|
| Blender | **5.0** or later |
| Blender built-in addon | **Add Curve: Extra Objects** (auto-enabled by the script) |
> **Note:** The single-file version (`knot_animation.py`) has no installation step — just open and run in the Text Editor.
---
## Installation
### Option A — Persistent Add-on (recommended)
1. Download or clone this repository.
2. In Blender, go to **Edit → Preferences → Add-ons → Install…**
3. Select the `knot_animation/` **folder** (zip it first if your Blender version requires a zip).
4. Enable **"Pr3tz"** from the add-on list.
5. Open the **3D Viewport → N-panel → Pr3tz** tab.
### Option B — Run as a Script (no installation)
```
# From inside Blender's Text Editor:
# File → Open → knot_animation/__init__.py → Run Script (Alt+P)
# Or from the command line:
"C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python knot_animation/__init__.py
```
### Option C — Single-file version
`knot_animation_single_file.py` is a self-contained copy of the entire add-on in one file, useful for quick testing without touching Blender's add-on directory.
```
blender.exe --python knot_animation_single_file.py
```
---
## Quick Start
1. Install and enable the add-on (see above).
2. In the N-panel, click **"Populate Default List"** to load 10 example knots.
3. Press **Space** to play the animation and watch the knots morph.
4. Select any knot in the playlist to tweak its topology, shader, and animation rates in the panel below.
5. Use **"Generate Playlist"** with the randomiser settings to create entirely new playlists procedurally.
---
## Baking for Render Farms
The **Bake & Export** button (bottom of the Pr3tz panel) converts the procedural animation into a standalone `.blend`:
1. Set your **frame range** in the Timeline.
2. Click **Bake & Export for Render Farm** and choose an output path.
3. Optional: enable **Split Export** and set **Frames Per File** for multi-chunk jobs.
4. Submit the resulting `.blend` file(s) to your render farm — no addon needed on the farm.
---
## Module Layout
```
knot_animation/
├── __init__.py # Add-on entry point, bl_info, register/unregister
├── constants.py # Default playlist configs, camera/light positions, name tags
├── types.py # KnotConfig TypedDict (shared data contract)
├── compat.py # Headless align_matrix fix and other Blender compat patches
├── properties.py # Blender PropertyGroups (KnotItem, KnotGlobalSettings, …)
├── operators.py # KNOT_OT_* operators (Add, Remove, Move, Generate, Fit…)
├── ui.py # N-panel, UILists, draw_knot_properties()
├── geometry.py # _make_torus_knot() — pure parametric NURBS, no bpy.context reads
├── materials.py # 20 shader builders, material cache, blend/transition system
├── handler.py # @persistent frame_change_post handler, easing, playlist timing
├── scene_setup.py # setup_scene() — camera, area light, world, render settings
└── bake_export.py # KNOT_OT_BakeExport — bake to standalone .blend
```
---
## Key Parameters (KnotItem)
| Parameter | Description |
|---|---|
| **p / q** | Torus knot winding numbers — must be coprime for a true knot |
| **Major / Minor radius** | Size of the torus; switch to Ext/Int mode for exterior/interior control |
| **Bevel Depth** | Tube thickness of the curve |
| **Multiple Links** | Render all p link components separately |
| **Transition Frames** | Number of frames to morph into the next knot |
| **Cycle Rate** | Per-knot speed multiplier (>1 lingers, <1 advances faster) |
| **Spin / Rev Phase Rate** | Animate tube or orbital rotation over time |
| **Height Pulse Rate** | Oscillate the torus height — creates a breathing warp effect |
| **Scale Rate / Amplitude** | Per-knot scale oscillation frequency and amplitude |
| **Shader Preset** | One of 20 built-in material presets |
| **Project Material** | Use any material already in the .blend file |
---
## Global Settings
| Setting | Description |
|---|---|
| **Frames per Knot** | Base display duration for each playlist entry |
| **Curve Resolution** | NURBS subdivision — higher = smoother curve |
| **Bevel Resolution** | Tube cross-section segments |
| **Global Scale** | Uniform scale applied to all knots |
| **Global Speed** | Multiplies the effective frame counter — keyframeable |
| **Animation Phase** | Frame offset before all calculations — keyframeable |
| **Reactivity** | Scales all per-knot animation rates; wire a driver here for audio-reactive animation |
---
## Shader Presets Reference
| ID | Description |
|---|---|
| `GLOSS_BLUE` | Classic glossy blue dielectric |
| `NEON_GLOW` | Emissive neon with bloom-ready strength |
| `METALLIC` | Polished gold / copper metal |
| `GLASS` | Refractive clear glass |
| `HOLOGRAM` | Sci-fi translucent hologram |
| `LAVA` | Subsurface-scattered lava with emission |
| `IRIDESCENT` | Rainbow thin-film interference |
| `MATTE_CLAY` | Diffuse clay for concept previews |
| `GHOST` | Semi-transparent emission ghost |
| `CAR_PAINT` | Pearlescent automotive clearcoat |
| `CHROME` | Mirror-finish chrome |
| `RUBY_GLASS` | Deep red refractive glass |
| `FROSTED_ICE` | Rough refractive ice |
| `LICHEN_ROUGH` | Organic rough surface |
| `COPPER_PATINA` | Oxidised copper green |
| `ZEBRA_STRIPES` | Procedural stripe pattern |
| `WOOD_VENEER` | Procedural wood grain |
| `CARBON_FIBER` | Woven carbon fiber weave |
| `PEARLESCENT` | Angle-dependent pearl sheen |
| `PLASMA_GLOW` | High-energy plasma emission |
---
## Contributing
Pull requests are welcome. For major changes please open an issue first.
### Development setup
```powershell
# Clone
git clone https://github.com/YOUR_USERNAME/animknots.git
# Run the syntax checker (no Blender needed)
python check_syntax.py
```
---
## License
MIT — see [LICENSE](LICENSE) for details.