From VFXPedia

< Eyeon:Script | Reference | Applications | Fusion Expressions

Expression Types

InTool Scripts

InTool scripts are entered directly into a tool on the composition, using the Scripts tab in the tool controls (labeled with a red cogwheel). There are three varieties of InTool script, a start render, end render, and per-frame script. The start render script runs the first time the tool is rendered, the end render script runs when the tool is done rendering, and the per-frame script runs after each frame is complete.

InTool scripts do not currently start with any context, they are unaware of the fusion, composition, and tool variables which are visible to the Composition and Tool scripts described above, and because of their protected environment are unable to correctly access the composition variable that the tool is associated with. However, they are able to directly connect to other tools using various functions.

For example, you might use a InTool script in a saver to send you an email when rendering begins, add each frame to a zip file as rendering progresses, and ftp the final zip file to a remote location when rendering is complete.

Savers have an additional option for when a file is rendered to disk (FrameSavedScript). It is important to note that InTool scripts and simple expressions evaluate before the tool has been processed, so that parameters may be changed, but that the FrameSavedScript script is evaluated after the Saver has processed and saved its file.

Simple Expressions

A Simple Control Expression is used to rapidly connect one control to another or to create a value for a control using a value derived from an equation. To add a simple control expression, right-click on the control and choose Expression from the context menu.

A single line edit box will appear beneath the control. Type the desired expression into the edit box. To reference the value from another control, use the scripting name of the control. If we wanted to set a control equal to a static number, as a quick example, we would just set that line to the value (for instance, 5).

In essence, an expression is actually a one-line InTool script that returns a value for use by a single control. Any of the fucntions that are available to InTool scripts are thus available to a simple expression. So, for instance, one could use the math.sin function to modify the Y position of an X/Y path.

Simple Expressions vs. Expression Modifiers

