MatchMove

Function

The MatchMove node is a dedicated tracking node to match a foreground element onto a background element using 1 point (panning), 2 point (panning, scaling, rotation) or 4 point (cornerpinning) tracking. Unlike Tracker or Stabilize, MatchMove can do the compositing operation for you, or you can pass the transformed foreground out to do more modifications (Blur, color corrections, etc) before you do a composite. Unlike most compositing operations, MatchMove has the Background as the first image input, and the Foreground as the second image input.

You can generate up to four tracking points with MatchMove, or you can load in other tracks (either created in Shake or on disk) using the right mouse menu over a trackName textfield.

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

For a tutorial on tracking, jump to Tracking Tutorial.

A description of MatchMove parameters appears below.

Parameters
Type
Default Notes
applyTransform int 0 The foreground element will only be transformed if this is toggled to on.
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 cornerpin 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. These are saved in the script as stabilizeX/Y.
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 0 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 0,0,
Foreground.width, 0
Foreground.width, Foreground.height
0, Foreground.height

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.

In the script, these coordinates are refered to as x1, y1, x2, y2, etc.

 

x/yFilter string default, xFilter The transformation filter used. Jump to Filter Types
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).
aspectRatio float 1 The aspect ratio for non-square pixel plates.
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. This will not effect your output image.
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.
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 MatchMove( 
  image Background,
  image Foreground,
  int applyTransform,
  const char * stabType,
  float track1X,
  float track1Y,
  int matchX,
  int matchY,
  float track2X,
  float track2Y,
  int scale,
  int rotation,
  float track3X,
  float track3Y,
  float track4X,
  float track4Y,
  float x1, // These values are
  float y1, // for the foreground 
  float x2, // cornerpin coordinates
  float y2,
  float x3,
  float y3,
  float x4,
  float y4,
  const char * xFilter,
  const char * yFilter,
  float motionBlur, 
  float shutterTiming,
  float shutterOffset,
  float referenceFrame,
  const char * compositeType,
  int clipMode,
  const char * trackRange,
  const char * subPixelRes,
  const char * matchSpace,
  float referenceTolerance,
  const char * referenceBehavior,
  float failureTolerance,
  const char * failureBehavior,
  int limitProcessing,
  ...
);

Script

image = MatchMove( 
  Background,
  Foreground,
  applyTransform,
  "trackType",
  track1X,
  track1Y,
  matchX,
  matchY,
  track2X,
  track2Y,
  scale,
  rotation,
  track3X,
  track3Y,
  track4X,
  track4Y,
  x1, 
  y1,
  x2,
  y2,
  x3,
  y3,
  x4,
  y4,
  "xFilter",
  "yFilter",
  motionBlur, 
  shutterTiming,
  shutterOffset,
  referenceFrame,
  "compositeType",
  clipMode,
 "trackRange",
  "subPixelRes",
  "matchSpace",
  float referenceTolerance,
  "referenceBehavior",
  float failureTolerance,
  "failureBehavior",
  int limitProcessing,
  ...
);

See Also
Tracker, Stabilize