Video Analysis

Introduction

These commands provide capability for handling videos (from the LEEM or the KSA-400 video system) or sequences of images (stored in PGM format). The videos can be displayed, and various operations such as inspecting the intensity vs. image number at a particular pixel can be performed. Operations on those intensity vs. image number can also be performed, in particular fitting those to an oscillatory function (as in LEEM reflectivity curves) and producing a colorized image based on that analysis. Within the IM program, these video commands are given as part of a special command stream, which begins with the command: 

VIdeo
and ends with the command: 
QUit
All commands occurring between these beginning and ending commands are interpreted as video analysis commands. The VIdeo command can be followed by options /1, /2, or have no option. The /1 option is the same as no option, and assumes video files measuring 544x512 (which applies to all video files before about March, 2016). The /2 option assumes video files measuring 528x512 (which applies to all video files after about March, 2016). For example, the following command stream will write a string in the lower left-hand corner of the image with information about the scale of the image: 

vid             ;start video command sequence
10june09_4.vid  ;input the video
1,100           ;start,end frames
33,544          ;x range
1,512           ;y range
1               ;bin size
267,277,260     ;center x,y and radius
0       ;energy (eV) of first frame in video
0.1     ;energy (eV) per frame
gr              ;construct sequence of gray scale images
di              ;display that sequence of gray scale images
co              ;convert gray scale images from .PGM format to .JPG format
qu              ;quit video command stream
qu              ;quit IM command stream
In the above example the values in the 4th and 5th lines define the window (maximum of 512 in each direction) within each video frame that is used for analysis, and the bin value on the 6th line provided a bin size if needed. The values on the next line define a midpoint and radius, beyond which some of the analysis commands do not operate (i.e. as a time saver). The values on the next two lines define the starting energy for frame 1 of the sequence and the energy increment between frames. The command gr then constructs a sequence of gray scale image, di displays them, co convert them from PGM to JPG format, and the two qu commands exit the video command stream and the IM command stream, respectively.

Additional Required Files

Importantly, one additional file is needed within the working directory (i.e. whatever directory the IM command sequence is present in), font2.fnt. This file defines the fonts used for labeling of images. If this file is not present, then the VIdeo commands will not function properly.

Data Structures and Directories

When a video is input with the VIdeo command, a directory called DAT is created and a set of 16-bit images are written in that directory, one image per frame of the video to be analyzed. These 16-bit images are given type PGM, but they're not really PGM files since they don't have a header. Rather they're just storage files that contain the data for each image. Later use of the GRay command then creates a second directory called IMG into which standard 8-bit PGM image are written. Those images are the ones that are displayed with the DIsplay command. These 8-bit PGM images can be transferred if desired from the IMG directory into the directory above that one, which the user is working in, and input there using a regular IM command sequence with the command INput/PGM.

The commands within the video sequence operate on either these 16-bit or 8-bit images within the DAT or IMG directories, respectively. As for the IM program as a whole, labeling of these images is performed on fixed size images measuring 512x512 pixels. Pixels are numbered 1 to 512 from left to right (x-direction, or column number), and 1 to 512 from bottom to top (y-direction, or row number). Locations of various symbols are specified using the coordinates of the pixels. Strings are located relative to a pointer, with the lower left-hand corner of a character being located at the current pointer location.

Grey-scale Values

These routines employ user-specified grey-scale values for the various labels, with an 8-bit range used for the shade values. A value of 0 corresponds to black, and a value of 255 corresponds to white.

Command Summary


CIrcle
arguments:	ncircle (integer)
                xmid,ymid,radius (reals)
                ... (previous line repeated n times)
                xoffset (integer)
Draws ncircle circles on the 8-bit PGM images, and averages the data from the 16-bit image files over these circular regions. The curves of average intensity vs. energy are output in fort.31, fort.32, fort.33, ... for the first, second, third, ... circular regions. The parameter xoffset determines the location on the PGM images of a letter A, B, C, ... that labels each circle. 

COnvert
Converts the sequence of gray scale images from PGM to JPG format. 

Display
Displays the sequence of gray scale images constructed with the GRay command. 

GRay
Construct sequence of gray scale images. 

GRay/d
arguments:	number of translational drift specifications (integer)
                frame1,frame2,delx,dely shifts in image position (2 integers, 2 reals)
                ... (previous line repeated n times)
                number of rotational drift specifications (integer)
                frame1,frame2,delrot shifts in image orientation (2 integers, 1 real)
                ... (previous line repeated n times)
Construct sequence of gray scale images, with adjustments made due to translational and rotational drifts in the image position. The specified values correspond to the actual shift in the image as viewed in the absence of any corrections. The specified adjustments are applied consecutively. Files fort.70 and fort.71 contain a summary, frame by frame, of the tranlational and rotational adjustments. 

GRay/s
arguments:	min, max fractions (reals)
Construct sequence of gray scale images, specifying data cuts (statistics) for the gray scale images. The min, max fractions specify the fractional amount of gray scale to cut off (i.e. saturate) on either end of the gray scale range. If both 's' and 'd' options are specified, then the arguments for the 's' option must be supplied first. NOTE: this 's' option specification used to be called 'd', so some prior input files may require revision. 

