Skip to content

Path Macros

Jump to bottom
Allen Lee edited this page Aug 7, 2017 · 17 revisions

Path Macros address two needs:

  1. You move your movies/experiments to different folders or filesystems.
  2. You use the Labeler on multiple machines/platforms, or you collaborate with others working on their own machines.

The Labeler identifies your movies and trxfiles using full filesystem paths. If your data is moved to a new location, these paths will no longer be valid. If you work across multiple machines/platforms, each may use different paths to identify the same networked filesystem location. (Janelia users, see "File Share Paths" on the internal wiki.)

Macros: Simple Example

To address this, APT supports the use of macros in moviefile and trxfile paths. For example:

>> lObj = Labeler;
... open project ...
>> lObj.movieFilesAll
ans = 
    'C:\here\is\a\windows\path\movie1.avi'
    'C:\here\is\a\windows\path\movie2.avi'

>> lObj.movieFilesMacroize('C:\here\is\a\windows\path','dataroot')
>> lObj.movieFilesAll
ans = 
    '$dataroot\movie1.avi'
    '$dataroot\movie2.avi'
>> lObj.movieFilesAllFull % this is the macro-expanded version of .movieFilesAll
ans = 
    'C:\here\is\a\windows\path\movie1.avi'
    'C:\here\is\a\windows\path\movie2.avi'
>> lObj.projMacros
ans = 
    dataroot: 'C:\here\is\a\windows\path'

... do stuff, save project ...

Suppose that the next time you open this project, you do so on a different platform, or the data has moved in the interim. APT will see that the paths in the project are no longer valid, and will prompt you to update the 'dataroot' macro accordingly, and your project will be back in business.

Adding a movie

In the example above, suppose that after doing some work we want to add more movies to the project. To keep the project "portable", we would like to continue using the $dataroot macro in any new movies.

If macros are defined in a project, APT will automatically check to see if any existing macros might apply when a new movie(set) is added. If any existing macros are applicable, APT will prompt you with the option to use the "macroized" vs the raw/unchanged path.

Trxfiles

Trxfiles usually live in the same folder as their associated movies. Trxfiles that meet this condition are automatically macroized as $movdir/<filename>. Trxfiles that do not fit this pattern retain their full/raw filename.

While movies themselves can contain arbitrary macros, the only macro supported for trxfiles is $movdir.

This default handling of trxfiles is intended to be largely invisible to the user. The large majority of the time, trxfiles will live next to their moviefiles. APT's default use of $movdir just means that APT will always look for the trxfile next to its moviefile, if data is moved or a different machine is used.

Opening a project where data has moved

Whenever a project is loaded, APT attempts to restart the interface at the movie you were last working on. If this movie cannot be found, APT starts the project in "no movie selected" mode, and opens the Movie Manager to give you an overview of the project.

At this point, if you can see that your data has moved en masse to a new filesystem location, or if you are on a different platform where the data has a different root path, it is probably useful to first macroize your project using the command-line API (see below) before selecting a movie to work on. This way, you will update all the movie paths in your project at once, and make your project portable. Alternatively, you can just switch to a movie directly; APT will prompt you to browse to find the missing movie. In this case, the movie paths in your project will no longer be consistent and you will need to manually update the movie locations as you navigate to them.

Selected Command-line API

For now macros are for power-users and only a command-line interface is supported. In the following, lObj is a Labeler object.

% Raw movie and trxfile paths (can contain macros)
lObj.movieFilesAll
lObj.trxFilesAll

% Macro-replaced (if applicable) movie and trxfile paths 
lObj.movieFilesAllFull
lObj.trxFilesAllFull

% Replace a string str with the given macro throughout .movieFilesAll
lObj.movieFilesMacroize(str,macro) 

% "Undo" given macro by replacing $<macro> with its value throughout .movieFilesAll
lObj.movieFilesUnMacroize(macro)

% Undo all macros
lObj.movieFilesUnMacroizeAll()

% List all macros currently in project
lObj.projMacros

% Set values on existing macros via a dialog
lObj.projMacroSetUI()

% Clear all unused macros
lObj.projMacroClearUnused()
Clone this wiki locally