Select page from this chapter: Coordinate System, Keyboard, stLocal

stLocal

Overview

The BWTT will sometimes wish to obtain information from your local system. If this information is not available, other mechanisms exist in the GUI for specifying the information manually, but you may save yourself some data entry if you provide automatic access to this information. You can do this by creating a file named stLocal.m and placing it on your Matlab path.

stLocal Function

stLocal should have the following form. You can make as many entries in the switch statement as you need to - the example below has no entries, so it responds to no requests. Individual requests are described below.

function result = stLocal(request, data) result = []; switch request end end

Requests

UserData Filename

By default, the user data (preferences, mostly) is stored in a system-specific location. This will usually be fine, but if your system is set up differently, this location may not be suitable (or you may prefer to use something different, for some reason). In this case, respond to the request getUserDataPath.

NB: If you change this setting, you will have to restart Matlab for the change to take effect.

case 'getUserDataPath' result = 'c:\My\Preferred\UserData\Path';

Job Meta Data

Some methods (particularly, output methods) will need to obtain meta data about the job so that they can perform parts of their processing. For example, temporal filtering requires the frame rate at which the associated video was originally recorded, whilst converting results into view-invariant units requires the mmPerPixel value. If you provide this information automatically by responding to the request getJobMetaData you can save yourself from having to specify it manually for each job in a project.

Meta Data Fields

recordedFrameRate is just the frame rate at which the video was recorded, allowing temporal operations (e.g. temporal filtering) to be performed correctly. It is a floating point scalar value, typically 250.0 or 500.0. The default (not set) value is the empty matrix []. If not set, output methods that provide temporal operations will not be able to perform them.

mmPerPixel provides the scaling from pixels into physical coordinates. It is a floating point scalar value, typically around 0.1 to 1.0. The default (not set) value is the empty matrix []. If this is not set, output methods that provide conversion into physical coordinates will not provide these data. Note that mmPerPixel may be dependent on the view that is being tracked (see viewIndex).

viewIndex is the index of the view that is being tracked, and can only be set by the user, not automatically. It is a small integer greater than or equal to 1. The default (not set) value is the empty matrix []. Most videos will have only one view (typically, an overhead view). Some protocols use one or more mirrors to pack multiple views into a single frame. When tracking such videos, you will need to specify which view you are tracking if mmPerPixel is to be extracted correctly by your automatic system. Your automatic system for retrieving mmPerPixel can handle the default value [] as appropriate to the video: if the video (or, all your videos) has only one view, it can return mmPerPixel; if the video has multiple views, it should return [] for mmPerPixel to indicate that it is not yet possible to provide this information (i.e. that the user needs to specify the view, first). See the example, below.

Example

The example below shows how we use this in Sheffield. Our high-speed video management system can retrieve the frame rate of any of our managed videos, which we can recognise using hs_isUID, and retrieve using hs_getFPS. Note that, if we do not recognise the filename, we return an empty result to indicate that we cannot provide this information. A simpler example would be, if all your videos are recorded at the same frame rate, you can simply return this value without checking the filename.

switch request case 'getJobMetaData' switch data.key case 'recordedFrameRate' % get the base name of the video file videoFilename = data.job.getVideoFilename(); basename = stProcessPath('justBasename', videoFilename); % if that's recognised as a UID if hs_isUID(basename) result = hs_getFPS(basename); else result = []; end case 'mmPerPixel' % get the view index viewIndex = data.job.getMetaData('viewIndex'); % get the base name of the video file videoFilename = data.job.getVideoFilename(); basename = stProcessPath('justBasename', videoFilename); % if that's recognised as a UID if hs_isUID(basename) && ~isempty(viewIndex) result = hs_getMmPerPixel(basename, viewIndex); else result = []; end end end