NL (number of layers)
arguments:	xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                ampmin (real)
                kmin,kmax (real)
                pmin,pmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Performs analysis of number of graphene layers based on reflectivity data from the LEEM. Analysis is performed over the region defined by xstart,xend and ystart,yend; normally these will be 1,512 and 1,512, but a restricted region can be used to test the analysis over small areas of an image sequence. Also, if xstart=xend and ystart=yend then just that one pixel is analyzed, with additional intermediate output of the analysis results. The analysis consists of taking the averaged intensity vs. energy curve made of an average over the surrounding pixels out to radius radius, performing a background subtraction specified by background-type, fitting that to an oscillatory function with variable wavevector (k) and phase (p), constructing a scatterplot of the results on a p vs. k plane, and then defining regions within that scatterplot for which the pixels belonging to that region are colored the color color on a colorized image of the surface (1=blue, 2=red, 3=yellow, 4=green, 5=cyan, 6=magenta, 7=gray, ...). Only results of the fits having amplitude greater than ampmin are included in the scatterplot and subsequent analysis. The scatterplot is displayed over an area defined by kmin,kmax and pmin,pmax. In order to produce clusters of points within this scatterplot that are aligned with the k- and p-axes, a modification is made to the p values, wherein they are redefined as pnew = p + kmult*k using the kmult parameter. Also, on the scatterplot the phase values are offset by an amount poffset. The scatterplot is output in two forms, one being a direct VP graph (EXG file) and the other being a color PPM file. On the latter, the bottom gfrac part of the color scale range is expanded to fill the entire range (i.e. the part of the range above gfrac) is saturated). 

NL/s
arguments:	xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                ampmin (real)
                kmin,kmax (real)
                pmin,pmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Similar to NL command, but just constracts a new scatterplot without re-fitting all the data. Useful for refining values of kmin,kmax and pmin,pmax in a relatively quick manner. 

N2 (number of layers; command type 2)
arguments:	finalchan (integer)
                xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                ampmin (real)
                minchan1,maxchan1,minchan2,maxchan2 (integers)
                discrim (real)
                kmin,kmax (real)
                pmin,pmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Performs analysis similar to NL command, but with modification that the ratio of intensities between minchan1,maxchan1 and minchan2,maxchan2 is examined, and colorization of the point is performed only if the fractional difference between these values (i.e. (finalvalue-initialvalue)/initialvalue)) exceeds the discriminator value of discrim. This is useful for not colorizing areas that lack the turn-on in reflectivity near 8 eV. See figure 8 of paper 92 for an example of usage. The value of finalchan defines the final value of channel (frames) used in the fitting procedure, whereas the total number of frames input with the VIdeo command must extend to include the maxchan1 and maxchan2 values. 

N2 (number of layers; command type 2)/s
arguments:	finalchan (integer)
                xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                ampmin (real)
                minchan1,maxchan1,minchan2,maxchan2 (integers)
                discrim (real)
                kmin,kmax (real)
                pmin,pmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Similar to N2 command, but just constracts a new scatterplot without re-fitting all the data. Useful for refining values of kmin,kmax and pmin,pmax in a relatively quick manner. 

N3 (number of layers; command type 3)
arguments:	xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                kmin,kmax (real)
                pmin,pmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                ampmin,ampmax (real)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Performs analysis similar to NL command, but with modification that the amplitude of the intensity in each region must fall between the specified values of ampmin,ampmax (hence, a three-dimensional type of scatterplot analysis is performed). An ampmin value following the radius (as for NL) is not part of the input parameter sequence. 

N3 (number of layers; command type 3)/s
arguments:	xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                amp0min (real)
                kmin,kmax (real)
                pmin,pmax (real)
                ampmin,ampmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Similar to N3 command, but just constracts a new scatterplot without re-fitting all the data. Useful for refining values of kmin,kmax and pmin,pmax in a relatively quick manner. 

N4 (number of layers; command type 4)
arguments:	finalchan (integer)
                xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                amp0min (real)
                minchan1,maxchan1,minchan2,maxchan2 (integers)
                discrim (real)
                kmin,kmax (real)
                pmin,pmax (real)
                ampmin,ampmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Performs analysis similar to NL command, but combines modifications in the N2 and N3 commands. The ratio of intensities between minchan1,maxchan1 and minchan2,maxchan2 is examined, and colorization of the point is performed only if the fractional difference between these values (i.e. (finalvalue-initialvalue)/initialvalue)) falls within the specified ampmin,ampmax range for each region. This procedure is useful for identifying areas e.g. that have the reflectivity minimum associated with decoupled graphene. The value of finalchan defines the final value of channel (frames) used in the fitting procedure, whereas the total number of frames input with the VIdeo command must extend to include the maxchan1 and maxchan2 values. 

N4 (number of layers; command type 4)/s
arguments:	finalchan (integer)
                xstart,xend (integers)
                ystart,yend (integers)
                radius (real)
                amp0min (real)
                minchan1,maxchan1,minchan2,maxchan2 (integers)
                discrim (real)
                kmin,kmax (real)
                pmin,pmax (real)
                ampmin,ampmax (real)
                poffset (real)
                kmult (real)
                gfrac (real)
                background-type (integer)
                nregion (integer)
                kmin,kmax (reals)
                pmin,pmax (reals)
                color (integer)
                ... (previous 3 lines repeated nregion times)
Similar to N4 command, but just constracts a new scatterplot without re-fitting all the data. Useful for refining values of kmin,kmax and pmin,pmax in a relatively quick manner. 

QUit
Quit the video command stream. 

VIdeo
arguments:	filename (string)
                startframe,endframe (integers)
                xstart,xend (integers)
                ystart,yend (integers)
                binsize (integer)
                xmid,ymid,radius (reals)
                Estart,deltaE (reals)
Inputs video filename, from startframe to endframe, and using the portion of each image specified by xstart,xend, ystart,yend, and binsize. Parameters xmid,ymid,radius define a circular region for subsequent analysis (the values for these parameters can be determined by drawing a circular region using LAbel commands, on a single of the image frame from the video that is copied over from the img folder and input using a regular IM command stream. The energy scale for each frame in the video is defined by Estart,deltaE.