Adding an Object Tracker to Motion Templates

Beginning with version 7.1, FxFactory offers an Object Tracker parameter to native plug-ins created through FxPacks.

To take advantage of this feature in your own Motion Templates, you will need to modify your product so as to have both an FxPack and FxTemplates components. The process is similar to that of adding custom UI to your effect, and as such, your first step should be to follow the instructions in that tutorial, making sure that you choose a Filter type effect to host your custom UI:

Adding Custom UI to Motion Templates through Native Plug-Ins

Once that first step is complete, you will have to modify your native plug-in to have as many point parameters as you will need per trackable object. In the simplest case, an object can be defined by just two points: one for the top left and the other for the bottom right coordinate of a rectangular region. As you shall see, the object tracker allows you to define additional control points and non-rectangular shapes, which require additional point parameters to be created in the plug-in.

How do you create a point parameter?

FxFactory has a “+” button that lets you conveniently add a parameter in any supported type to the plug-in. Unfortunately that feature is not very useful in the context of point parameters. Instead, you will create additional published inputs in the composition, which will set you along a different strategy:

  • Switch to the Parameters section of your plug-in.
  • Click the “+” button at the bottom of the parameter list to add an Object Tracker parameter:

  • The newly created object tracker parameter will have 1 trackable object already defined, but none of its points have been mapped. In the next few steps, you will create additional published inputs in the composition.
  • Click the Edit in FxCore option1) to make changes to the composition that backs your plug-in:

  • Delete any unnecessary logic in the composition, since your filter should render its input image without applying any modifications to it. Select all nodes in the composition except the Billboard, and hit the Delete key to remove them from the graph.
  • Now that only the Billboard node is left, right-click on its Image input and select the Publish command:

The billboard is now set to render whatever input image comes from the host app, unchanged.

  • The changes made so far to the composition should look like this:

  • Switch to the FxCore library and search for the Splitter node under the Utility group:

  • Drag the Splitter node to an empty space in your graph. Change its type to Number by clicking its type icon to reveal a popup menu:

As a shortcut, FxCore also allows you to create a new node anywhere in the graph by right-clicking on empty space in the graph.

  • Click the + icon to create additional inputs. All inputs in the splitter will be of the same type. You will need two inputs for each point you plan to define in the plug-in. One input will be used for the point’s X coordinate and one for its Y coordinate.
  • Assuming that your object tracker will need access to the Top Left, Bottom Right and Center coordinates of the object being tracked, your splitter should publish 6 distinct numeric inputs. It helps to rename each input according to its intended role. Double-click the input title to edit its contents:

  • In the example above, when creating the X and Y inputs that will ultimately be used for the Top Left point, the input splitters have been renamed to Top Left X and Top Left Y.
  • Repeat the above process until all inputs have been created and labeled. Your last step is to publish these inputs so they are available to FxFactory. To publish an input, right-click on each circle to bring up a contextual menu:

  • Select the Publish command, and repeat for all inputs in the node. FxCore also offers a faster way of publishing and unpublishing an input: option-click within the circle. When an input is published, an outline appears around its circle.

  • Save the composition and close it.
  • Switch back to the FxFactory application.
  • Click the Apply Changes button to read back the composition:

  • FxFactory will now pick up all the new inputs you have published in the composition. If you also deleted some inputs to simplify the logic of the composition, FxFactory will also mark some parameters in red, which means the parameters have become unmapped:

  • Delete any unmapped parameters that are no longer required by your plug-in. Unmapped parameters have a red dot to the right of their name and ID.
  • Notice that FxFactory also created slider parameters for every numeric input splitter you published.
  • Select two sliders and click the Join button at the bottom of the parameter list:

  • When you join two sliders, a single point parameter is the result. Voilà!
  • Join all pairs of X and Y sliders to form point parameters.
  • All point parameters you have thus created are now available to be linked from your Object Tracker parameter.

