TDXMorph4
Reference

Parameter Morpher4.18

Paid · v4.18.5Real-time composition, enhanced

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 ListView instances.
  • 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

  1. Download ParameterMorpher.tox from Patreon.
  2. Drag the .tox into your TouchDesigner network, or use File > Import > Component.
  3. 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 the Elements component.


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)
    Turns Pages mode on and shows the n-th container, 1 based. Returns that container, or None when 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 while Pages mode is off.

  • PageCount
    How many containers there are, which is the upper bound on the Page parameter.

  • 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 the BindedPaths dictionary.

  • GetPresetManager()
    Returns the internal PresetManager component 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. parameter is the Par itself (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 .json file.
    Used for saving full configuration states including UI bindings.

  • ImportPresetsJSON()
    Imports presets and bindings from a .json file, 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 its MorphSettings. This is the multi-track counterpart of MorphRandom, and it behaves single-track unless the engine's Multitrack gate is on.

  • MorphGroup(tag, mode=None)
    Morphs only the interpolatable elements whose MorphSettings.Group matches tag, 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 to NumberOfPresets (2.0 counts as 2); anything else gives a warning.

  • SetPreset(slot)
    Loads and activates a stored preset. Same slot rule as StorePreset.

  • 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

  • PresetManager
  • PresetMorpher
  • Menus
  • Elements
  • Parameters
  • TDResources
  • Lib/Elements/*

Python Libraries

  • TDStoreTools.StorageManager
  • json