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.