If you ever need to add additional point parameters, repeat the relevant steps discussed above. Every time FxFactory notices that a composition has new inputs, it will make its best guess as to the parameter types that should be created. Inputs published by your composition represent values of few specific types (numeric, textual, etc.) that the composition wants to accept from the host app. The parameters you create in FxFactory to map those inputs are meant to give users a way to manipulate those values through a human-friendly user interface.

Do I have to use a single plug-in for custom UI and object tracking?

The above tutorial assumes that a single filter in the FxPack serves both as a host for your custom UI elements and for your object tracker. This is not a requirement. Multiple approaches are possible, and the tutorial simply follows one of them.

Another approach that works well is to keep custom UI inside a generator plugin and create a separate filter within the same FxPack to host the object tracker. Remember that FxFactory also creates a watermark generator for your Motion Templates, which brings the total number of custom plugins in each template to 3. In this particular setup:

  1. The filter with object tracking capability is applied to the effect or title layers, at the bottom of your layer hierarchy2).
  2. The watermark generator should continue to appear at the very top of your layer hierarchy, so that the watermark is rendered above any other content.
  3. The custom UI generator can appear anywhere in the hierarchy, its layer disabled since your Motion Template does not need the output of the generator 3).

What about the watermark?

There is more than one way to build a product, and more than one way to delegate the responsibility of rendering a watermark. Ultimately only one plugin, present in every Motion Template, should be rendering a watermark. And ultimately only one plugin in each Motion Template should have its “Publish OSC” parameter enabled, so that you provide only one row of buttons to users. In the scenario described so far you should have:

  • One or two plugins in the FxPack, for custom UI and object tracking.
  • The “Requires watermark” option in the FxPack should be off.
  • The “Requires watermark generator” option in the FxTemplates should be on.
  • Each Motion Template should contain an instance of the watermark generator, corresponding to the product you are working on, in a topmost 2D-only layer that is always as large as the frame dimensions for the current snapshot.

Avoid multiple overlapping rows of on-screen buttons

No matter what approach you choose, it helps to remember that only one of the plugins in your Motion Template should display a row of buttons on-screen. That role belongs to the object tracker, since its on-screen controls make it easier for users to access object tracking functionality.
As you may recall, plugins are allowed by Final Cut Pro to display any on-screen controls based on the value of the Publish OSC parameter inside the Motion Template.

If you added a watermark generator to the same Motion Template that uses an object tracker plugin, remember to turn off its Publish OSC parameter. This prevents the watermark generator from automatically adding its row of buttons to the Canvas. If your Motion Template uses other native plugins from the same product (FxPack), remember that those other plugins too will by default create a row of on-screen buttons too. In this scenario, you need to instruct FxFactory to avoid displaying multiple rows of buttons on-screen by turning off the Automatically display on-screen controls for licensing, help, etc… for all but the object tracking filter:

If you follow the approach described so far, the above option should remain on only for the filter in the FxPack that hosts the object tracking parameter.

For better or worse, there is more than one way to solve the problems described in this document. What you end up doing is entirely dependent on how your product is structured. It helps to be familiar with Motion Templates and FxFactory to create the best possible user experience. When in doubt, contact us for assistance.

Next Steps

Once you have as many point parameters as you need, your next step is to configure the Object Tracker parameter.

If your goal is to use an object tracker inside a Final Cut Title, you should also review the documentation for the Tracker Opacity parameter. It is very important that the opacity of the Watermark Generator and any opaque layers above the Title Background be linked to the Tracking Opacity parameter so the watermark graphic and other overlays are excluded from the analysis phase.

To ensure a better user experience in Final Cut Pro, it is also important to clean-up your Motion Templates of any redundant metadata before the product is released. This is accomplished by linking each Motion Template to the object tracker plug-in, and then clicking the Strip Metadata button available in the FxTemplates UI. This process is described in the Optimal User Experience in Final Cut Pro section of the Object Tracker parameter.

FxCore must be installed prior to attempting this tutorial.
Remember to set the filter’s “Mix” slider value to 0% for efficiency and to work around problems between the Quartz Composer framework and eGPUs
An alternative to disabling the Watermark Generator layer is to set its output opacity to 0%