Simple Expressions (implemented in Fusion 5) use different syntax and functional environments than Expression Modifiers (added by choosing Modify With -> Expression from the control's context menu). The only values in an Expression Modifier that are available to the number / point out controls are those defined in the Number In / Point In tabs. You can connect these Number / Point controls to published or animated inputs, but not to the inputs directly. You can also connect them by way of simple expressions.

Using InTool Scripts and Expressions

Variable Scope

Variables declared and used within an InTool script are local to that tool only. For example, if you declared 'x = "Hello"' in a per-frame InTool script, you would be unable to access the value of that variable from the console view. Entering 'print(x)' at the console would return 'nil'.

Evaluation

InTool scripts only evaluate for the frame they are currently on. They can have no lasting effect on the tool itself or the composition, only on the values used by that tool to render for that frame. For example, you could not set an InTool script to effectively delete itself (FrameRenderScript = ""), as that would apply only for the current frame; it would not be permanent.

This means that StartRenderScript and EndRenderScript also cannot be used to modify the properties of a tool in any effective way. When the composition changes frames, the effect of that script will immediately be removed. Start and End Render Scripts are more often used to run tasks indirectly related to the operation of tools (e.g. run an external script or batch file that will strip the GAMA data out of a QuickTime file).

Inputs

Given that the context of the simple expression or InTool script is local to the tool that the script belongs to, the input names for that tool do not need to be qualified with the tool's name. For instance, if one wanted to set the brightness to 0.5 in a Brightness/Contrast tool using an InTool script, it would be simply declared as such:

Brightness = 0.5

With simple expressions, declaring what input you desire to set is unnecessary (and invalid), as the results of the expression are automatically assigned to the control, i.e. prefixed with the line "Brightness =" . Note that you can only set values for controls for the currently rendering frame, and not for frames at other times.

Furthermore, when reading values in, the environment assumes that you're trying to evaluate an input's value for the current time (the time of the frame being currently rendered by that tool), but you can use square brackets to evaluate values at other times. To set the Brightness value to that of the Contrast control at time 100:

Brightness = Contrast[100]

If you need to read values at other times from other tools, you should use the GetValue() function, as described in the Functions section.

Parameter Types

Images

Image inputs, instead of passing on the selected tool, pass on the current image data. One can derive some of the information about that information on the fly, which can be used to modify inputs as well as other input images. Available properties are:

Image.Width
Image.Height
Image.XScale
Image.YScale
Image.Field
Image.Depth
Image.ProxyScale

This can be used on any of a tool's input image parameters. For example, if one wanted to modify a Merge tool's size slider based on its background's X Scale, one would do the following:

Size = Background.XScale

This has many potentially useful applications of having the image object passed into the InTool script's global environment that will be explored later in one of the lessons.

Inputs with Point Data

You may notice that if you attempt to get the X / Y position of a Merge's center point, or to a background tool's aspect ratio, it instead returns a Point object instead of a table, which is what we're used to receiving in the regular Fusion environment. To get the X/Y data, we instead retrieve the point object's X and Y members as such:

print(Merge1.Center.X)
print(Merge1.Center.Y)

To set point data, we use the Point(X,Y) function to create point userdata as such.

Transform1.Center = Point(0.5,0.5)

Clip Data

A loader or saver's clip data is another object that is not automatically evaluated with expressions and InTool scripts. Instead, you would get/set the clip by using the clip's FileName property.

print(Loader1.Clip.FileName)

Text Inputs

Text based inputs will automatically receive data that is formatted as a string, but to read text data you must access its Value member.

print(Text1.StyledText.Value)

Built-in Variables

In order to protect the basic operation of Fusion and to optimize performance, the InTool script environment starts with a much more limited context than most scripts. InTool scripts will not be able to access the composition that the tool belongs to, nor will they be able to get or set attributes of other tools within the same context of the composition, as they have only limited access to the control values of other tools.

self

In the global context of the tool, "self" is an initialized variable that points to the tool where the scripting is happening. If you need to run a function on this tool, it would be called from the self variable.

time

Given that time-modifying tools and frame parallelism make it possible for the composition's current time to be different to a given tool's current time, one cannot use the standard CurrentTime variable that is frequently used in composition scripts. As such, time is declared in the global environment of InTool scripts. For example, one could make a counter for a text plus tool based on the time variable instead of using a frame counter modifier, or set the Brightness value based on the Contrast animation, delayed by a few frames.

StyledText = time
 
-- or
 
Brightness = Contrast[time - 3]

filename

For Saver tools, an extra variable is available in the global environment for those scripts run in the FrameSavedScripts context called "filename". Its value will be equal to the path of the file just written by Fusion.

Sandbox Environment

InTool scripts are not aware of the functions and variables specific to the globals table. They have a much more limited functional scope and will not load script libraries into their environment. To load a script library, use the function ldofile(pathtoscriptlib).

ScriptLibs

As stated in Chapter 1, script library files are not loaded automatically into the scripts InTool environment. You can manually load a script library by using the ldofile() method, part of Lua's library of functions.

-- Get the path of the scripts directory from Fusion
-- in order to do this we'll have to actually connect first.
 
fusion = Fusion("localhost")
if not fusion then return end
 
-- load the eyeon library
ldofile(fusion:MapPath("Scripts:eyeon.scriptlib"))

Tips for Introduction (edit)

Assigning simple expression through script

To assign a simple expression to an attribute via scripting, use the SetExpression command.

Syntax: myTool.InputName:SetExpression(" expression text ")

Here are some examples:

myText.StyledText:SetExpression("Text(time)")
myBackground.Height.SetExpression("Width/2.35")

Accessing the Fusion object in InTool scripts

Comp and tool scripts can access a variable called fusion which contains an instance of the Fusion class. InTool scripts, however, don't have this variable set up by default. You can easily create it yourself. Just add this line to a tool's frame render script:

fusion = eyeon.scriptapp("Fusion", "localhost")

InTool script, that print (in console) full listing of tools in current composition

--tell WHO IS fusion:
fusion = eyeon.scriptapp("Fusion", "localhost")
--..and where we are:
comp = fusion:GetCurrentComp()
 --print all tools list in current comp:
dump(comp:GetToolList())

Example InTool script for 3D tool

InTool script that change tool attribute based on attribute from another 3Dobject, that connected to tool.SceneInput.

In this case we connect Locator3D.Size attribute to Camera3D.FLenght (camera connected to locator.SceneInput)

There is FlowView:

And there is locator InTool script:

                                  Start Render Script:

--tell WHO IS fusion:
fusion = eyeon.scriptapp("Fusion", "localhost")
--..and where we are:
comp = fusion:GetCurrentComp()
 
-- find this tool in current comp context
toollist = comp:GetToolList()
selfTool = nil
for i, tool in toollist do 
   if tool.Name == self.Name then 
      selfTool = tool
      break
    end
end

                                  Frame Render Script:

print("================")
 
inputObj = selfTool.SceneInput:GetConnectedOutput():GetTool()
Size = inputObj.FLength[comp.TIME_UNDEFINED]
print(inputObj.Name,"is connected to",self.Name)

Image parameter type

Instead of the .Width and .Height attributes mentioned above, you can also use .OriginalWidth and .OriginalHeight. These are the image dimensions without proxy scaling.

FuID parameter type

In addition to the point and text types described above, some controls in Fusion (mostly dropdowns) are using the FuID type. It's similar to a string, but you can't assign strings directly to these inputs in an InTool script (only comp and tool scripts can do this). Instead, turn a string into a FuID object like this:

-- create FuID from a string
f = FuID("The Value")
-- turn FuID into a string
print(f.Value)

See the snippets page for more FuID examples.

Eyeon:Script/Reference/Applications/Fusion Expressions/Introduction