# Pr3tz — Procedural Torus-Knot Animation for Blender

![Pr3tz cover](docs/cover.png)

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

- **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
- **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
- **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) |
---

## Installation & Running

### Option A — Persistent Add-on (Recommended for Users)

1. Download a release zip (or run `package_addon.py` to build one).
2. In Blender, go to **Edit → Preferences → Get Extensions → Add-ons** (or **Install from Disk...** from the top right gear menu).
3. Select the zip file (e.g. `releases/pr3tz_v2.0.0.zip`).
4. Enable **"Pr3tz"** from the list.
5. Access the controls in the **3D Viewport → N-panel (sidebar) → Pr3tz** tab.

### Option B — Symlink (Recommended for Developers)

To test and develop with live code updates without having to reinstall the addon:
1. Open your terminal as Administrator (on Windows) or with standard user permissions (on Linux/macOS).
2. Run the appropriate command for your OS/shell to link the `pr3tz/` folder directly to Blender's local addons directory (replace path with your Blender version/path if needed):

   **PowerShell (Windows):**
   ```powershell
   New-Item -ItemType SymbolicLink -Path "$env:APPDATA\Blender Foundation\Blender\5.0\scripts\addons\pr3tz" -Value "$PWD\pr3tz"
   ```

   **CMD (Windows):**
   ```cmd
   mklink /d "%APPDATA%\Blender Foundation\Blender\5.0\scripts\addons\pr3tz" "%CD%\pr3tz"
   ```

   **Bash (Linux):**
   ```bash
   ln -s "$PWD/pr3tz" "$HOME/.config/blender/5.0/scripts/addons/pr3tz"
   ```

   **Bash (macOS):**
   ```bash
   ln -s "$PWD/pr3tz" "$HOME/Library/Application Support/Blender/5.0/scripts/addons/pr3tz"
   ```

3. Enable **"Pr3tz"** in Blender's Preferences.
4. Press `F3` and search for **"Reload Scripts"** to reload changes instantly.

### Option C — Bootstrap Loader (No Installation)

Since Python relative imports fail when running individual module files directly, you can run the bootstrap script from the repository root:
1. Open Blender.
2. In the **Text Editor**, open [run_script.py](run_script.py).
3. Click **Run Script** (or press `Alt+P`).

Alternatively, load it directly from the terminal:

**PowerShell (Windows):**
```powershell
& "C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python run_script.py
```

**CMD (Windows):**
```cmd
"C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python run_script.py
```

**Bash (Linux):**
```bash
blender --python run_script.py
```

**Bash (macOS):**
```bash
/Applications/Blender.app/Contents/MacOS/Blender --python run_script.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.

---

## Programmatic Examples

The `examples/` directory contains 8 different Python scripts demonstrating how to interact with the Pr3tz animation engine programmatically:

1. [01_simple_torus_knot.py](examples/01_simple_torus_knot.py) — Demonstrates basic torus knot generation with customizable coprime topology parameters.
2. [02_multi_link_knot.py](examples/02_multi_link_knot.py) — Shows how to generate multi-link torus knots when $p$ and $q$ are not coprime, producing multiple separate interlocking curve loops.
3. [03_shape_types.py](examples/03_shape_types.py) — Shows generating and editing other shapes supported by the engine (Mobius Strip, 3D Lissajous, Spherical Spiral).
4. [04_animation_styles.py](examples/04_animation_styles.py) — Exercises the four different built-in animation modes (spin, revolution, vertical height breathing, and scale pulsation).
5. [05_custom_transitions.py](examples/05_custom_transitions.py) — Configures morph transitions and material cross-fading between completely different geometry types and shader presets.
6. [06_audio_reactive_simulation.py](examples/06_audio_reactive_simulation.py) — Simulates audio-reactive animation by programmatically keyframing global parameters and knot attenuverters.
7. [07_headless_render.py](examples/07_headless_render.py) — Sets up and renders a sequence of frames headlessly using Blender's background CLI.
8. [08_programmatic_bake_export.py](examples/08_programmatic_bake_export.py) — Invokes the bake/export operator programmatically to compile procedural curves into standalone mesh frames.

To run any example from the command line:

**PowerShell (Windows):**
```powershell
& "C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python examples/01_simple_torus_knot.py
```

**CMD (Windows):**
```cmd
"C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python examples/01_simple_torus_knot.py
```

---

## 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.

---
## Repository Layout

```
├── pr3tz/               # Main add-on package folder
│   ├── __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
├── run_script.py        # Bootstrap runner for Text Editor / CLI execution
└── package_addon.py     # Automated packaging tool to create release .zip files
```

---

## 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 |

---
## Release Packaging

We provide an automated script to pack the addon for release:

**PowerShell / CMD (Windows):**
```cmd
python package_addon.py
```

**Bash (macOS/Linux):**
```bash
python3 package_addon.py
```

This script:
1. Parses the release version dynamically from `pr3tz/__init__.py`.
2. Zips the `pr3tz/` directory into `releases/pr3tz_v<version>.zip`.
3. Automatically excludes developer files (`__pycache__`, `.git`, `.pyc`, etc.) so that the release package remains clean.

---

## Contributing

Pull requests are welcome. For major changes please open an issue first.

### Development setup

To configure your workspace for active development:
1. Clone the repository:
   ```bash
   git clone https://github.com/YOUR_USERNAME/pr3tz.git
   ```
2. Symlink the addon to Blender's addons folder as shown in **Option B** of the installation instructions.
3. Use `run_script.py` to quickly test code changes from the CLI or Text Editor.

---

## License

MIT — see [LICENSE](LICENSE) for details.