Effects commands
To add an effect to a clip use the command:
-add_effect CLIP_IDENTIFIER /full/path/to/effect.xml
The first argument to this command identifies the clip(s) you wish to apply the effect to. The second argument is the path to an XML file which describes the effect to apply. This XML file maybe rather simple, for example when adding a dirt correction effect which uses default settings; rather complex, for example when adding a sharpen effect with time-animated curves and in/out points; or anywhere in between.
As mentioned earlier, to document the XML files to describe every possible parameter in every possible effect would be a whole document in itself. In this chapter we simply describe some of the more commonly used effects and parameters. If this does not cover the effect/parameter you need then you can (1) contact support for advice (once we know which effect/parameter you are interested in documenting it is straight forward... its just there are an awful lot of them!), and/or (2) create the effect you wish to use in the GUI and then look at the XML description of the clip in the project directory structure - the XML required by the command line processing and that generated by the GUI are one and the same.
Auto Dirt
In its simplest form a dirt effect can be added using the XML file:
<meta type="Effect">
<effect type="AutoDirtFix">
</effect>
</meta>
The default settings for this effect are the same as when creating the effect using the GUI. A more complex example changing dirt type, minimum contrast, frame lookahead and fix mode:
<meta type="Effect">
<effect type="AutoDirtFix">
<dirtParams>
<type>0</type>
<contrast>0.05</contrast>
<lookahead>2</lookahead>
<fix>1</fix>
</dirtParams>
</effect>
</meta>
Note that contrast
is specified as an absolute, whereas in the GUI it is a percentage; the dirt type
is an integer where dark only=0
, light only=1
and dark and light=2
; and the fix
mode is an integer with temporal=0
and spatial=1
.
If you need to specify colour channels use channels
where the value is the the sum of red=1
, green=2
and blue=4
. Sizes, such as minimumSize
and maximumSize
, are normalised to the clip width. For example if a clip is 2k resolution then a size of 0.00244141
is 5 pixels (0.00244141*2048=5). To have no bound on minimum or maximum size sets its value to -1
.
Scratch
A basic scratch effect can be added using the XML file:
<meta type="Effect">
<effect type="Scratch2013">
</effect>
</meta>
The default settings for this effect are the same as when creating the effect using the GUI. A fuller example:
<meta type="Effect">
<effect type="Scratch2013">
<scratchParams>
<scratchType>3</scratchType>
<motion>1</motion>
<contrast>0.1</contrast>
<length>0.5</length>
<angle>2</angle>
<width>0.00292969</width>
</scratchParams>
</effect>
</meta>
scratchType
, while doing the same job as type
for the dirt effect has a different name and values - dark only=1
, light only=2
, dark and light=3
; motion
is spatial=0
and temporal=1
; length
, like contrast
, is an absolute number; and width
is normalised to 1.
Degrain
To create a degrain effect use an XML file:
<meta type="Effect">
<effect type="Degrain">
[grain parameters]
</effect>
</meta>
where "[grain parameters]" is an XML block which describes the grain parameters. By far the easiest way of obtaining this is to save out a grain preset from the GUI. This will write the required grain parameters XML block into the /Users/USERNAME/Documents/The Pixel Farm/PFClean/presets/grain
directory.
Generating a set of grain parameters is best achieved using the GUI tools to sample relevant areas of the footage. A library of grain parameters for different film stocks can then be built up and used across projects. However, there is nothing stopping a user manually generating a set of grain parameters by using a GUI generated set as a template and enter values for the grain strength and standard deviations.
Effects with keyframed parameters
Effects such as sharpen, blur and median filter are not as straight forward as they first may appear. Even though you may wish to create a simple blur effect with a single constant blur value, the blur effect, in its most general form, is actually defined by 6 parameters
red
,green
andblue
horizontal and vertical values - each of which is keyframed curve. And it is these keyframed curves that you need to define in an XML file in order to create the effect.
Blur
Below is an example of a blur effect:
<meta type="Effect">
<effect type="Blur">
<bezierAnimParam name="sizeX" type="bezierAnimParam">
<curve componentColour="255 0 0" componentName="Red" type="bezier1d">
<point>0.000000 2.100000</point>
</curve>
<curve componentColour="0 255 0" componentName="Green" type="bezier1d">
<point>0.000000 2.100000</point>
</curve>
<curve componentColour="0 0 255" componentName="Blue" type="bezier1d">
<point>0.000000 2.100000</point>
<point>0.500000 1.000000</point>
</curve>
</bezierAnimParam>
<bezierAnimParam name="sizeY" type="bezierAnimParam">
<curve componentColour="255 0 0" componentName="Red" type="bezier1d">
<point>0.000000 2.100000</point>
</curve>
<curve componentColour="0 255 0" componentName="Green" type="bezier1d">
<point>0.000000 2.100000</point>
</curve>
<curve componentColour="0 0 255" componentName="Blue" type="bezier1d">
<point>0.000000 2.100000</point>
<point>0.500000 1.000000</point>
</curve>
</bezierAnimParam>
</effect>
</meta>
The single point comprising the sizeX
Red
curve - 0.0, 2.1
- means at time 0
use a value of 2.1
(and since no other points are defined that value is used at all other times, ie. its clamped). The two points for the sizeX
Blue
curve - 0.0, 2.1
and 0.5, 1.0
- means use a value of 2.1
at time 0
decreasing to a value of 1.0
at time 0.5
. The time value is normalised to the clip frame range so time=0
maps to the start frame and time=1
is the end frame.
The blur effect is said to have 2 curve groups - sizeX
and sizeY
- each consisting of 3 curves Red
, Green
and Blue
.
Sharpen
The sharpen effect (<effect type="Sharpen">
) has 3 curve groups - sizeX
, sizeY
and amount
- each consisting of Red
, Green
and Blue
curves.
Median filter
The media filter effect (<effect type="MedianFilter">
) has 4 curve groups - windowSizeX
, windowSizeY
, blend
and percentile
- each consisting of Red
, Green
and Blue
curves.
Stabilize
A basic stabilisation effect can be added to a clip with:
<meta type="Effect">
<effect type="Stabilize">
<mode>3</mode>
</effect>
</meta>
where mode
is none=0
, horizontal=1
, vertical=2
, translation=3
, affine=4
and perspective=5
. If you do not specify a mode
then it will default to 0
and that is probably not what you want!
An example with other parameters specified:
<meta type="Effect">
<effect type="Stabilize">
<mode>3</mode>
<range>10</range>
<threshold>30</threshold>
<border>0.2</border>
<lock>1</lock>
</effect>
</meta>
Note that threshold
is specified as a percentage but border is an absolute even though both are presented in the GUI as a percentage. lock
is an integer where false=0
and true=1
.
Edge framing
The edge framing effect can be added to a clip with:
<meta type="Effect">
<effect type="AutoFill">
<mode>1</mode>
</effect>
</meta>
where mode
is none=0
, translation=1
, affine=2
and perspective=3
. Like the stabilize effect, make sure you specify a mode
otherwise it defaults to 0 (none)
which is probably not what you want.
Deflicker
A basic deflicker effect can be added to a clip with:
<meta type="Effect">
<effect type="Deflicker">
</effect>
</meta>
An example with other parameters specified:
<meta type="Effect">
<effect type="Deflicker">
<channels>0</channels>
<filter>1</filter>
<rgbChannels>7</rgbChannels>
<range>5</range>
<sensitivity>0.25</sensitivity>
<adjust>1</adjust>
<temporal>1</temporal>
</effect>
</meta>
where channels
is RGB=0
and luminance=1
; filter
is median=0
, Gaussian=1
and lock=2
; rgbChannels
are the colour channels as documented elsewhere; adjust
is brightness=1
, contrast=2
and both=3
;
and temporal
is false=0
and true=1
.
Lens undistort
The XML for creating a lens undistort effect is:
<meta type="Effect">
<effect type="Lens Undistort">
<mode>0</mode>
<centre>0.5 0.5</centre>
<bezierAnimParam name="lowRadial" type="bezierAnimParam">
<curve componentColour="255 255 255" componentName="Value" type="bezier1d">
<point>0.0 0.1</point>
</curve>
</bezierAnimParam>
</effect>
</meta>
where mode
is low=0
, low+high=1
, low+offset=2
and low+high+offset=3
; centre
is the distortion centre normalised to 1
. The effect has 3 curve groups: lowRadial
consisting of a single curve Value
; highRadial
consisting of a single curve Value
; and offset
consisting of 2 curves X
and Y
.
In/out points and region of interest
In and out points for an effect can be set using the in
and out
attributes of the XML description of the effect, e.g.:
<meta type="Effect" in="25000" out="75000">
<effect type="Sharpen">
...
</effect>
</meta>
in
and out
values are represented at integers where 0
is the start frame and 100000
is the end frame. So, in the above example the in point is 25% of the way into the clip and the out point is 75%. A region of interest can be set using the roiXMin
, roiYMin
, roiXMax
and roiYMax
attributes of the XML description of the effect, e.g.:
<meta type="Effect" roiXMin="2500" roiYMin="2500" roiXMax="75000" roiYMax="75000">
<effect type="Sharpen">
...
</effect>
</meta>
Again the values are normalised in the range 0-100000
for the width and height.
The above sets the in/out points and region of interest for a specific effect. It is also possible to set these for the clip as a whole (such that they acts on all effects unless overridden) by adding a ClipInfo
effect to the clip:
<meta type="ClipInfo" in="10000" out="90000">
</meta>
The ClipInfo
data does not directly represent an effect, but its contents can influence other effects.