Expressions - Device Control
Warning: the disguise software does not support expressions that uses layer names that has spaces between the words, for example "video explosions". In this case you have to rename it to "video_explosions". Expressions can only contain a-z A-Z 0-9 _
Expressions for numeric animations
Expressions allow you to have a more powerful control over animation properties. They can be used with any numeric animation property.
To set up an expression, right-click the property you want to control. This will open up the min/max/step viewer, which allows you to edit the limit values of the property and the value step used while animating. Below the min/max/step properties is a field called expression, which initially contains a single word self. This is the expression.
The easiest expression is self. It tells the system to use the value taken from the keyframe sequence. However, self can be built into more complex mathematical expressions (formulae) to do useful things, such as :
self * 2
255 * self multiplies the animated value by 255.
When you type in an expression, the property field turns green when the expression has been correctly understood. If there is a mistake, the property field turns red; moving the mouse over the property field will open up a text message telling you what went wrong.
Expressions can refer to any property of any other object in the system. For example, if you want to read the x coordinate of the position of a screen called myscreen and multiply it by 2. The expression to use would be:
screen:myscreen.pos.x * 2
In general, to access (property) of an object called (objectName) of type (type), we use:
As well as addition, subtraction, multiplication and division, disguise's expressions also support a number of standard mathematical functions. These are:
sin(x) - Sine of the angle x, where x is measure in radians
cos(x) - Cosine of the angle x, where x is measure in radians
tan(x) - Tangent of the angle x, where x is measure in radians
asin(x) - Inverse sine of the angle x, where x is measure in radians
acos(x) - Inverse cosine of the angle x, where x is measure in radians
atan(x) - Inverse tangent of the angle x, where x is measure in radians
atan2(y, x) - Angle in radians bewteen the positive x axis and the x/y co-ordinate supplied
exp(x) - Exponent of x
log(x) - Natural logarithm of x
log10(x) - Base 10 logoarithm of x
sqrt(x) - Square root of x
pow(x, y) - Raise x to the power y
abs(x) - Absolute value of x, ie: ignores the sign
floor(x) - Round x down to nearest whole integer
ceil(x) - Round x up to nearest whole integer
max(x, y) - Returns maximum value of x and y
min(x, y) - Returns minimum value of x and y
clamp(x, min, max) - Limits x to within the range min to max
radians(x) - Converts x from degrees to radians
degrees(x) - Converts x from radians to degrees
There are also a number of mathematical constants defined. These are human readable strings that may be used as a shorthand replacement for the numbers that they represent. They are:
pi - The value of PI. Equal to 3.14159265
e - Euler's number. Equal to 2.71828183
limit:: - Limits result to min max range of field
scale:: - Scales 0 - 1 values to lie within min max range.
self - keyframed value (expression defaults to this).
self.min - minimum value for this field
self.max - maximum value for this field
Time - track time in seconds
Uptime - time since d3 started in seconds
dmx:universe.channel = Read 8 bit dmx value (address base 1)
dmx16:universe.channel = Read 16bit dmx value (address base 1)
This parameter is now being controlled by universe 1, channel 28.
You can now add further expressions to the Art-Net expression, which is important for scaling the value to an appropriate size, for example:
To enable Art-Net inputs, first make sure to set up the Artnet input in d3, as described in the sub-chapter DMX input/output.
For step-by-step instructions on how to configure the disguise software to control the Timeline and layer properties using Art-Net, please see the sub-chapters Controlling the Timeline with Artnet, and Controlling layer properties with Artnet.
There's also a 16 bit version,
dmx16:universe.channel which makes a 16bit value out of the channel and channel+1 bytes. First byte is course data, second is fine. The resultant value will be the range of 0 to 65535.
When dealing with the disguise object names in expressions spaces and hyphens should be replace with underscores
For example - osc device-1 would be osc_device_1
Right-click a parameter in a layer and type in the following syntax:
For example, if you wish to control the brightness of a video layer type in:
In OSC paths, "/" is replaced with "."
osc:.some.osc.value - Read float from incoming osc message from first osc device. Only supports messages with a single parameter of type float. .some.osc.value expands to /some/osc/value
oscdevice1:.some.osc.value - Same as above but from an oscdevice called "oscdevice1". Device name must begin with osc to be supported.
After release 15, the disguise software supports more than one OSC argument per message. This allows you to use things like XY touchpad to control colour X and colour Y values.
The format would be osc:d3.address[argument number]
Position x: osc:d3.touchpad.xy
Position y: osc:d3.touchpad.xy
See more under the Controlling layer properties with OSC page.
mididevice:name.c - Get float value from mididevice control 4.
For example, you have a MIDI device named bcf2000, which has a total of 32 controls. You want to read the first control value and multiply it by the animated value coming from the timeline.
The correct expression to use would be:
self * mididevice:bcf2000.c
In general, to read control (i) of mididevice (name), you would use:
audioline:name.c[lower..upper] - Get the max value from a selection of frequency ranges.
Expressions can be used to control layer properties using the AudioAnalyser device. For more information see the Audio Analyser topic.
For example, go to the expressions text field of any numerical property and type in:
This expression will take the brightness value of the other layer called NameOfModule and multiply it with 0.5.
Please note: You cannot have any spaces in the layer name when using the name in the expression. This will generate a syntax error marked by a brown expressions field.
You can automatically create the expression by dragging an arrow from one layer parameter to another while holding down Alt . Hold down Ctrl to open up multiple layers or keyframe editors.