Real time GIWAXS movie generator

The m-script takes GIWAXS images, calibrates them, reshapes them, and plots them as a movie of reshaped GIWAXS patterns.

This m-file or script uses GIXSDATA from Argonne National Laboratory / Advanced Photon source. It was written by Zhang Jiang. Please download latest version of GIXSGUI on the web-page <https://www.aps.anl.gov/Sector-8/8-ID/Operations-and-Schedules/Useful-Links/Sector-8-GIXSGUI>. Then, unzip GIXSGUI folder. Start Matlab. On the Home tab, click "Set Path" > "Add with Subfolders..." and select the folder that contains the GIXSGUI distribution. Click "Save" and "Close".

Then, open my script "real_time_GIWAXS_movie_generator.m". The m-script calibrates GIWAXS images according to the calibration text file, you need to create. Then, it reshapes X-ray detctor image to GIWAXS pattern in (q_r, q_z) space. It can perform time-binning of images, which is explained below.

In program, you need to specify the path to folder with your images. Therefore, you need to fill string variable path_to_folder on the 52 line (e.g. path_to_folder='d:\folder_with_images\';).

You need to write video avi file somewhere on your hard drive. Please see line 61:

myVideo = VideoWriter('D:\myVideoAlica.avi', 'Motion JPEG AVI');

Specify here the place on your hard drive to save avi video file.

You need to enter path to your text calibration file, where your calibration parameters are stored. Therefore, you need to fill string variable path_to_calib_file on the 8 line (e.g. path_to_calib_file='d:\laboratory\calibration.txt';).

To create calibration text file, please create text file somewhere on your computer. Then, fill one row in text file for example like:

Pilatus 487 407 0.172 0.172 8.04 510 2 1 4 0.5 0.38 263 383 263 353

First string is type of your camera, it can be for example Pilatus from Decrtris. If not, there can be written Other.

The second unsigned integer is number of pixels in horizontal direction and third unsigned integer is number of pixels in vertical direction. For example, here, I use Pilatus 200K with area of 487 x 407 pixels (H X V).

The fourth float number is size of pixel in horizontal direction and fifth float number is size of pixel in vertical direction. Here, I use Pilatus detector, so, square pixel size is 0.172 x 0.172 mm (H x V).

The sixth float number is energy of X-rays in keV. Here, I use laboratory microfocus X-ray source with Cu anode. The energy of CuKalpha radiation is in this example 8.04 keV.

The seventh float number is sample to detector distance, also called SDD in mm.

The eight unsigned integer is geometry in GIXSDATA or GIXSGUI. There are only two possibilities for geometry value. It can be 1 for transmission or 2 for reflection. Of course, here, we evaluate GIWAXS data or grazing incidence data. It means geometry must be 2. We are in reflection mode.

The ninth unsigned integer is for phi mode value. According to the GIXSDATA and GIXSGUI manual, Range for pixel azimuthal angle with respect to the direct beam. [1]/2/3/4 for [(−180◦ , 180◦)]/[0◦ , 360◦ )/[−270◦ , 90◦ )/[−90◦ , 270◦). It is OK, to put here number 1 for azmuthal range (−180◦ , 180◦).

The tenth unsigned integer is polarization mode. According to the GIXSDATA and GIXSGUI manual, Incident beam polarization. 1/[2]/3/4 for none/[horizontal] /vertical/unpolarized. In my opinion, if your data were measured at synchrotron beamline, you need to set e.g. number 2 for horizontal polarization. If your data were measured with laboratory microfocus X-ray source, you need to set e.g. number 4 for unpolarized beam.

The eleventh float number is Horizontal Polarization Fraction. It can be set only for horizontal polarization mode (polarization mode = number 2) or vertical polarization mode (polarization mode = number 3). If Horizontal Polarization Fraction = 0.5, you have half of horizontal polarization and half of vertical polarization.

The twelfth float number is angle of incidence measured with respect to the sample surface. Here, e.g. the angle of incidence is equal to 0.38 deg.

The 13-th float number is position of primary beam in the image in horizontal direction. The 14-th float number is position of primary beam in the image in vertical direction. Here, in this example, Beam0_Hor = 263 pixel, and Beam0_Ver = 383 pixel.

The 15-th float number is position of specular/reflected beam in the image in horizontal direction. The 16-th float number is position of specular/reflected beam in the image in vertical direction. Here, in this example, Specular_Hor = 263 pixel, and Specular_Ver = 353 pixel.

In my script, calibration text file is read by readtable function. The calibration in the script is between 10 and 37 lines. Read it carefully to understand calibration.

If you perform time-resolved study with Pilatus detector, your images are like

image_00000.tif

image_00001.tif

image_00002.tif

image_00003.tif

and so on until

image_01199.tif

image_01200.tif

Here, your first image is image_00000.tif and last image is image_01200.tif.

According to this example, your image name root is image_name_root=''image". Please see the 40 line.

Here for Pilatus detector, the numbering contains 5 digits for example 10-th image has numbering 00009. Therfore, no_digits=5 on the 48 line;

The underscore between image_name_root and image numbering is added automatically.

You also need to fill image name extension. It can be '.tif' or '.cbf' (crystallographic binary file). You need to fill string variable for example image_name_extension='.tif'; on the 50 line.

If you performed time resolved study, where you have 1201 Pilatus tif images, then your first image is image_00000.tif and your last image is image_01200.tif. Then, you fill no_start_image=0 and no_stop_image=1200;

Then you can also use time-binning feature, which means that if time_binning=2, each two neighboring images are integrated together. If time_binning=1, you plot each GIWAXS image individually.

This software can perform time binning. Therefore, you need to fill unsigned integer variable time_binning.

If you don't want to use time binning, then time_binning = 1;

If you want to sum each two images, then time_binning = 2;

But be carefull, for time_binning = 1, it does not affect no_start_image and no_stop_image variables.

But for time_binning = 2, no_start_image=0 and no_stop_image=1199, beacuse from 0 to 1199 image, we have 1200 images which gives remainder 0 after division by 2. If no_start_image=0 and no_stop_image=1200, then you have 1200 +1 = 1201 images, which gives remainder 1 after divison by 2. Then, program would crash.

Finally, you want to reshape your PILATUS or other detector image in pixels into the reciprocal Angstroms. You have already your calibration text file.

My script does rehaping from pixels to q_r (horizontal reciprocal axis) and q_z (vertical reciprocal axis). It is done in my program in the lines 144 and 154.

param_reshape.X = 6; % qr

param_reshape.Y = 3; % qz

For details look at GIXSGUI or GIXSDATA manual for xflag chart.

For example, if you want to reshape in horizontal direction from -1.8 reciprocal Angstroms (variable qr_min) to +1.8 reciprocal Angstroms (variable qr_max) on 400 points and in vertical direction from 0.0 reciprocal Angstroms (variable qz_min) to +2.5 reciprocal Angstroms (variable qz_max) on 300 points, then your setting in my script should be:

% reshape parameters

no_of_points_x=400;

no_of_points_y=300;

% q_r minimal value

qr_min=-1.8; % [A-1]

% q_r maximal value

qr_max=1.8; % [A-1]

% q_z minimal value

qz_min=0.0; % [A-1]

% q_z maximal value

qz_max=2.5; % [A-1]

Here, for example, 400 points is sampling of original image in horizontal direction and 300 points is sampling of original image in vertical direction. Always check one of your image by reshaping in GIXSGUI, then apply reshaping parameters to your time-resolved data. Be carefull, if variables no_points_x and no_points_y are too big, then you can oversample your data. In such a case, you would observe oversampling lines in your reshaped image.

The time binning is happenning on 156 line of my script (find matrix sum_matrix).

Your reshaped image is in matrix img_reshaped.

You can create your program from less image number to bigger image number in forward direction or from bigger image number to less image number in backward direction. You specify direction of the visualization images in video on the 54 line in direction variable.

You set minimum intensity value and maximum intensity value in your colorscale in your images like:

min_intensity=0; % [Counts]

max_intensity=5; % [Counts]

You set time step between neighboring images in line 80 in variable time_step.

time_step=100; % [ms]

The time unit like second (s) or milisecond (ms) can be changed in:

time_string=strcat(time_to_string, ' ms');

Note for programmers: The GIXSDATA and GIXSGUI is written as object oriented program. Therefore, you need to create gixsdata object, e.g. please see line 116 with obj=gixsdata(path_to_image);. It creates object for existing time-resolved image in time-binning loop. The object is destroyed or deleted in the line 158.