Overview
The ParameterMorpher is comprised of various components. To access full functionality you
need to interact with both the extParameterMorpher class and the extElementsContainer
class.
What changed in 4.x
- The embedded PresetManager engine is the shared multi-track engine. ParameterMorpher embeds three copies of it, so per-track timing, end modes, curve shapes and preset schema v2 are all available here. See PresetManager.
- The mapping editor is an owned
listCOMP, replacing the previous palette TreeListers. ParameterMorpher carries no third-party content. As of 4.5.0 it is the shared ControlMapper editor described above. - The three embedded PresetManager paths editors are owned
ListViewinstances. - Ships empty: no demo content, no stored presets, no bound paths, and no container. You create the first one yourself, which is the first step under Getting started below.
Installation
- Download
ParameterMorpher.toxfrom Patreon. - Drag the
.toxinto your TouchDesigner network, or use File > Import > Component. - Click the component's viewer to open the panel.
There is nothing else to install. The morphing engine is embedded, so ParameterMorpher does not need a separate PresetManager (unlike SceneLauncher, which attaches an external one).
The licence terms are in the LICENSE operator inside the component. Keep the .tox in your
project folder or wherever you keep your components; it carries everything it needs.
Getting started
The component opens empty, with no container and no elements. That is intentional: you build the interface you want rather than deleting a demo first.
1. Create a container
Click Create in the header, the button whose tooltip reads Create container. A
Container1 appears in the panel and the Containers parameter on the Info page goes
to 1.
The scripted equivalent, if you are building a project generatively:
op('ParameterMorpher').CreateContainer()
Call it again for a second container. Use
op('ParameterMorpher').ChangeOrientation(horizontal=True) if you want them side by side
rather than stacked.
2. Add parameters
Drag parameters onto the container panel from the network:
- Drag a single parameter (from the parameter dialog) onto the container to get one slider bound to it. This works for any parameter, built in or custom.
- Drag a whole node onto the container (or onto any element row in it) to get one element per parameter, but note that this picks up custom parameters only. Dropping a node that has none, a Noise TOP for example, creates nothing. Drag that node's individual parameters instead.
Each element stays bound to its source parameter, so moving the slider drives the original node directly.
3. Store a preset
Shift + Left Click an empty preset slot. The current value of every element in that container is captured into it.
Set the parameters differently and store a second preset. Two presets is the minimum for morphing to do anything visible.
4. Morph
Left Click a stored preset slot. The container morphs to it over its morph time, using its interpolation curve.
Two variants are useful while you are still building:
- Ctrl + Left Click jumps straight to the preset with no interpolation. Locked elements keep their value, as with a plain click.
- Ctrl + Right Click morphs over the container's global Morph Time rather than the time stored in the preset, for a quick transition check.
If you click a preset before adding any elements, the component tells you there is nothing to apply it to. That is the expected message, not an error.
5. Where to go next
Right Click empty space inside a container for its context menu: Reset parameters, Clear parameters, Rename presets in order and Add script.
The header dropdown builds the companion tools against your containers: Timers, Channels, Grabber, Animator and Patterns.
Full key and mouse reference: SHORTCUTS.md. Everything below this point is the Python API.
Signals and patterns
Any interpolatable element can drive its parameter continuously, independently of preset morphing. A signal is either an LFO (a periodic wave) or a pattern (a stepped sequence of values). It is chosen per element and runs on the component's own clock.
Where the controls live
Each element carries its own controls, and they are built on demand. In expert mode an
element shows a sig checkbox; enabling it builds that element's signal and pattern rows,
disabling it removes them again. Several elements can therefore show their signals at once.
Only the controls that are visible exist: the sync-step field matches the syncing mode (free running has none), and the pattern editor is the family your pattern type uses. Changing either swaps that one control.
The controls are a view, not the engine. Every element runs its signal whether or not its controls are built, and every value you set lives on the element's parameters below, which is why disabling and re-enabling restores exactly what you had.
The model
Signal state lives on the element's MorphSettings operator as eighteen custom parameters, and
the engine reads only those. Setting them from Python does exactly what the pane does.
| Parameter | Meaning |
|---|---|
Enablesignal |
Turns the element's signal on. Nothing runs while this is off. |
Signalsource |
Selects LFO, Pattern or Timeline. |
Lfo |
Wave shape, used when the source is LFO. |
Pattern |
Pattern type, used when the source is Pattern. |
Frequency |
Rate in Hz, used when the syncing mode is free running. |
Syncingmode |
Internal (free running), Manual, locked to Beat, Bar or Sixteenths, or locked to the project Timeline. A Timeline source offers Project and Custom only. Under Manual the signal holds still and moves only on Manualtrigger. |
Manualtrigger |
Advances a pattern by one step. An LFO or timeline signal restarts from its beginning; under Manual sync it then holds that value until the next trigger. |
Beatfactor, Barfactor, Sixteenthsfactor |
Multipliers for the locked syncing modes. |
Rangex, Rangey |
Output range. The raw signal is remapped into it. |
Smoothingactive |
Turns output smoothing on. |
Smoothrange, Smoothlength |
Smoothing amount and window length. |
Timelinemode |
Envelope shape for a Timeline source: Loop, Bounce or Once. |
Duration |
Length of one pass in seconds, used when a timeline signal runs on Custom. |
Repetitions |
How many cycles fit across the project range under Timeline syncing. |
Pattern values are stored separately, as JSON on the element's Patterndata parameter. Each
pattern type keeps its own entry, so switching type and switching back preserves what you
entered. Projects made before 4.7.0 migrate automatically the first time they load.
In the pattern editor a sequence can be typed with spaces, commas, semicolons or brackets
(0.1, 0.5, 1 and [0.1 0.5 1] both work). An entry that is not a number is refused with a
message naming it, and a Pwrand needs exactly one weight per value.
Enabling a signal from Python has one wrinkle worth knowing. A parameter execute DAT does not fire in the frame its element was created, so setting Enablesignal straight after creating an element starts the signal but builds no controls, and the element then has to be toggled twice by hand. Call EnableSignal(True) on the element instead: it writes the same parameter and drives the build directly. It is idempotent, so the execute DAT firing a frame later is a no-op.
Pattern types
Nine methods on an element select a pattern type and set its values in one call. They are the
supported way to script patterns; writing Patterndata by hand is not.
| Method | Produces |
|---|---|
SetPseq(sequence) |
The sequence in order, looping. |
SetPrand(sequence) |
Random picks from the sequence. |
SetPxrand(sequence) |
Random picks with no immediate repeats. |
SetPshuffle(sequence) |
The sequence shuffled once, then looping. |
SetPwrand(sequence, weights) |
Random picks biased by weights, one per value. Without weights, every value gets equal odds. |
SetPseries(start, step, length) |
An arithmetic series. |
SetPgeom(start, grow, length) |
A geometric series. |
SetPwhite(lo, hi) |
Uniform random values between lo and hi. |
SetPbrown(lo, hi, step) |
Brownian motion bounded by lo and hi. |
SetPseries and SetPgeom are finite by definition, so the engine wraps them to repeat
rather than letting the signal run dry and freeze.
Under the hood
One SignalEngine service at the component root drives every element, rather than each
element carrying its own engine. Only active signals occupy the service's table, and its clock
runs only while that table has a row, so a component with no signals enabled costs nothing
when idle.
The service API is documented in Help/SignalEngine.md. To resync
every running LFO in a container to a common phase, call HardSyncLFOs() on the container. Pattern
signals and Timeline-synced LFOs are left as they are.
exParameterMorpher
The extParameterMorpher class is part of the TDXMorph system for TouchDesigner.
It manages container creation, library tool instantiation, and parameter exposure within the TDXMorph module.
This class serves as a high-level manager for creating interface elements, preset-related tools, and morphing utilities from the internal library.
It adheres to a Model–View–Controller (MVC) structure, functioning as the Model, that is, the logic and data layer independent of UI interactions.
Architecture
| Attribute | Description |
|---|---|
| Class | extParameterMorpher |
| Role | Manages creation of containers, preset-related tools, and exposure of morphing data. |
| Type | Model / Logic Controller |
| Design Pattern | Part of the TDXMorph MVC architecture. |
| Usage Context | Used internally to instantiate morphing-related utilities and connect Preset Managers to UI containers. |
Initialization
morpher = op('ParameterMorpher')
Public Methods
Container Management
-
GetContainer(n)
Retrieves a specific container UI by index. -
CreateContainer()
Creates a new container for slider-based UI elements and links it to theElementscomponent.
Preset Manager Integration
-
ExposeTimers(x=0, y=0)
Creates a composite component exposing Preset Manager timer channels. -
ExposeChannels(x=0, y=0)
Creates a component exposing the parameter channels of the UI sliders: one channel per element (its value), named after the container and the element's parameter.
UI Layout Control
-
ChangeOrientation(horizontal=False)
Changes the alignment of UI containers between horizontal and vertical layouts. -
ShowPage(n)
TurnsPages modeon and shows the n-th container, 1 based. Returns that container, orNonewhen none exist. -
NextPage()/PreviousPage()
Steps one container forward or back. Both stop at the ends of the set rather than wrapping, and both are inert whilePages modeis off. -
PageCount
How many containers there are, which is the upper bound on thePageparameter. -
PageLabel()
The name and position of the current container, as shown in the header.
Reporting
ReportResult(msg, title)
Displays a popup dialog in TouchDesigner and logs a formatted message to the console.
Design Philosophy
- UI Independence: Logic operates independently of any UI behavior.
- Modularity: Provides an interface layer for morphing and preset operations without visual dependencies.
- Automation-Friendly: Allows automatic generation of morphing tools and managers in project setups.
- Extensibility: Encourages addition of new library components without structural changes.
- MVC Integrity: Respects the TDXMorph Model–View–Controller separation of concerns.
extElementsContainer
Overview
The extElementsContainer class manages groups of UI elements (sliders, toggles, menus, etc.) in TDXMorph, providing a high-level interface between the user interface and the internal PresetManager.
It acts as a UI-focused controller, handling element creation, parameter binding, preset management, and synchronization between visual and logical layers.
This class is primarily used to create and manage parameter-linked sliders for morphing and randomization within TouchDesigner.
Architecture
| Attribute | Description |
|---|---|
| Class | extElementsContainer |
| Role | Manages groups of morphing UI elements for parameter control. |
| Type | UI Controller / Manager |
| Design Pattern | Part of the TDXMorph MVC architecture. |
| Usage Context | Used to create UI bindings, manage presets, randomization, and morph transitions. |
Stored Properties
| Property | Type | Description |
|---|---|---|
BindedPaths |
dict |
Dictionary mapping cross-check names to binding data for parameters. |
containerName |
str |
Name of the container instance. |
NumberOfElements |
int |
Number of elements contained in the UI container. |
GlobalStatus |
bool |
Whether global morphing and randomization are enabled. |
Container and UI Management
-
Name(property)
Gets or sets the container’s name. -
Delete()
Deletes all UI elements and destroys the container panel. -
UpdateSize(sizeLimit=720)
Adjusts the height of the container based on its content. -
HardSyncLFOs()
Restarts the phase of every running LFO signal in the container, so they move in step. Pattern signals and Timeline-synced LFOs are left as they are. -
ChangePresetsNum(newVal)
Changes the number of presets available in the container. -
GetBindedKeys()
Returns a list of all keys from theBindedPathsdictionary. -
GetPresetManager()
Returns the internalPresetManagercomponent reference. -
GetElementsValues()
Returns a dictionary of element values and ranges. -
CreateElement(source, parameter, dataSource='parameter', customName=None)
Creates and binds a new UI element linked to a parameter or preset.parameteris theParitself (op('noise1').par.period), not its name.
Handles the correct UI type allocation, binding, and reference registration. -
AddScript()
Creates a special script element that executes custom code when triggered. -
ClearParameters()
Removes all UI parameters after confirmation. Their stored values leave every preset too, and the confirmation says how many presets that affects. -
ResetParameters()
Resets all UI elements to their default stored values. A slider's range resets on the slider and its signal settings too, and a Menu or StrMenu element keeps one slot per item. -
RenamePresetsOrder()
Renames and reorders presets based on current UI order. The selected preset and the blend endpoints follow their presets to the new names. -
ExpertMode(value)
Enables or disables “Expert Mode” for advanced control settings.
Preset Management
-
ExportPresetsJSON()
Exports all presets, bindings, and element data to a.jsonfile.
Used for saving full configuration states including UI bindings. -
ImportPresetsJSON()
Imports presets and bindings from a.jsonfile, reconstructing the UI and restoring order. -
ClearPresets(overwriteWarning=True)
Clears all presets in both macro and micro (local) managers.
Randomization and Morphing
-
SyncClocks()
Synchronizes morph timers across all linked elements. -
SetRandom(mode=None)
Randomizes parameter values globally or per element. -
MorphRandom(mode=None)
Performs a morph transition toward randomized target values. -
MorphAll(mode=None)
Morphs every element at once, each on its own timing and curve from itsMorphSettings. This is the multi-track counterpart ofMorphRandom, and it behaves single-track unless the engine'sMultitrackgate is on. -
MorphGroup(tag, mode=None)
Morphs only the interpolatable elements whoseMorphSettings.Groupmatchestag, each to a fresh random target on its own timing and curve. It forces the engine's per-track gate on, because a group is inherently multi-track, and elements outside the group keep their absolute start, so a morph already in flight is undisturbed.
Sequence Control
PresetsSequence()
Traverses the presets in the order their buttons show, across all linked elements.
Utility and Miscellaneous
-
Interpolation(property)
Gets or sets the interpolation curve used for morphing. -
Distribution(property)
Gets or sets the random distribution type. -
GlobalTime(property)
Toggles global vs local morph timing control. -
Automorph/Automorphs(property)
Controls automatic morph playback and its count. -
Time(property)
Gets or sets the morphing duration. -
NumberOfPresets(property)
Gets or sets the total number of available presets. -
StorePreset(slot)
Stores the current preset into a numbered slot. A slot is a whole number from 1 up toNumberOfPresets(2.0counts as 2); anything else gives a warning. -
SetPreset(slot)
Loads and activates a stored preset. Same slot rule asStorePreset. -
DeletePreset(slot)
Deletes a stored preset by index (a whole number from 1; a slot above the current count can still be deleted). -
GetElement(elementNum)
Returns a specific UI element by its numeric order. -
Freeze(value)
Locks or unlocks the entire UI, preventing accidental changes.
Callbacks
The following methods execute when connected callback scripts are defined:
-
OnMorphingStart(manager, morphingType, presetName)
Triggered when a morphing process starts. -
OnMorphingEnd(manager, morphingType, presetName)
Triggered when a morphing process ends, including when Stop ends it. -
OnPresetCall(manager, morphingType, presetName)
Triggered when a preset is invoked manually or programmatically.
Each one calls the matching function in the DAT set on Elementscontainercallbacks, passing the
container first:
def onMorphingStart(elementsContainer, presetManager, morphingType, presetName): ...
def onMorphingEnd(elementsContainer, presetManager, morphingType, presetName): ...
def onPresetCall(elementsContainer, presetManager, morphingType, presetName): ...
A blank Elementscontainercallbacks, or a DAT without the function, is ignored.
Design Philosophy
- UI-Driven Logic: Designed for dynamic UI creation and interaction with parameters.
- Modularity: Each container acts independently but can synchronize with others.
- Non-Destructive: Parameters can be freely created, rebound, or deleted.
- Automation-Friendly: Supports scripting, callback hooks, and sequenced morphing.
- MVC Compliance: Acts as a Controller in the TDXMorph architecture, linking UI (View) and PresetManager (Model).
Dependencies
TouchDesigner Components
PresetManagerPresetMorpherMenusElementsParametersTDResourcesLib/Elements/*
Python Libraries
TDStoreTools.StorageManagerjson