Stabilize

Function

The Stabilize function is a dedicated tracking node to lock an image down, removing problems like camera shake or gate weave. You can do 1 point (panning), 2 point (panning, scaling, rotation) or 4 point (cornerpinning) stabilization. Tracks can be generated in the Stabilize node, or can be read in using the right mouse menu on the textfield of a trackName.

For general information on the three tracking functions, including button descriptions and workflow issues, jump to About Tracking.

For a tutorial on tracking, jump to Tracking Tutorial.

Parameters
Type
Default
applyTransform int 0
The foreground element will only be transformed if this is toggled to on.

inverseTransform int 0
This will invert the transformation. Use this to unstabilize the shot. For example, you stabilize a shot with a Stabilize, apply some compositing operations, and then copy the first Stabilize onto the end. By inverting the transformation, it will return the shot to its former shaky condition.

trackType string 1 point

You can do 1 point, 2 point or 4 point matchmoves. Different options appear when you select different types.

1 point
This will pan the foreground element to match the tracking point. You can optionally turn off the X or Y movement.

2 point
This will pop up two extra parameters, giving you the option to also match scaling and rotation of the background element with the matchScale and matchRotate parameters. Under each of these parameters is a sub-parameter returning the actual scaling and rotation value used in the transformation.

4 point
This will perform cornerpinning matchmoving on the foreground element. The pan, scaling, and angle parameters will disappear. You can adjust the 4 points that get pinned into the background by toggling over to FG mode in the Viewer. These points appear as sourceNX/YPosition.

applyX/Y int 1,1
These two toggles activate X and Y movement of the foreground element if applyTransform is turned on.

applyScale int 1
When in 2 point mode, this toggles on and off scaling of the foreground.

scale float NA
This is the calculated scale for 2 point matching. The scale at the refFrame is equal to 1, and all other frames are in reference to that frame.

applyRotate int 0
When in 2 point mode, this toggles on and off rotation of the foreground.

rotate float NA
This is the calculated rotation for 2 point matching. The anlge at the refFrame is equal to 0, and all other frames are in reference to that frame.

sourceNX/YPosition float NA
These eight coordinates return the X/Y corner positions of the foreground element that get matched into the four tracking points when in 4 point mode.

x/yFilter string default, xFilter
The transformation filter used. Jump to Filter Types

transformationOrder string trsx
This is the order in which transformations are executed, in the default example, (reading backwards), shear, scale, rotate, translate.

motionBlur float 0
Turns on the motion blur for the foreground element. A value of 0 means no blur, 1 is the high setting. A value midway will be a trade-off between speed and quality. This value gets multiplied by the Global motionBlur parameter.

shutterTiming
float
.5
Shutter length. 0 means no blur, whereas 1 represent a whole frame of blur. Note that standard camera blur is 180 degrees, or a value of .5. This value gets multiplied by the Global Parameter shutterTiming.

shutterOffset
float
0
This is the offset from the current frame at which the blur is calculated. Default is 0, previous frames are less than 0. The Global Parameter shutterOffset gets added to this.

refFrame float 1
This is the reference frame that is used to calculate the null state of the transformation. For example, scale will have a value of 1 and rotate will have a value of 0 at the reference frame.

outputType string Background
This is the compositing operation you select for the MatchMove node. Each one follows the standard Shake operator of the same name. To pass on a tracked foreground without compositing, select Foreground. You can also use this when modifying the foreground corner points, as the FG/BG button on the Viewer will switch this setting.

clipMode int 1 (Background)
This will select the output resolution of the node from either the Background (1) or the Foreground (0).

subPixelResolution string 1/16

The resolution of your track. The smaller the number, the more precise and slower your tracking will become.

Possible values:

1 area is sampled at every pixel. Not very accurate or smooth, but very fast.
1/4 area is sampled at every .25 pixels, i.e, 16 times more than with a sampling of 1.
1/16 area is sampled at every .0625 pixels, i.e, 256 times more than with a sampling of 1.
1/32 area is sampled at every .03125 pixels, i.e, 1024 times more than with a sampling of 1.
1/64 area is sampled at every .015625 pixels, i.e, 4096 times more than with a sampling of 1.


matchSpace string luminance
The pixels are matched according to the correlation between the selected color space, either luminance, hue, or saturation. If an image has roughly the same luminance, but contrasting hues, the user would switch over to hue-based tracking.

