Find Bad Motion Tracks

This is a Blender addon for finding bad motion tracking tracks.

The way it works is that it highlights tracks that move differently from the others.

Basically, if all tracks move to the right, except one that moves to the left, then the single track moving to the left is likely wrong and should be evaluated by a human.

Installation Instructions

1. Go to the latest release download page
2. Download the find_bad_tracks-A_B_C.py file
3. In Blender, open Preferences (under the Edit menu)
4. Click Add-ons
5. Click the Install... button
6. Find the file you just downloaded and click Install Add-on
7. Check the box next to Video Tools: Find Bad Tracks

Usage Instructions

1. Follow the Installation Instructions ^ for how to install and enable this addon

2. Do some motion tracking, collect some tracks

3. In the Motion Tracking workspace, Movie Clip Editor on the middle left of your screen, select the Track tab, expand Find Bad Tracks (you may have to scroll down to see this section) and press the Find Bad Tracks button.

   At about 400 tracks and 600 frames the computation takes 5s-10s on my machine.

4. A list of Bad Tracks will now be displayed just below that button, with each track's badness score next to it.

   Clicking a track in the list will select that track in the clip editor and take you to the worst frame. Stepping a few frames left or right will show how the track skips / slides.

5. Another list of Duplicate Tracks comes below the Bad Tracks list. This list contains track pairs that come close at some point of their lifetimes. The most divergent track pairs are at the top of this list.

   At the bottom of the list you will find tracks that overlap tightly without diverging.

   Clicking a track pair in this list will take you to a frame where the tracks overlap. Stepping a few frames left or right will show you if the tracks start diverging. If they do, (at least) one of the tracks are likely bad!

Comparison to Built-in Functionality

Find Bad Tracks is similar to the built-in Filter Tracks functionality (source).

	Find Bad Tracks	Filter Tracks
Finding the midpoint	💚 Uses median, resilient to outliers	💔 Uses average, sensitive to outliers
Threshold	💚 N/A, calculates a badness value based on the 80th percentile of track movements, works on both fast and slow moving frames	💔 5 pixels, too sensitive on fast moving frames, too lenient on slow moving frames
Uses derivative	💚	💚
Uses 2nd derivative	💚	💔 No, which means the Filtering will miss tracks which suddenly move in a new direction
Tracks marker shape changes	💚	💔
Presentation	💚 List tracks ranked by badness, lets user filter	💔 Just selects all "bad" tracks, in my case that included lots of good tracks making the signal-to-noise ratio bad
Finds duplicate tracks	💚	💔

Development

Use tox to verify your code before committing / PRing:

tox

Testing Locally in Blender

These are first-time instructions. For the second go, you can just regenerate the plugin and install it from disk again in the Blender Preferences. This will replace the currently installed version with the new one.

1. ./package-versioned-zip.sh 99.99.99
2. Start Blender and pick "VFX" under "New File"
3. Install the addon from find-bad-motion-tracks-99_99_99.zip:
   • Edit ->
   • Preferences ->
   • Extensions ->
   • Click the unlabeled Extension Settings dropdown button on the right ->
   • Install from Disk ->
4. Make some tracks to test with
   1. In the Motion Tracking workspace (you should already be there), click the Open button in the middle of the screen and load some video clip
   2. Click the "Detect Features" button on the left
   3. Under Track, click the "Track the selected markers forward for the entire clip" button
5. Scroll down to the Find Bad Tracks section and click the "Find Bad Tracks" button

Development Environment

I have developed this with:

• Visual Studio Code with its Blender Development extension
• The Fake Blender Python API module collection in a virtualenv
• Blender 2.93.1

Icon

To edit the icon, first update icon.blend. Then render the updated icon into icon.png.

Making a New Release

1. Make sure the screenshot and description ^ are both up to date and in sync.
2. Run release.sh and follow instructions.

TODO

• Fix the tracks list tooltips, the current ones make no sense: "Active Bad Track / Double click to rename."
• Profile and see what can easily be sped up
• Publish on Blender Market

Next Gen

The current badness algorithm works well when all tracks move in the same direction (camera pans).

But doesn't work at all when the camera zooms or rotates.

What about this then?

1. Compute the (2D) transformation matrix between two frames
2. For each marker, check how far it is from its computed value given that matrix

That should work for zooming and rotating camera motion as well. Also, we could check the whole matrix and see if it makes sense, if the whole image just gets narrower for example that's probably wrong.

Inspirational code here: https://stackoverflow.com/a/20555267/473672

DONE

• Document a release process
• Make an initial release
• Document install instructions higher up in this document
• Ignore locked tracks, assuming they have been manually vetted by a human
• Announce on BlenderNation
• Fix user reported issues
• Add duplicate tracks detection
• Remove worst-frame column from the bad-tracks list.
• Properly deselect unrelated tracks when switching between duplicate track pairs in the UI
• Add a tox.ini with mypy, pylint and black code formatting. Black formats locally and verifies in CI.
• Add a tox Github action for PRs and pushes