time-resolved GIWAXS - reshaping of GIWAXS patterns/maps

This algorithm evaluates time-resolved GIWAXS data. It reshapes GIWAXS images. It performs time-binning and pixel-binning of GIWAXS images.

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 "tb_pb_rot_GIWAXS_patterns.m". In the name of m-file, tb means time-binning, pb means pixel-binning, rot means that rotation of images is possible, and GIWAXS patterns means that program performs reshaping of GIWAXS patterns.

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

You need to enter path to output folder, where your results will be saved. Therefore, you need to fill string variable path_to_output_folder (e.g. path_to_output_folder='d:\output_folder\';).

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 (e.g. path_to_calib_file='d:\calibration\calibration_text_file.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 59 and 91 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".

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

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_ext='.tif';

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_image_start=0 and no_image_stop=1200;

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_image_start and no_image_stop variables.

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

My script uses imrotate function from Image Processing Toolbox, so, you can rotate images if necessary. You can fill, variable rot_angle in degrees. For many of your applications, rot_angle=0.0; % [deg].

In my script, you can perform pixel binning in horizontal direction (x direction) and vertical direction (y direction).

The horizontal or x direction is given by number of columns in image.

The vertical or y direction is given by number of rows in image.

For no pixel binning in horizontal or x direction:

% specify pixel binning in column direction

pixel_binning_col=1;

% start pixel in column direction

start_pixel_col=1; % [pixels]

% stop pixel in col direction

stop_pixel_col=487; % [pixels]

This is for eaxmple for Pialtus 200K detector, which has 487 pixels in horizontal or x direction (or 487 columns in image matrix). For no pixel binning, you go from 1-st pixel (start_pixel_col) to 487-th pixel (stop_pixel_col).

For no pixel binning in vertical or y direction:

% specify pixel binning in row direction

pixel_binning_row=1;

% start pixel in row direction

start_pixel_row=1; % [pixels]

% stop pixel in row direction

stop_pixel_row=407; % [pixels]

This is for eaxmple for Pialtus 200K detector, which has 407 pixels in vertical or y direction (or 407 rows in image matrix). For no pixel binning, you go from 1-st pixel (start_pixel_row) to 407-th pixel (stop_pixel_row).

Now consider that you want to sum each 2 x 2 pixels (H x V). So, you want to perform 2 by 2 pixel binning. Then, you set, pixel_binning_col=2; pixel_binning_row=2;

The setting in script should be like that:

% specify pixel binning in column direction

pixel_binning_col=2;

% start pixel in column direction

start_pixel_col=1; % [pixels]

% stop pixel in col direction

stop_pixel_col=486; % [pixels]

and

% specify pixel binning in row direction

pixel_binning_row=2;

% start pixel in row direction

start_pixel_row=1; % [pixels]

% stop pixel in row direction

stop_pixel_row=406; % [pixels]

So, what was changed? I changed stop_pixel_col to value 486, because from start_pixel_col=1 to stop_pixel_col=486, you have 486 pixels which gives remainder 0 after division by 2 (pixel_binning_col=2).

I changed stop_pixel_row to value 406, because from start_pixel_row=1 to stop_pixel_row=406, you have 406 pixels which gives remainder 0 after division by 2 (pixel_binning_row=2).

Now, you can consider that you want pixel binning 4x4.

Then

% specify pixel binning in column direction

pixel_binning_col=4;

% start pixel in column direction

start_pixel_col=1; % [pixels]

% stop pixel in col direction

stop_pixel_col=484; % [pixels] (remainder 0 after disvison by 4)

and

% specify pixel binning in row direction

pixel_binning_row=4;

% start pixel in row direction

start_pixel_row=1; % [pixels]

% stop pixel in row direction

stop_pixel_row=404; % [pixels] (remainder 0 after disvison by 4)

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 222 and 223.

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 -0.2 reciprocal Angstroms (variable qr_min) to +0.2 reciprocal Angstroms (variable qr_max) on 250 points and in vertical direction from 0.0 reciprocal Angstroms (variable qz_min) to +0.2 reciprocal Angstroms (variable qz_max) on 120 points, then your setting in my script should be:

no_points_x=round(250/pixel_binning_col);

no_points_y=round(120/pixel_binning_row);

qr_min=-0.2; % [A^(-1)]

qr_max=0.2; % [A^(-1)]

qz_min=0.0; % [A^(-1)]

qz_max=0.2; % [A^(-1)]

Here, for example, 250 points is sampling of original image in horizontal direction and 120 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 154 line of my script (find matrix integrate_image).

The pixel binning is hapenning between 160 and 175 lines of my script (find matrix new_image).

Your reshaped image is in matrix img_reshaped.

On line 235, the reshaped image matrices from your time-resolved experiment are saved as ascii file or text file.

You can import your reshaped matrices to Origin visualization software and plot them as colormaps for your publications.

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 133 with obj=gixsdata(full_path_to_image);. It creates object for existing time-resolved image in time-binning loop. The object is destroyed or deleted in line 157. The time-binned image is pixel-binned between lines 160 and 175. Then, new gixsdata object is created in line 203 (obj=gixsdata(full_path_to_image_create);) for time-binned and pixel-binned image. The pixel-binned image is calibrated and reshaped to reciprocal space. The object for time-binned and pixel-binned image is destroyed or deleted in line 237.