Pr3tz/docs/PARAMETERS.md

# Pr3tz — Full Parameter Reference

This document describes every configurable parameter available in the Pr3tz add-on.

---

## Global Settings (`KnotGlobalSettings`)

Accessed via the **"Global Settings"** section at the top of the Pr3tz panel.
These settings apply to the entire animation.

| Property | Type | Default | Description |
|---|---|---|---|
| `frames_per_knot` | int | 12 | Base display duration (in frames) for each playlist entry. Each knot's effective duration is `frames_per_knot × cycle_rate`. |
| `resolution` | int | 128 | NURBS curve subdivision — controls how smooth the knot path is. Range: 3–1024. |
| `bevel_resolution` | int | 8 | Number of sides on the tube cross-section. Range: 0–64. |
| `knot_scale` | float | 1.0 | Uniform scale multiplier applied to all knots. |
| `global_speed` | float | 1.0 | Multiplies the effective frame counter for the entire playlist. Keyframeable. |
| `animation_phase` | float | 0.0 | Frame offset added before all calculations. Keyframe or drive for reactive control. |
| `reactivity_factor` | float | 1.0 | Scales all per-knot animation rates (spin, revolution, height, scale). Wire a driver to an audio amplitude for audio-reactive animation. Range: 0–10. |

---

## Per-Knot Settings (`KnotItem`)

Each entry in the playlist has its own complete set of parameters.

### Topology

| Property | Type | Default | Description |
|---|---|---|---|
| `torus_p` | int | 2 | Number of revolutions around the torus axis. With `q`, defines the knot type. Must be coprime with `q` for a true knot. |
| `torus_q` | int | 3 | Number of spins around the torus tube. Must be coprime with `p`. |
| `flip_p` | bool | False | Reverse the direction of the p (revolution) component. |
| `flip_q` | bool | False | Reverse the direction of the q (spin) component. |
| `multiple_links` | bool | False | Render all `gcd(p, q)` link components as separate curves. |
| `torus_u` | int | 1 | Revolution multiplier — repeats the revolution pattern. |
| `torus_v` | int | 1 | Spin multiplier — repeats the spin pattern. |
| `torus_rP` | float | 0.0 | Revolution phase offset (orbit rotation). |
| `torus_sP` | float | 0.0 | Spin phase offset (tube rotation). |

### Dimensions — Major/Minor Mode

| Property | Type | Default | Description |
|---|---|---|---|
| `mode` | enum | `MAJOR_MINOR` | Choose `MAJOR_MINOR` or `EXT_INT` dimension mode. |
| `torus_R` | float | 2.0 | Major radius — distance from centre of torus to centre of tube. |
| `torus_r` | float | 1.0 | Minor radius — radius of the tube itself. |
| `torus_h` | float | 1.0 | Height scaling of the torus. Values > 1 stretch the knot vertically. |

### Dimensions — Exterior/Interior Mode

| Property | Type | Default | Description |
|---|---|---|---|
| `torus_eR` | float | 3.0 | Exterior radius (outer edge of the torus). |
| `torus_iR` | float | 1.0 | Interior radius (inner edge / hole radius). |

### Geometry

| Property | Type | Default | Description |
|---|---|---|---|
| `geo_bDepth` | float | 0.04 | Bevel depth — tube thickness. |
| `geo_extrude` | float | 0.0 | Extrude the curve profile outward. Creates a ribbon effect when combined with `geo_offset`. |
| `geo_offset` | float | 0.0 | Offset the extruded profile from the curve centreline. |

### Animation Rates

All rate properties are **scaled by `reactivity_factor`** before being applied.

| Property | Type | Default | Description |
|---|---|---|---|
| `cycle_rate` | float | 1.0 | Per-knot speed multiplier. `> 1` makes this knot linger longer; `< 1` advances it faster. |
| `spin_phase_rate` | float | 0.0 | Rate of change of spin phase (tube rotation) per frame. |
| `rev_phase_rate` | float | 0.0 | Rate of change of revolution phase (orbit rotation) per frame. |
| `height_rate` | float | 0.0 | Oscillation frequency of torus height. Creates a breathing / pulsing warp. |
| `scale_rate` | float | 0.0 | Frequency of per-knot scale oscillation. |
| `scale_amplitude` | float | 0.0 | Amplitude of per-knot scale oscillation (0 = no oscillation). |

### Transitions

| Property | Type | Default | Description |
|---|---|---|---|
| `transition_frames` | int | 0 | Number of frames to smoothly morph from the *previous* knot into this one. 0 = instant cut. |
| `transition_easing` | enum | `QUAD_IN_OUT` | Interpolation curve for the morph: `LINEAR`, `QUAD_IN_OUT`, or `SMOOTHSTEP`. |

### Material

| Property | Type | Default | Description |
|---|---|---|---|
| `material_mode` | enum | `PRESET` | `PRESET` uses a built-in shader; `PROJECT` uses an existing material from the .blend file. |
| `shader_id` | enum | `GLOSS_BLUE` | Which of the 20 built-in shader presets to use. |
| `preset_color` | color | (0.2, 0.6, 1.0) | Base color tint passed into the selected shader preset. |
| `preset_roughness` | float | 0.1 | Roughness override for the preset. |
| `preset_metallic` | float | 0.0 | Metallic override for the preset. |
| `preset_emission_strength` | float | 1.0 | Emission strength override for presets that emit light. Range: 0–100. |
| `project_material` | Material | — | A material data-block from the current .blend. Active when `material_mode = PROJECT`. |

---

## Fit Timeline / Fit Playlist Operators

| Operator | Description |
|---|---|
| **Fit Timeline to Playlist** | Extends `frame_end` so the full playlist plays exactly once, accounting for each knot's `cycle_rate`. |
| **Fit Playlist to Timeline** | Adjusts `frames_per_knot` so the playlist fills the current `frame_end` exactly. |

---

## Bake & Export Options (`KNOT_OT_BakeExport`)

| Option | Default | Description |
|---|---|---|
| **Use Render Resolution** | True | Temporarily sets preview resolution to match render resolution during baking for highest-quality mesh output. |
| **Pack Textures** | True | Packs all external textures into the exported `.blend` file. |
| **Split Export** | False | Splits the baked animation into multiple `.blend` files. |
| **Frames Per File** | 500 | When split export is on, the number of frames included in each file. |

The bake operator:
1. Iterates every frame in `frame_start`–`frame_end`.
2. Converts the procedural NURBS curve to a mesh via `new_from_object`.
3. Uses a MD5 fingerprint to skip duplicate frames (extends the previous object's visibility window instead).
4. Inserts `hide_render` / `hide_viewport` keyframes with CONSTANT interpolation so only the correct mesh shows each frame.
5. Optionally bakes camera shake to `delta_location` keyframes.
6. Saves a copy of the file, then restores the session completely.