Select page from this chapter: Home, Quick Start, Terminology

Quick Start


Download the latest release, and extract the zip file to any folder. You have to add some paths to the Matlab path before you can use the BWTT. The paths to add are all the sub-folders (three, at time of writing) under


where %BWTT% indicates the folder where you unzipped the release. You can add the paths with pathtool, or by placing a command of this sort in your startup.m.


Start the BWTT

At the Matlab prompt, run bwtt.

Create a project

When you start the BWTT, a new project is created for you. You can create a new project at any time with the command File/New Project. Now save the using File/Save.

The project is saved as a folder - you can look at it now, though you shouldn't usually have to mess around in there. Within the folder is the project file, and multiple job files (none yet, in your project), as well as various other bits and pieces. You won't generally need to go into the project folder, but be aware that you need to copy the whole folder to make a copy of the project. No data is stored elsewhere, in contrast to previous versions.

Add a job (video)

You can add multiple jobs (videos) at once using Project/Add Directory, but for now just add a single job using Project/Add Job. Pick a video file suitable for snout tracking, since it runs quickly. Your GUI should now look something like the figure below.

The single entry in the listbox top-left is the job. It is marked MO (modified) because it has not yet been saved, and has an initial frame range of 1:1 (one frame). The grey dot indicates that it does not yet have any tracking set up on it. Click CTRL+S (APPLE+S) to save the project, and the job status will change to LW (locked for writing). You won't usually need to worry about job status unless you're project sharing, though the MO state is handy because it shows which jobs you've changed since the last save.

What's a job?

A "job" is an entry in a BWTT project, the same as a "video" for simple cases - see Terminology for more details.

Set up snout tracking

Select "Snout Tracking" from the "Quick Edit" drop-down list under "Processing Methods" (for full details, click here). This will set up a "task" on the job to do snout tracking using the usual configuration. If you need to modify this configuration, you can press the "Edit Task" button to display the Edit Task GUI, but don't do this now. Your Processing Methods (PM) panel should now look like the figure below.

NB: If "Snout Tracking" is already selected, just select it again.

Parametrise the methods

Click "Task Pars" to set parameters on the selected methods. This displays the "Parameters GUI" (for full details, click here).

Under "Select Job" you should have only one option, because only one job is selected, so don't worry about that now. Under "Select Pipeline" you should have only one option, because only one pipeline (Snout) was initialised. You can immediately click "Test" to see how the BWTT gets on with the default parameters.

You should get an error message something like "cannot compute SSK - nose and snout position are not set" because stShapeSpaceKalman requires the nose tip and snout center locations. Set these with left click and right click (CTRL+click, on a mac), respectively. Then click "Test" again. You should now get some results, and usually snout tracking works reasonably well without further adjustment (you may need to tweak "Black/White Threshold", particularly if your video is dark).

Parametrisation of this task is now complete, so click "Next" to move on to the next one. There aren't any more, of course, so click "Yes" to close the GUI.

Understanding the job display

Your job entry in the project listbox should now look something like that displayed below (for full details, click here). Note that a few things have changed.

First, the job status has gone back to MO, naturally, since you modified the job. Second, the grey dot has become a light blue and dark blue pair of dots. The first (light blue) indicates that the job now has a task; the second (dark blue) indicates that you have parametrised that task using the Parameters GUI. Third, a green S has appeared, indicating that the job's current task has just one pipeline, the Snout pipeline.

NB: The dark blue dot indicates that you have run the Parameters GUI on this task and exited using the "Next" button. It does not mean you've necessarily paid attention to the parameters, or used the "Test" button.

Run the task

To run the task, just click on the ">" (Play) button in the Execution Panel. Choose the default, "Immediate Sequential Local Processing", and click OK (for full details, click here). The job is now underway, or might have finished by the time you read this.

If all went well, you'll now have a green dot (job complete). If you have a red cross, you did something wrong and should be ashamed of yourself (click CTRL+E or APPLE+E to find out what went wrong). Restart the task (below), and try again.

Restart the task

If you are one of those who rushes ahead of instructions, you might have set up a frame range on the job, too. If not, you just tracked only one frame, which is pretty lame. This is such a small amount of tracking that we can let it go, so just select Selected/Restart Task and click "OK" to confirm. The job will return to its state before you ran it (i.e. light blue and dark blue dots).

