SetupDistortionCorrection, and CorrectDistortion.
The remaining m-files are invoked from the two calls above, and typically should not be called as independent script files.
The process begins by typing SetupDistortionCorrection in the Matlab command line. This will open a Graphical User Interface (GUI), displaying two image axes, and a few user controls.
The user will first upload a distorted grid image from a single camera view. This image will be displayed, with some additional graphical feedback, in the left image axis. In the center of the GUI, the user may choose which type of distorion correction transform he or she wishes to create. The transform options are ordered in such a way that the top-most option is the fastest, least precise transform, and the bottom-most option is by far the slowest, and consistently most precise option.
Once the transform option is selected, the user simply clicks "Correct Distortion & Save", and the transform is generated, a preview image is displayed, and a UI save display will appear. What is saved here is a matlab workspace (*.mat file) which contains various information about the undistortion transform.
After the save process is completed, the GUI will display the time per frame, and mean precision of the transform generated, as a means of measuring performance depending on the user's needs.
To continue on to correct distortion in videos, select the "Undistort video >>" button.
This button essentially ends the SetupDistortionCorrection process and begins the CorrectDistortion process. It is not necessary to continue straight on to the from the Setup process; the button exists solely for convenience.
In the CorrectDistortion process, which can also be invoked individually by typing CorrectDistortion at the Matlab command line, the user begins by loading the transform workspace (*.mat) that was created in the previous step. After loading the transform file, the performance information about the transform will be displayed onscreen, and the user is allowed to begin loading videos. Once a video is loaded, the number of frames and total undistortion time will appear onscreen.
The user also has the option to crop the video during this process by specifying a start and end frame in the Crop control panel. Included in this panel is the option to reduce the resolution of the video as well, with preset options of 1024x1024, 512x512, and 256x256.
Enhancing the contrast of each frame in the video is also an option available from the GUI. For any given frame, the contrast enhancement and distortion correction process can be previewed by selecting the appropriate buttons. The previews will be shown in the right image axis.
Once the proper options have been chosen, the new .avi file can be generated by selecting the Correct Distortion & Save button.
CorrectDistortion( 'path to undistortion setup file, i.e. C:/grid1PVW.mat', 'path to video, i.e. C:/frogSwim.avi', startFrame, endFrame, resolution: 1024, 512, or 256, compression: 'None' or 'RLE', and contrast enhance: true or false);
In this mode, no graphical interface will be shown, and the entire process will be run in the background. To create a batch list of videos to be corrected, simply create a new m-file in Matlab, and add the sequence of command line calls as shown above. An example of the contents of one such m-file is given below:
CorrectDistortion('C:/grid1ADP.mat', 'C:/frogSwim1.avi', 12, 223, 512, 'RLE', true); CorrectDistortion('C:/grid1ADP.mat', 'C:/frogSwim2.avi', 30, 180, 512, 'RLE', true); CorrectDistortion('C:/grid1ADP.mat', 'C:/frogSwim3.avi', 24, 252, 512, 'RLE', true); ... etc, etc.
If this list of commands were stored in a file <foo.m>, the batch processing would commence by entering the command <foo> into the Matlab command line.
For more advanced use, this processing can be accomplished without having any Matlab display appear at all. Running from a windows command line, linux or OSX terminal, the following command offers an alternative to signal the start of batch processing:
matlab -nodesktop -nodisplay -nosplash -nojvm -r foo
Notice, there is no .m attached to the end of the script file name, since it is implied by the call to Matlab. Attaching the .m at the end of the file will confuse Matlab, and the script will not execute.