referenceTolerance float .75
A tracking correlation of 1 is a perfect score, meaning there is an exact match between the original reference frame and the sampled area. By lowering the referenceTolerance, you are accepting greater inaccuracy in your track. If tracked keys are between the referenceTolerance and the failureTolerance, they will be highlighted in the Viewer. Also, in some cases, referenceBehavior will be triggered if the tracking correlation is below the referenceTolerance.

referenceBehavior string use start frame

This behavior dictates what source sample a tracking area should reference. By default, the reference sample is the first frame at which you started the track, not necessarily the first frame of the trackRange. The last two behaviors measure the tracking correlation and match it to the referenceTolerance to decide an action.

use start frame
The reference area the new samples are compared to comes from the first frame at which you started tracking. If you stop tracking midway, and start up again at a later frame, the later frame will be used as the reference sample.

update every frame
The source sample is updated from the previous frame. This will give you an inherent drift in your track, as tiny errors will accumulate. This method is for movements that have drastic changes in perspective and scale.

update from keyframes
If you are using a failureBehavior of predict location and don't create keys or don't predict location, a keyframe will not necessarily be saved every frame. In this case, you may only want to update from the last frame that had a valid keyframe.

update if above reference tolerance
This will update the reference sample from the previous frame if the correlation is above the referenceTolerance. The intent of this is update every frame unless you know the point is obscured. If you have a predict mode and know there are obstructions, it keeps the ref area from updating if the point is completely obscured.


update if below reference tolerance
This will update the reference sample from the previous frame if the correlation is below the referenceTolerance. This is basically saying "If I can't get a good match, then resample". This is excellent for gradual perspective and scale shifts in your tracking area.

failureTolerance float .5
If the correlation of a track falls below this value, it will initiate the failureBehavior.

failureBehavior string stop

stop
The tracker stops if the correlation is less than the failureTolerance. You can also hit Esc to manually stop tracking.

predict location and create key.
If a failure is detected, then the tracker predicts the location of the key based a vector of the last two keys, and continues tracking in the new area.

predict location and don't create key.
As above, but new keys are not created, it merely predicts the new search area. This is excellent for tracked objects passing behind foreground objects.

don't predict location
In this case, the tracker merely sits in the same spot looking for new samples. New keys are not created.

use existing key to predict location
This setting allows you to manually create keys along your track path. You then go back to the beginning to track and start tracking, and the search pattern will start looking at where the pre-existing motion path is.

limitProcessing int 1
This will create a DOD of the bounding box of all active trackers. Only that portion of the image will be loaded from disk, therefore your tracking will go more quickly.

trackRange
string
1
This is the potential frame range limit of your tracking. If you read in a clip, the range will be set to the clip range. For generated elements like RGrad, it will take a range of 1. You can set new limits using Shake's standard range description, i.e., 10-30x2. If you stop tracking and start up again, it will start from the current frame until it reaches the lower or upper limit of your trackRange, depending on if you are tracking forwards or backwards.

trackNName string trackN
The name of the track. You can change this.

trackNX/Y float
width/3, height/3
2*width/3, height/3
2*width/3, 2*height/3
width/3, 2*height/3
The actual track point in X and Y. This is what you would use if you were linking a parameter to a track point.

trackNCorrelation float NA
The correlation value of that key to the original sample. A score of 1 is a perfect score. 0 is a very very very very bad score.

trackNWindow Parameters float NA
These multiple parameters control the windowing of the tracking box, and are not relevant to exported values.


Synopsis

image Stabilize( 
  image In,
  int applyTransform,
  int inverseTransform
  const char * trackType,
  float track1X,
  float track1Y,
  int stabilizeX,
  int stabilizeY,
  float track2X,
  float track2Y,
  int matchScale,
  int matchRotation,
  float track3X,
  float track3Y,
  float track4X,
  float track4Y,
  const char * xFilter,
  const char * yFilter,
  const char * transformationOrder,
  float motionBlur, 
  float shutterTiming,
  float shutterOffset,
  float referenceFrame,
  ...
);


Script

image = Stabilize( 
  In,
  applyTransform,
  inverseTransform,
  "trackType",
  track1X,
  track1Y,
  stabilizeX,
  stabilizeY,
  track2X,
  track2Y,
  matchScale,
  matchRotation,
  track3X,
  track3Y,
  track4X,
  track4Y,
  "xFilter",
  "yFilter",
  "transformationOrder",
  motionBlur, 
  shutterTiming,
  shutterOffset,
  referenceFrame,
  "trackRange",
  "subPixelRes",
  "matchSpace",
  float referenceTolerance,
  "referenceBehavior",
  float failureTolerance,
  "failureBehavior",
  int limitProcessing,
  ...
);

See Also
Tracker, MatchMove