Set the frame range

The top-right panel is the "Video Preview & Frame Range" panel, and displays one frame of the video - see the image below (for full details, click here).

You can move around in the video either by clicking on the "video slider" (the white bar directly below the image) or by using the Keyboard (try left and right arrows with or without SHIFT or CTRL).

Set the first frame by pressing HOME (or [), the last frame by pressing END (or ]), and the key (initial) frame by pressing K. The A and S buttons both set a complete frame range - A sets all frames, S sets a short range for testing.

The video slider displays the frame range (first to last) as a green bar, the key frame as a red marker, and the current frame as a thin blue line. The current frame is the frame shown in the image, and is also indicated in the top left of the image. The text boxes display the frame range, but can also be edited directly to set the frame range.

You'll notice that the job entry in the project listbox is also updated as you change the frame range, so you've got a quick way to see the frame range of all jobs.

Run the task

Run the task again (">" button). This time, if you selected more than a few frames, you'll see the red progress bar counting up. You can cancel the task by clicking the stop button, or pause it (to free your CPU to do something else, perhaps) by clicking the pause button.

If you're like me, the tracking won't work because you've changed the key frame and the snout center and nose tip you set won't be correct any more. If this happened, restart the task again (Selected/Restart Task), click "Task Pars", set them correctly, and run the job again. This time, you might have time to see the blue arrows that indicate that the job is underway (see below).

During tracking, the Video Preview window shows the most recent results so you can see if things are going well.

Review tracking

You can review the tracking results by clicking the "+" button in the top-right of the Video Preview panel. This opens the "Review GUI" (for full details, click here). Move around using the left and right arrow keys (with or without SHIFT or CTRL).

Retrieve output

To get your results, you can use the "Output Methods" panel, displayed below (for full details, click here).

To quickly view a summary of the snout tracking, double click omSnoutData in the output methods listbox. omSnoutData is computed, and then plotted. You should get a figure window pop up with some summary plots. Double-clicking like this does not affect the results you eventually get out of the BWTT, but is a quick way to review what the results tell.

To retrieve the results proper, we will use the "Export" function. First, we need to "Set Outputs". Select just omSnoutData in the list, and click "Set Outputs". omSnoutData will be marked with square brackets (see figure above) to indicate that it is the one and only selected output.

NB: Raw tracking results are always exported - if you have no output methods "set", this is all you will get when you export. In some cases, this may be all you want.

Output methods can be parametrised, just like tracking methods. Click "Output Pars" to start the charmingly-named "Output Methods Parameters GUI". The parameters are not detailed, here, but you get the idea I expect.

Now, click "Export". In this case, it doesn't matter if you click "Yes" or "No" in the dialog that pops up - you'll understand why. Save the export file.

Review output

Load the exported file at the Matlab command prompt. One variable is inside, called export, and it should look something like this:

exported: '20-Apr-2011 01:11:21' jobs: {[1x1 struct]} index: [1x1 struct]

The field index is for advanced usage, and you can ignore it for now. The results and outputs for each job are in, and the results for your single job are in{1}.

uid: 'BD46_69D4_5BEF_4972' videoFilename: 'T:/HSA/B/050902-0032.avi' videoBasename: '050902-0032' jobFilename: 'T:/BWTTProjects/test2/BD46_69D4_5BEF_4972.stJob' frameIndices: [50 51 52 53 54 55 56 57 58 59 60] meta: [1x1 struct] results: {1x11 cell} outputs: [1x1 struct]

The important fields, here, are results (the raw tracking results) and outputs (the output of any Output Methods that were selected). In addition, note the field frameIndices, which applies to all array in results and outputs.

The details of these arrays are beyond the scope of this document, but you'll find (for instance) the raw (unfiltered) outputs from omSnoutData at{1}.outputs.omSnoutData.raw, and they should look something like this:

center: [11x2 double] noseTip: [11x2 double] orientation: [11x1 double] speed: [11x1 double]

Where do I go from here?

There's more? Oh, yes.

You can extend existing tracking by creating Multiple Tasks for a job. You can do parallel processing using the options in the Process GUI. You can change your local setup through the Preferences GUI and/or by using stLocal(). You can generate exciting and colourful summary videos for presentations using omOutputVideo. Oh, there's a wealth of stuff. You'll just have to explore. Have fun out there, kids.