-
Notifications
You must be signed in to change notification settings - Fork 5
Module Guidelines
The goal of this document is to demonstrate how to add a new module to ReVAS. If you don't have time to read it all, jump to Summary of Guidelines.
Each module in ReVAS must have two input arguments. The first one (also referred to as primary input) must be a full path to a file (video, or .mat file) or an input array (3D array for videos, 2D array for position, etc.). The second argument (secondary input) must be a params structure, which defines the parameters to be used in this particular module. The params structure can have any number or type of fields, however it must have at least an overwrite field, which will determine whether or not the output of the module will be written to a file.
Depending on the type of operation that our new module will do, there might be additional restrictions or some required fields. For instance, if our new module is going to operate on videos, a badFrames field (which is a logical array indicating which frames are "bad" due to blinks or subject movement, etc.) is also required to propagate that info downstream in the processing pipeline, even if it is not used in our new module.
If we want to use the ReVAS GUI to show some progress or visualize the output of our module, we must add a field called enableVerbosity to params structure, along with the axesHandles field, indicating which axes object(s) will be used to do the visualization.
Each ReVAS module must have at least two output arguments. The first output argument (also referred to as primary output) is used as an input to the next module in the pipeline, therefore, a decision has to be made here. If the immediate output of our module is going to be fed into the next module in the pipeline, then this output variable (i.e., processed video, extracted motion, filtered motion, etc.) can be passed to the first output argument. If this module only acts like an intermediate processing step (e.g., creating a reference frame but passing the input video to the next module untouched), then first output argument must be the same as the first input argument and the primary product of the current module must be passed onto subsequent modules via the params structure.
The second output argument must be the params structure. This is (1) to enable chaining multiple modules back to back, (2) passing output of a bypass module to later stages in the pipeline.
Finally, a module might have three or more output arguments. MATLAB's varargout must be used for modules with more than two output arguments.
Conceptually, there are three types of modules.
Core modules are the ones which take in a video array or eye motion traces or a file path to one of these, perform some processing steps on this input, and return a new output (in the form of a modified video, or processed motion traces). For instance, BandpassFilter.m takes in a video and applies a bandpass filter to each frame, and returns another video with these filtered frames.
Bypass modules also take one of the aforementioned inputs, however, they pass the input to the output as is. Bypass modules are used to create intermediate or auxiliary parameters or dependencies for subsequent modules in the pipeline. For instance, FindBlinkFrames.m module takes in a video, detects bad frames during which video quality drops or there is a blink, passes the input video as is to its first output argument and an array of labels badFrames as a field of its second output argument params. Therefore, FindBlinkFrames.m can be considered as a Bypass module.
Hybrid modules can be considered as a combination of the previous two types. StripAnalysis.m module, for instance, takes in a video and returns extracted eye motion traces in its primary output. In addition, it returns same and additional information (e.g., position, timeSec, peakValueArray, etc.) as new fields under params structure.
The following table classifies existing ReVAS modules into these different types.
| Core | Bypass | Hybrid |
|---|---|---|
|
|
|
We want to create a new module. Let us assume that this module takes in a video, inverts colors of each frame, and selects one of its frames as a reference frame. We will call this new module DummyModule.m.
Note that there is already a module called
MakeReference.min ReVAS to create a reference frame, however, it has limitations and definitely a lot of room for improvement. Therefore, one might want to implement their existing and arguable better reference frame synthesis module, and incorporate it into ReVAS. This example walks through all the steps needed to achieve this.