Scripts Reference:

Algorithms

bcdi_flatten_intensity.py

Apply intensity normalization of additive spatially multiplexed patterns with n
encoded phases, as described in:
R. Jaurez-Salazar et al. Optics and Lasers in Engineering 77, 225-229 (2016).

Input: a 3D real intensity array

bcdi_blurring_function.py

Load a 3D BCDI reconstruction (.npz file) containing the field 'amp'. After defining a
support using a threshold on the normalized amplitude, calculate the blurring function
by Richardson-Lucy deconvolution. Extract the resolution from this blurring function in
arbitrary direction. See M. Cherukara et al. Anisotropic nano-scale resolution in 3D
Bragg coherent diffraction imaging.
Appl. Phys. Lett. 113, 203101 (2018); https://doi.org/10.1063/1.5055235

Experiment

bcdi_ccd_calib.py

Area detector calibration, based on ESRF ID01 geometry.

The input should be a list of detector meshes.
Meshes at direct beam and Bragg angle can be combined.
The corresponding HKLs have to be provided.

Frames where the peak is truncated (in the gap...) can be excluded.

bcdi_ccd_calib_cristal.py

Area detector calibration, based on SOLEIL CRISTAL geometry.

The input should be a list of detector meshes.
Meshes at direct beam and Bragg angle can be combined.
The corresponding HKLs have to be provided.

Frames where the peak is truncated (in the gap...) can be excluded.

bcdi_ccd_calib_sixs.py

Script to calibrate the Maxipix detector on SOLEIL SIXS beamline.
command for the mesh detector is e.g.
SBS.mesh delta -0.40 0.70 12 gamma -0.40 0.70 12 1  (do not invert motors)
remove first image of ascan gamma

Graph

bcdi_3D_object_movie.py

Create a movie from a 3D real space reconstruction in each direction. Requires
imagemagick (https://imagemagick.org) or ffmpeg (http://ffmpeg.zeranoe.com/builds/).

bcdi_linecut_diffpattern.py

Graphical user interface for plotting linecuts along particular direction of a 3D array.

For the laboratory frame, the CXI convention is used: z downstream, y vertical,
x outboard. For q, the usual convention is used: qx downstream, qz vertical, qy outboard

bcdi_scan_analysis.py

Open 1Dscans and plot interactively the integrated intensity vs. motor positions in a
user-defined region of interest.

bcdi_scan_movie.py

Create a movie from a scan (i.e. timescan). Requires ffmpeg
(http://ffmpeg.zeranoe.com/builds/).

bcdi_view_mesh.py

Open mesh scans and plot interactively the integrated intensity vs. motor positions for
a user-defined region of interest.

bcdi_view_psf.py

Open and plot the point-spread function (PSF) from a .cxi reconstruction file (from
PyNX). The PSF or the mutual coherence function (FFT of the PSF) can be to be plotted.

bcdi_visu_2D_slice.py

Graphical interface to visualize 2D slices through a 3D stacked dataset.

Preprocessing

bcdi_apodize.py

Apodization applied directly on reciprocal space data, using a 3d Gaussian, Tukey or
Blackman window.

bcdi_concatenate_scans.py

Average several BCDI or CDI scans after an optional alignement step, based on a
threshold on their Pearson correlation coefficient. The alignment of diffraction
patterns can be realized using Python regular grid interpolator, subpixel shift or a
simple roll of pixels. Note that there are many artefacts when interpolating in
reciprocal space, rolling is the best option.

The script expects that datasets have already been stacked, for example using the script
bcdi_preprocessing_BCDI. Relative to root_folder, the stacked data for scan S1 would be
in /root_folder/S1/S1_pynx_suffix and the mask in /root_folder/S1/S1_maskpynx_suffix

In this example, sample_name=["S"] and suffix=["_suffix"], but it could be different for
each dataset (hence the use of a list).

bcdi_interpolate_CDI.py

This script can be used to interpolate the intensity of masked voxels suing the
centrosymmetry property of a 3D diffraction pattern in the forward CDI geometry.
The diffraction pattern should be in an orthonormal frame with identical voxel sizes
in all directions. The mask should be an array of integers (0 or 1) of the same shape
as the diffraction pattern.

bcdi_preprocess.py

Prepare experimental data for Bragg CDI phasing: crop/pad, center, mask, normalize and
filter the data.

Beamlines currently supported: ESRF ID01, SOLEIL CRISTAL, SOLEIL SIXS, PETRAIII P10 and
APS 34ID-C.

The directory structure expected by default is (e.g. scan 1):
specfile, hotpixels file and flatfield file in:    /rootdir/
data in:                                           /rootdir/S1/data/

output files saved in:   /rootdir/S1/pynxraw/ or /rootdir/S1/pynx/ depending on the
'use_rawdata' option.

If you directory structure is different, you can use the parameter data_dir to indicate
where the data is.

Usage:

 - command line:
   `python path_to/bcdi_preprocess.py --config_file path_to/config.yml`
 - directly from a code editor:
   update the constant CONFIG_FILE at the top of the file

    Parameters related to path names:

    :param scans: e.g. 11
     scan number or list of scan numbers
    :param detector_on_goniometer: e.g. True
     True if the detector is on a goniometer, False if its plane is alway perpendicular
     to the direct beam independently of its position.
    :param root_folder: e.g. "C:/Users/Jerome/Documents/data/dataset_ID01/"
     folder of the experiment, where all scans are stored
    :param save_dir: e.g. "C:/Users/Jerome/Documents/data/dataset_ID01/test/"
     images will be saved here, leave it to None otherwise. Provide a single path or a
     list of paths for multiple scans.
    :param data_dir: e.g. None
     use this to override the beamline default search path for the data. Provide
     a list of paths for multiple scans.
     :param sample_name: e.g. "S"
     str or list of str of sample names (string in front of the scan number in the
     folder name). If only one name is indicated, it will be repeated to match the
     number of scans.
    :param comment: string use in filenames when saving
    :param colormap: e.g. "turbo"
     "turbo", "custom" or colormap defined in the colorcet package, see
     https://colorcet.holoviz.org/
    :param debug: e.g. False
     True to see plots


    Parameters used in the interactive masking GUI:

    :param flag_interact: e.g. True
     True to interact with plots, False to close it automatically
    :param mask: e.g. "path_to/mask.npz"
     path to a file containing a 3D mask array of the same shape as the data would have
     during interactive masking (binned & cropped/padded). It will be used to mask the
     data if flag_interact is False, or as an initial mask if flag_interact is True.
    :param background_plot: e.g. "0.5"
     background color for the GUI in level of grey in [0,1], 0 being dark. For visual
     comfort during interactive masking.
    :param backend: e.g. "Qt5Agg"
     Backend used in script, change to "Agg" if you want to save the figures without
     showing them (not compaticle with interactive masking). Other possibilities are
     "Qt5Agg" (default) and "module://matplotlib_inline.backend_inline"

    Parameters related to data cropping/padding/centering #

    :param centering_method: e.g. "max"
     Method used to determine the location of the Bragg peak. 'max', 'com'
     (center of mass), or 'max_com' (max along the first axis, center of mass in the
     detector plane). It will be overridden if 'bragg_peak' is provided.
    :param center_fft: e.g. "skip"
     how to crop/pad/center the data, available options: 'crop_sym_ZYX','crop_asym_ZYX',
     'pad_asym_Z_crop_sym_YX', 'pad_sym_Z_crop_asym_YX', 'pad_sym_Z', 'pad_asym_Z',
     'pad_sym_ZYX','pad_asym_ZYX' or 'skip'
    :param pad_size: e.g. [256, 512, 512]
     Use this to pad the array. Used in 'pad_sym_Z_crop_sym_YX', 'pad_sym_Z' and
     'pad_sym_ZYX'. Leave None otherwise.

    Parameters for data filtering

    :param mask_zero_event: e.g. False
    mask pixels where the sum along the rocking curve is zero may be dead pixels
    :param median_filter: e.g. "skip"
     which filter to apply, available filters:

     - 'median': to apply a med2filter [3,3]
     - 'interp_isolated': to interpolate isolated empty pixels based on 'medfilt_order'
       parameter
     - 'mask_isolated': mask isolated empty pixels
     - 'skip': skip filtering

    :param median_filter_order: e.g. 7
     minimum number of non-zero neighboring pixels to apply filtering

    Parameters used when reloading processed data

    :param reload_previous: e.g. False
     True to resume a previous masking (load data and mask)
    :param reload_orthogonal: e.g. False
     True if the reloaded data is already intepolated in an orthonormal frame
    :param preprocessing_binning: e.g. [1, 1, 1]
     binning factors in each dimension of the binned data to be reloaded

    Options for saving:

    :param save_rawdata: e.g. False
     True to save also the raw data when use_rawdata is False
    :param save_to_npz: e.g. True
     True to save the processed data in npz format
    :param save_to_mat: e.g. False
     True to save also in .mat format
    :param save_to_vti: e.g. False
     True to save the orthogonalized diffraction pattern to VTK file
    :param save_as_int: e.g. False
     True to save the result as an array of integers (save space)

    Parameters for the beamline:

    :param beamline: e.g. "ID01"
     name of the beamline, used for data loading and normalization by monitor
    :param actuators: e.g. {'rocking_angle': 'actuator_1_1'}
     optional dictionary that can be used to define the entries corresponding to
     actuators in data files (useful at CRISTAL where the location of data keeps
     changing, or to declare a non-standard monitor)
    :param is_series: e.g. True
     specific to series measurement at P10
    :param rocking_angle: e.g. "outofplane"
     "outofplane" for a sample rotation around x outboard, "inplane" for a sample
     rotation around y vertical up, "energy"
    :param specfile_name: e.g. "l5.spec"
     string or list of strings for multiple scans. beamline-dependent parameter,
     use the following template:

     - template for ID01 and 34ID: name of the spec file if it is at the default
      location (in root_folder) or full path to the spec file
     - template for SIXS: full path of the alias dictionnary or None to use the one in
      the package folder
     - for P10, either None (if you are using the same directory structure as the
      beamline) or the full path to the .fio file
     - template for all other beamlines: None

    Parameters for custom scans:

    :param custom_scan: e.g. False
     True for a stack of images acquired without scan, e.g. with ct in a
     macro, or when there is no spec/log file available
    :param custom_images: list of image numbers for the custom_scan, None otherwise
    :param custom_monitor: list of monitor values for normalization for the custom_scan,
     None otherwise

    Parameters for the detector:

    :param detector: e.g. "Maxipix"
     name of the detector
    :param phasing_binning: e.g. [1, 2, 2]
     binning to apply to the data (stacking dimension, detector vertical axis, detector
     horizontal axis)
    :param correct_curvature: e.g. True
     Correct for the curvature of Ewald sphere. You can use False only at P10_SAXS
     (~ 8keV).
    :param linearity_func: e.g. [1, -2, -0.0021, 32.0, 1.232]
     coefficients of the 4th order polynomial ax^4 + bx^3 + cx^2 + dx + e which it used
     to correct the non-linearity of the detector at high intensities. Leave None
     otherwise.
    :param center_roi_x: e.g. 1577
     horizontal pixel number of the center of the ROI for data loading.
     Leave None to use the full detector.
    :param center_roi_y: e.g. 833
     vertical pixel number of the center of the ROI for data loading.
     Leave None to use the full detector.
    :param roi_detector: e.g.[0, 250, 10, 210]
     region of interest of the detector to load. If "center_roi_x" or "center_roi_y" are
     not None, it will consider that the current values in roi_detector define a window
     around the pixel [center_roi_y, center_roi_x] and the final output will be
     [center_roi_y - roi_detector[0], center_roi_y + roi_detector[1],
     center_roi_x - roi_detector[2], center_roi_x + roi_detector[3]].
     Leave None to use the full detector. Use with center_fft='skip' if you want this
     exact size for the output.
    :param normalize_flux: e.g. "monitor"
     'monitor' to normalize the intensity by the default monitor values,
     'skip' to do nothing
    :param photon_threshold: e.g. 0
     voxels with a smaller intensity will be set to 0.
    :param photon_filter: e.g. "loading"
     'loading' or 'postprocessing', when the photon threshold should be applied.
     If 'loading', it is applied before binning; if 'postprocessing', it is applied at
     the end of the script before saving
    :param bin_during_loading: e.g. False
     True to bin during loading, faster
    :param frames_pattern: None or list of int.
     Use this if you need to remove some frames, and you know it in advance. You can
     provide a binary list of length the number of images in the dataset. If
     frames_pattern is 0 at index, the frame at data[index] will be skipped, if 1 the
     frame will be added to the stack. Or you can directly specify the indices of the
     frames to be skipped, e.g. [0, 127] to skip frames at indices 0 and 127.
    :param background_file: non-empty file path or None
    :param hotpixels_file: non-empty file path or None
    :param flatfield_file: non-empty file path or None
    :param template_imagefile: e.g. "data_mpx4_%05d.edf.gz"
     string or list of strings for multiple scans. beamline-dependent parameter,
     use the following template:

     - template for ID01: 'data_mpx4_%05d.edf.gz' or 'align_eiger2M_%05d.edf.gz'
     - template for SIXS_2018: 'align.spec_ascan_mu_%05d.nxs'
     - template for SIXS_2019: 'spare_ascan_mu_%05d.nxs'
     - template for Cristal: 'S%d.nxs'
     - template for P10: '_master.h5'
     - template for NANOMAX: '%06d.h5'
     - template for 34ID: 'some_name_%05d.tif'

    Parameters specific to tomography-like CDI datasets:

    :param dirbeam_detector_position: e.g. [12.12, 43.05, -23.34]
     Position of the detector [z, y, x] for the direct beam measurement in the
     laboratory frame (z downstream, y vertical up, x outboard)
    :param fit_datarange: e.g. True
     If True, crop the final array within the defined data range, avoiding empty areas
     at the corners of the interpolation window: the defined data is a cylinder
     (of axis the axis of rotation), but the interpolation window is rectangular, with
     nan values outside of data. Set it to False for BCDI (e.g. ID27).
    :param correct_curvature: e.g. True
     True to correcture q values for the curvature of Ewald sphere.

    Parameters below if you want to orthogonalize the data before phasing:

    :param use_rawdata: e.g. True
     False for using data gridded in laboratory frame, True for using data in detector
     frame
    :param interpolation_method: e.g. "xrayutilities"
     'xrayutilities' or 'linearization'
    :param fill_value_mask: e.g. 0
     0 (not masked) or 1 (masked). It will define how the pixels outside of the data
     range are processed during the interpolation. Because of the large number of masked
     pixels, phase retrieval converges better if the pixels are not masked (0 intensity
     imposed). The data is by default set to 0 outside of the defined range.
    :param beam_direction: e.g. [1, 0, 0]
     beam direction in the laboratory frame (downstream, vertical up, outboard)
    :param sample_offsets: e.g. None
     tuple of offsets in degrees of the sample for each sample circle (outer first).
     convention: the sample offsets will be subtracted to the motor values. Leave None
     if there is no offset.
    :param detector_distance: e.g. 0.50678
     in m, sample to detector distance in m
    :param energy: e.g. 9000
     X-ray energy in eV, it can be a number or a list in case of energy scans. Leave
     None to use the default from the log file.
    :param direct_beam: e.g. [125, 362]
     [vertical, horizontal]
     BCDI: direct beam position on the unbinned, full detector measured with detector
     angles given by `dirbeam_detector_angles`. It will be used to calculate the real
     detector angles for the measured Bragg peak. Leave None for no correction.
     CDI: direct beam position on the unbinned, full detector measured at the detector
     position given by dirbeam_detector_position. It will be used to calculate q values.
    :param custom_motors: e.g. {"mu": 0, "phi": -15.98, "chi": 90, "theta": 0,
     "delta": -0.5685, "gamma": 33.3147}
     use this to declare motor positions if there is not log file, None otherwise

    Parameters when orthogonalizing the data before phasing  using the linearized
    transformation matrix:

    :param align_q: e.g. True
     if True it rotates the crystal to align q, along one axis of the array. It is used
     only when interp_method is 'linearization'
    :param ref_axis_q: e.g. "y"  # q will be aligned along that axis
    :param dirbeam_detector_angles: e.g. [1, 25]
     [outofplane, inplane] detector angles in degrees for the direct beam measurement.
     Leave None for no correction
    :param bragg_peak: e.g. [121, 321, 256]
     Bragg peak position [z_bragg, y_bragg, x_bragg] considering the unbinned full
     detector. If 'outofplane_angle' and 'inplane_angle' are None and the direct beam
     position is provided, it will be used to calculate the correct detector angles.
     It is useful if there are hotpixels or intense aliens. Leave None otherwise.
    :param outofplane_angle: e.g. 42.6093
     detector angle in deg (rotation around x outboard, typically delta), corrected for
     the direct beam position. Leave None to use the uncorrected position.
    :param inplane_angle: e.g. -0.5783
     detector angle in deg(rotation around y vertical up, typically gamma), corrected
     for the direct beam position. Leave None to use the uncorrected position.

    Parameters when orthogonalizing the data before phasing  using xrayutilities.
    xrayutilities uses the xyz crystal frame (for zero incident angle x is downstream,
    y outboard, and z vertical up):

    :param sample_inplane: e.g. [1, 0, 0]
     sample inplane reference direction along the beam at 0 angles in xrayutilities
     frame
    :param sample_outofplane: e.g. [0, 0, 1]
     surface normal of the sample at 0 angles in xrayutilities frame
    :param offset_inplane: e.g. 0
     outer detector angle offset as determined by xrayutilities area detector
     initialization
    :param cch1: e.g. 208
     direct beam vertical position in the full unbinned detector for xrayutilities 2D
     detector calibration
    :param cch2: e.g. 154
     direct beam horizontal position in the full unbinned detector for xrayutilities 2D
     detector calibration
    :param detrot: e.g. 0
     detrot parameter from xrayutilities 2D detector calibration
    :param tiltazimuth: e.g. 360
     tiltazimuth parameter from xrayutilities 2D detector calibration
    :param tilt_detector: e.g. 0
     tilt parameter from xrayutilities 2D detector calibration

bcdi_read_BCDI_scan.py

Open a rocking curve data, plot the mask, the monitor and the stack along the first
axis.

It is usefull when you want to localize the Bragg peak for ROI determination.

Supported beamlines: ESRF ID01, PETRAIII P10, SOLEIL SIXS, SOLEIL CRISTAL.

bcdi_read_edf.py

Read .edf image (ESRF data format).

bcdi_read_data_P10.py

Open images or series data at P10 beamline.

bcdi_rescale_support.py

Create a support from a reconstruction, using the indicated threshold. The support
can be cropped/padded to a desired shape. In real space the CXI convention is used:
z downstream, y vertical up, x outboard. In reciprocal space, the following
convention is used: qx downtream, qz vertical up, qy outboard.

bcdi_rotate_scan.py

Rotate a 3D reciprocal space map around some axis. The data is expected to be in an
orthonormal frame.

Postprocessing

bcdi_amp_histogram.py

Plot the modulus histogram of a complex object reconstructed by phase retrieval.

bcdi_angular_profile.py

This script allow to plot the width of a 2D object in function of the angle and a
modulus threshold defining the object from the background. Must be given as input:
the voxel size (possibly different in all directions), the angular step size and an
origin point where all linecuts pass by.

bcdi_bulk_surface_strain.py

Extract the surface voxel layer of an object recontructed by BCDI phase retrieval and
plot histograms of the strain at the surface and in the remaining bulk.
Input: a .npz file containing fields 'amp' and 'strain' (e.g., S130_amp_disp_strain.npz)

bcdi_compare_BCDI_SEM.py

This script can be used to compare the lateral sizes of an object measured by CDI and
scanning electron micrscopy. Two dictionary should be provided as input
(one for each technique). The dictionary should contain the following items:
{'threshold': 1D array-like values of thresholds,
 'angles':D array-like values of angles
 'ang_width_threshold': 2D array-like values (one row for each threshold,
 the row is the width vs angle of the linecut)}

These dictionaries can be produced by the script angular_profile.py

After aligning the traces of the width vs angle (e.g. if the object was slightly
rotated in one of the measurements), the traces are overlaid in order to determine
which threshold is correct.

bcdi_correct_angles_detector.py

Calculate exact inplane and out-of-plane detector angles from the direct beam and
Bragg peak positions, based on the beamline geometry. For Pt samples it gives also an
estimation of the temperature based on the thermal expansion.

Supported beamlines: ESRF ID01, PETRAIII P10, SOLEIL SIXS, SOLEIL CRISTAL.

Input: direct beam and Bragg peak position, sample to detector distance, energy.
Output: corrected inplane, out-of-plane detector angles for the Bragg peak.

bcdi_facet_strain.py

Script for detecting facets on a 3D crytal reconstructed by a phasing algorithm
(Bragg CDI) and making some statistics about strain by facet. The correct threshold
for support determination should be given as input, as well as voxel sizes for a
correct calculation of facet angle.

Input: a reconstruction .npz file with fields: 'amp' and 'strain'
Output: a log file with strain statistics by plane, a VTK file for 3D visualization of
detected planes.

bcdi_line_profile.py

This script allow to plot and save linecuts through a 2D or 3D object in function of a
modulus threshold defining the object from the background. Must be given as input:
the voxel size (possibly different in all directions),  the direction of the cuts and
a list of points where to apply the cut along this direction.

bcdi_modes_decomposition.py

Eigendecomposition of a set of 3D reconstructed objects from phase retrieval,
ideally the first mode should be as high as possible. Adapted from PyNX.

bcdi_polarplot.py

Stereographic projection of a measured 3D diffraction pattern or calculated from a
real-space BCDI reconstruction. A shell dq of reciprocal space located a radius_mean
(in q) from the Bragg peak is projected from the South pole and the North onto the
equatorial plane.

The coordinate system follows the CXI convention: Z downstream, Y vertical up and X
outboard. Q values follow the more classical convention: qx downstream, qz vertical
up, qy outboard.

bcdi_post_process_BCDI_2D.py

starting from a 2D complex object (output of phasing program), center the object,
remove the phase ramp, the phase offset and wrap the phase.

bcdi_prtf_BCDI.py

Calculate the resolution of a BCDI reconstruction using the phase retrieval transfer
function (PRTF). The measured diffraction pattern and reconstructions should be in
the detector frame, before phase ramp removal and centering. An optional mask can be
provided.

For the laboratory frame, the CXI convention is used: z downstream, y vertical,
x outboard. For q, the usual convention is used: qx downstream, qz vertical, qy outboard

Supported beamline: ESRF ID01, PETRAIII P10, SOLEIL SIXS, SOLEIL CRISTAL

Path structure:
    specfile in /root_folder/
    data in /root_folder/S2191/data/

bcdi_prtf_BCDI_2D.py

Calculate the resolution of a 2D BCDI reconstruction using the phase retrieval
transfer function (PRTF). The measured diffraction pattern and reconstructions should
be in the detector frame, before phase ramp removal and centering. An optional mask
can be provided.

For the laboratory frame, the CXI convention is used: z downstream, y vertical,
x outboard. For q, the usual convention is used: qx downstream, qz vertical, qy outboard

Supported beamline: ESRF ID01, PETRAIII P10, SOLEIL SIXS, SOLEIL CRISTAL

Path structure:
    specfile in /root_folder/
    data in /root_folder/S2191/data/

bcdi_prtf_CDI.py

Calculate the resolution of a forward CDI reconstruction using the phase retrieval
transfer function (PRTF). The diffraction pattern and reconstructions should be in
the orthogonal laboratory frame. Q values need to be provided.

For the laboratory frame, the CXI convention is used: z downstream, y vertical,
x outboard. For q, the usual convention is used: qx downstream, qz vertical, qy outboard

bcdi_rocking_curves.py

Open a series of rocking curve data and track the position of the Bragg peak over the
series. Supported beamlines: ESRF ID01, PETRAIII P10, SOLEIL SIXS, SOLEIL CRISTAL,
MAX IV NANOMAX.

bcdi_strain.py

Interpolate the output of the phase retrieval into an orthonormal frame,
and calculate the strain component along the direction of the experimental diffusion
vector q.

Input: complex amplitude array, output from a phase retrieval program.
Output: data in an orthonormal frame (laboratory or crystal frame), amp_disp_strain
array.The disp array should be divided by q to get the displacement (disp = -1*phase
here).

Laboratory frame: z downstream, y vertical, x outboard (CXI convention)
Crystal reciprocal frame: qx downstream, qz vertical, qy outboard
Detector convention: when out_of_plane angle=0   Y=-y , when in_plane angle=0   X=x

In arrays, when plotting the first parameter is the row (vertical axis), and the
second the column (horizontal axis). Therefore the data structure is data[qx, qz,
qy] for reciprocal space, or data[z, y, x] for real space

Usage:

 - from the command line:
   `python path_to/bcdi_strain.py --config_file path_to/config.yml`
 - directly from a code editor:
   update the constant CONFIG_FILE at the top of the file

    Parameters related to path names:

    :param scans: e.g. 11
     scan number or list of scan numbers
    :param root_folder: e.g. "C:/Users/Jerome/Documents/data/dataset_ID01/"
     folder of the experiment, where all scans are stored
    :param save_dir: e.g. "C:/Users/Jerome/Documents/data/dataset_ID01/test/"
     images will be saved here, leave it to None otherwise. Provide a single path or a
     list of paths for multiple scans.
    :param data_dir: e.g. None
     use this to override the beamline default search path for the data. Provide
     a list of paths for multiple scans.
    :param sample_name: e.g. "S"
     str or list of str of sample names (string in front of the scan number in the
     folder name). If only one name is indicated, it will be repeated to match the
     number of scans.
    :param comment: string use in filenames when saving
    :param debug: e.g. False
     True to see plots
    :param colormap: e.g. "turbo"
     "turbo", "custom" or colormap defined in the colorcet package, see
     https://colorcet.holoviz.org/
    :param reconstruction_files: e.g. "C:/Users/Jerome/Documents/data/modes.h5"
     full path to the output of phase retrieval, or list of such paths if 'scans' is a
     list. Providing several reconstructions for each scan is not supported.
     If None an interactive window will open to choose a file.

    Parameters used in the interactive masking GUI:

    :param backend: e.g. "Qt5Agg"
     Backend used in script, change to "Agg" if you want to save the figures without
     showing them. Other possibilities are "Qt5Agg" (default) and
     "module://matplotlib_inline.backend_inline"

    Parameters used when averaging several reconstruction:

    :param sort_method: e.g. "variance/mean"
     'mean_amplitude' or 'variance' or 'variance/mean' or 'volume', metric for averaging
    :param averaging_space: e.g. "reciprocal_space"
     in which space to average, 'direct_space' or 'reciprocal_space'
    :param correlation_threshold: e.g. 0.90
     minimum correlation between two arrays to average them

    Parameters related to centering:

    :param centering_method: e.g. {"direct_space": "max_com", "reciprocal_space": "max"}
     dictionary with the centering methods for direct and reciprocal space. The methods
     supported are 'com' (center of mass), 'max', 'max_com' (max along the first axis,
     center of mass in the detector plane), 'skip'. If a simple string is provided, it
     will use that method for both direct and reciprocal space.
    :param roll_modes: e.g. [0, 0, 0]
    correct a roll of few pixels after the decomposition into modes in PyNX
    axis=(0, 1, 2)

    Prameters relative to the FFT window and voxel sizes:

    :param original_size: e.g. [150, 256, 500]
     size of the FFT array before binning. It will be modified to take into account
     binning during phasing automatically. Leave it to None if the shape did not change.
    :param phasing_binning: e.g. [1, 1, 1]
     binning factor applied during phase retrieval
    :param preprocessing_binning: e.g. [1, 2, 2]
     binning factors in each dimension used in preprocessing (not phase retrieval)
    :param output_size: e.g. [100, 100, 100]
     (z, y, x) Fix the size of the output array, leave None to use the object size
    :plot_margin: e.g. 30
     margin to add on each side of the smallest box around the crystal. Use this to
     increase the box size in case the interpolated crystal is cropped.
    :param keep_size: e.g. False
     True to keep the initial array size for orthogonalization (slower), it will be
     cropped otherwise
    :param fix_voxel: e.g. 10
     voxel size in nm for the interpolation during the geometrical transformation.
     If a single value is provided, the voxel size will be identical in all 3
     directions. Set it to None to use the default voxel size (calculated from q values,
     it will be different in each dimension).

    Parameters related to the strain calculation:

    :param data_frame: e.g. "detector"
     in which frame is defined the input data, available options:

     - 'crystal' if the data was interpolated into the crystal frame using
       xrayutilities or (transformation matrix + align_q=True)
     - 'laboratory' if the data was interpolated into the laboratory frame using
       the transformation matrix (align_q: False)
     - 'detector' if the data is still in the detector frame

    :param ref_axis_q: e.g. "y"
     axis along which q will be aligned (data_frame= 'detector' or 'laboratory') or is
     already aligned (data_frame='crystal')
    :param save_frame: e.g. "laboratory"
     in which frame should be saved the data, available options:

     - 'crystal' to save the data with q aligned along ref_axis_q
     - 'laboratory' to save the data in the laboratory frame (experimental geometry)
     - 'lab_flat_sample' to save the data in the laboratory frame, with all sample
       angles rotated back to 0. The rotations for 'laboratory' and 'lab_flat_sample'
       are realized after the strain calculation (which is always done in the crystal
       frame along ref_axis_q)

    :param isosurface_strain: e.g. 0.2
     threshold use for removing the outer layer (the strain is undefined at the exact
     surface voxel)
    :param skip_unwrap: e.g. False
     If 'skip_unwrap', it will not unwrap the phase. It can be used when there is a
     defect and phase unwrapping does not work well.
    :param strain_method: e.g. "default"
     how to calculate the strain, available options:

     - 'default': use the single value calculated from the gradient of the phase
     - 'defect': it will offset the phase in a loop and keep the smallest magnitude
       value for the strain. See: F. Hofmann et al. PhysRevMaterials 4, 013801 (2020)

    Parameters for the beamline:

    :param beamline: e.g. "ID01"
     name of the beamline, used for data loading and normalization by monitor
    :param is_series: e.g. True
     specific to series measurement at P10.
    :param actuators: e.g. {'rocking_angle': 'actuator_1_1'}
     optional dictionary that can be used to define the entries corresponding to
     actuators in data files (useful at CRISTAL where the location of data keeps
     changing, or to declare a non-standard monitor)
    :param rocking_angle: e.g. "outofplane"
     "outofplane" for a sample rotation around x outboard, "inplane" for a sample
     rotation around y vertical up
    :param sdd: e.g. 0.50678
     in m, sample to detector distance in m
    :param energy: e.g. 9000
     X-ray energy in eV, leave None to use the default from the log file.
    :param beam_direction: e.g. [1, 0, 0]
     beam direction in the laboratory frame (downstream, vertical up, outboard)
    :param sample_offsets: e.g. None
     tuple of offsets in degrees of the sample for each sample circle (outer first).
     convention: the sample offsets will be subtracted to the motor values. Leave None
     if there is no offset.
    :param tilt_angle: e.g. 0.00537
     angular step size in degrees for the rocking angle
    :param direct_beam: e.g. [125, 362]
     [vertical, horizontal], direct beam position on the unbinned, full detector
     measured with detector angles given by `dirbeam_detector_angles`. It will be used
     to calculate the real detector angles for the measured Bragg peak. Leave None for
     no correction.
    :param dirbeam_detector_angles: e.g. [1, 25]
     [outofplane, inplane] detector angles in degrees for the direct beam measurement.
     Leave None for no correction
    :param bragg_peak: e.g. [121, 321, 256]
     Bragg peak position [z_bragg, y_bragg, x_bragg] considering the unbinned full
     detector. If 'outofplane_angle' and 'inplane_angle' are None and the direct beam
     position is provided, it will be used to calculate the correct detector angles.
     It is useful if there are hotpixels or intense aliens. Leave None otherwise.
    :param outofplane_angle: e.g. 42.6093
     detector angle in deg (rotation around x outboard, typically delta), corrected for
     the direct beam position. Leave None to use the uncorrected position.
    :param inplane_angle: e.g. -0.5783
     detector angle in deg(rotation around y vertical up, typically gamma), corrected
     for the direct beam position. Leave None to use the uncorrected position.
    :param specfile_name: e.g. "l5.spec"
     string or list of strings for multiple scans. beamline-dependent parameter,
     use the following template:

     - template for ID01 and 34ID: name of the spec file if it is at the default
      location (in root_folder) or full path to the spec file
     - template for SIXS: full path of the alias dictionnary or None to use the one in
      the package folder
     - for P10, either None (if you are using the same directory structure as the
      beamline) or the full path to the .fio file
     - template for all other beamlines: None

    Parameters for custom scans:

    :param custom_scan: e.g. False
     True for a stack of images acquired without scan, e.g. with ct in a
     macro, or when there is no spec/log file available
    :param custom_images: list of image numbers for the custom_scan, None otherwise
    :param custom_monitor: list of monitor values for normalization for the custom_scan,
     None otherwise
    :param custom_motors: e.g. {"delta": 5.5, "gamma": 42.2, "theta": 1.1, "phi": 0}
     dictionary providing the goniometer positions of the beamline

    Parameters for the detector:

    :param detector: e.g. "Maxipix"
     name of the detector
    :param pixel_size: e.g. 100e-6
     use this to declare the pixel size of the "Dummy" detector if different from 55e-6
    :param center_roi_x: e.g. 1577
     horizontal pixel number of the center of the ROI for data loading.
     Leave None to use the full detector.
    :param center_roi_y: e.g. 833
     vertical pixel number of the center of the ROI for data loading.
     Leave None to use the full detector.
    :param roi_detector: e.g.[0, 250, 10, 210]
     region of interest of the detector to load. If "center_roi_x" or "center_roi_y" are
     not None, it will consider that the current values in roi_detector define a window
     around the pixel [center_roi_y, center_roi_x] and the final output will be
     [center_roi_y - roi_detector[0], center_roi_y + roi_detector[1],
     center_roi_x - roi_detector[2], center_roi_x + roi_detector[3]].
     Leave None to use the full detector. Use with center_fft='skip' if you want this
     exact size for the output.
    :param template_imagefile: e.g. "data_mpx4_%05d.edf.gz"
     string or list of strings for multiple scans. beamline-dependent parameter,
     use the following template:

     - template for ID01: 'data_mpx4_%05d.edf.gz' or 'align_eiger2M_%05d.edf.gz'
     - template for SIXS_2018: 'align.spec_ascan_mu_%05d.nxs'
     - template for SIXS_2019: 'spare_ascan_mu_%05d.nxs'
     - template for Cristal: 'S%d.nxs'
     - template for P10: '_master.h5'
     - template for NANOMAX: '%06d.h5'
     - template for 34ID: 'Sample%dC_ES_data_51_256_256.npz'

    Parameters related to the refraction correction:

    :param correct_refraction: e.g. True
     True for correcting the phase shift due to refraction
    :param optical_path_method: e.g. "threshold"
     'threshold' or 'defect', if 'threshold' it uses isosurface_strain to define the
     support  for the optical path calculation, if 'defect' (holes) it tries to remove
     only outer layers even if the amplitude is lower than isosurface_strain inside
     the crystal
    :param dispersion: e.g. 5.0328e-05
     delta value used for refraction correction, for Pt:  3.0761E-05 @ 10300eV,
     5.0328E-05 @ 8170eV, 3.2880E-05 @ 9994eV, 4.1184E-05 @ 8994eV, 5.2647E-05 @ 7994eV,
     4.6353E-05 @ 8500eV / Ge 1.4718E-05 @ 8keV
    :param absorption: e.g. 4.1969e-06
     beta value, for Pt:  2.0982E-06 @ 10300eV, 4.8341E-06 @ 8170eV,
     2.3486E-06 @ 9994eV, 3.4298E-06 @ 8994eV, 5.2245E-06 @ 7994eV, 4.1969E-06 @ 8500eV
    :param threshold_unwrap_refraction: e.g. 0.05
     threshold used to calculate the optical path. The threshold for refraction
     correction should be low, to correct for an object larger than the real one,
     otherwise it messes up the phase

    Parameters related to the phase:

    :param simulation: e.g. False
     True if it is a simulation, the parameter invert_phase will be set to 0 (see below)
    :param invert_phase: e.g. True
    True for the displacement to have the right sign (FFT convention), it is False only
    for simulations
    :param flip_reconstruction: e.g. True
     True if you want to get the conjugate object
    :param phase_ramp_removal: e.g. "gradient"
     'gradient' or 'upsampling', 'gradient' is much faster
    :param threshold_gradient: e.g. 1.0
     upper threshold of the gradient of the phase, use for ramp removal
    :param phase_offset: e.g. 0
     manual offset to add to the phase, should be 0 in most cases
    :param phase_offset_origin: e.g. [12, 32, 65]
     the phase at this voxel will be set to phase_offset, leave None to use the default
     position computed using offset_method (see below)
    :param offset_method: e.g. "mean"
     'com' (center of mass) or 'mean', method for determining the phase offset origin

    Parameters related to data visualization:

    :param align_axis: e.g. False
     True to rotate the crystal to align axis_to_align along ref_axis for visualization.
     This is done after the calculation of the strain and has no effect on it.
    :param ref_axis: e.g. "y"
     it will align axis_to_align to that axis if align_axis is True
    :param axis_to_align: e.g. [-0.01166, 0.9573, -0.2887]
     axis to align with ref_axis in the order x y z (axis 2, axis 1, axis 0)
    :param strain_range: e.g. 0.001
     range of the colorbar for strain plots
    :param phase_range: e.g. 0.4
     range of the colorbar for phase plots
    :param grey_background: e.g. True
     True to set the background to grey in phase and strain plots
    :param tick_spacing: e.g. 50
     spacing between axis ticks in plots, in nm
    :param tick_direction: e.g. "inout"
     direction of the ticks in plots: 'out', 'in', 'inout'
    :param tick_length: e.g. 3
     length of the ticks in plots
    :param tick_width: e.g. 1
     width of the ticks in plots

    Parameters for temperature estimation:

    :param get_temperature: e.g. False
     True to estimate the temperature, only available for platinum at the moment
    :param reflection: e.g. [1, 1, 1]
    measured reflection, use for estimating the temperature from the lattice parameter
    :param reference_spacing: 3.9236
     for calibrating the thermal expansion, if None it is fixed to the one of Platinum
     3.9236/norm(reflection)
    :param reference_temperature: 325
     temperature in Kelvins used to calibrate the thermal expansion, if None it is fixed
     to 293.15K (room temperature)

    Parameters for phase averaging or apodization:

    :param half_width_avg_phase: e.g. 0
     (width-1)/2 of the averaging window for the phase, 0 means no phase averaging
    :param apodize: e.g. False
     True to multiply the diffraction pattern by a filtering window
    :param apodization_window: e.g. "blackman"
     filtering window, multivariate 'normal' or 'tukey' or 'blackman'
    :param apodization_mu: e.g. [0.0, 0.0, 0.0]
     mu of the gaussian window
    :param apodization_sigma: e.g. [0.30, 0.30, 0.30]
     sigma of the gaussian window
    :param apodization_alpha: e.g. [1.0, 1.0, 1.0]
     shape parameter of the tukey window

    Parameters related to saving:

    :param save_rawdata: e.g. False
     True to save the amp-phase.vti before orthogonalization
    :param save_support: e.g. False
     True to save the non-orthogonal support for later phase retrieval
    :param save: e.g. True
     True to save amp.npz, phase.npz, strain.npz and vtk files

bcdi_strain_mean_var_rms.py

Load a 3D BCDI reconstruction (.npz file) containing the fields 'amp' and 'strain'.
Calculate the mean and variance of the strain, for all voxels in the support.

bcdi_volume_phasing.py

Calculate the volume of the reconstruction for different isosurfaces, save and plot
the result.

Publication

bcdi_coefficient_variation.py

Load several reconstructed complex objects and calculate the coefficient variation
(CV = std/mean) on the modulus, the phase or the strain.

In the reconstruction file, the following fieldnames are expected: 'amp', 'bulk',
'phase' for simulated data or 'disp' for experimental data, 'strain'.

It is necessary to know the voxel size of the reconstruction in order to put ticks at
the correct position. Laboratory frame: z downstream, y vertical, x outboard (CXI
convention)

bcdi_compa_simu_exp.py

Template for figures of the following article:
Carnis et al. Scientific Reports 9, 17357 (2019)
https://doi.org/10.1038/s41598-019-53774-2
Open the simulated amp_dist_strain.npz file and the reconstructed
amp_dist_strain.npz, and plot difference maps

bcdi_diffpattern_from_reconstruction.py

Calculate the diffraction pattern corresponding to a reconstructed 3D crystal
(output of phase retrieval). The crystal is expected to be expressed in an orthonormal
frame, and voxel sizes must be provided (voxel sizes can be different in each
dimension).

If q values are provided, the crystal will be resampled so that the extent in q given
by the direct space voxel sizes matches the extent defined by q values. If q values are
not provided, the crystal is padded to the user-defined shape before calculating the
diffraction pattern.

The reconstructed crystal file should be a .NPZ with field names 'amp' for the modulus
and 'displacement' for the phase. Corresponding q values can be loaded optionally.

bcdi_plot_diffpattern_2D.py

Template for figures of the following article:
Carnis et al. Scientific Reports 9, 17357 (2019)
https://doi.org/10.1038/s41598-019-53774-2
For simulated data or experimental data, open a npz file (3D diffraction pattern) and
save individual figures. q values can be provided optionally.
For everything else than q values, the convention is the CXI convention:
(z downstream, y vertical up, x outboard).
For q values, the convention is (qx downstream, qz vertical up, qy outboard).

bcdi_plot_strain.py

Template for figures of the following article:
Carnis et al. Scientific Reports 9, 17357 (2019)
https://doi.org/10.1038/s41598-019-53774-2

Open an amp_dist_strain.npz file and save individual figures.

In the reconstruction file, the following fieldnames are expected: 'amp', 'bulk',
phase' for simulated data or 'disp' for experimental data, 'strain'.

It is necessary to know the voxel size of the reconstruction in order to put ticks
at the correct position.

Simulation

bcdi_diffraction_angles.py

Calculate the position of the Bragg peaks for a material and a particular
diffractometer setup. The crystal frame uses the following convention: x downstream,
y outboard, z vertical.
Supported beamlines:  ESRF ID01, SOLEIL CRISTAL, SOLEIL SIXS and PETRAIII P10.

bcdi_domain_orientation.py

Calculate the position of the Bragg peaks for a mesocrystal given the lattice type,
the unit cell parameter and beamline-related parameters. Assign 3D Gaussians to each
lattice point and rotates the unit cell in order to maximize the cross-correlation of
the simulated data with experimental data. The experimental data should be sparse
(using a photon threshold), and Bragg peaks maximum must be clearly identifiable.

Laboratory frame convention (CXI): z downstream, y vertical up, x outboard.
Reciprocal space basis:            qx downstream, qz vertical up, qy outboard.

bcdi_kinematic_sum_forloop.py

Calculate the FT of an object with displacement, using kinematic sum.

Author: Stephane Labat @ IM2NP
Modif: Jerome Carnis

bcdi_plane_angle.py

Calculate the angle between to crystallographic planes expressed in the triclinic
crystal system.

bcdi_simu_diffpattern_BCDI.py

Using a support created from a reconstructed object (real space), calculate the
diffraction pattern depending on several parameters: detector size, detector distance,
presence/width of a detector gap, Poisson noise, user-defined phase.

The provided reconstructed object is expected to be orthogonalized, in the laboratory
frame.

bcdi_simu_diffpattern_CDI.py

Calculate the position of the Bragg peaks for a mesocrystal given the lattice type,
the unit cell parameter and beamline-related parameters.

Laboratory frame convention (CXI): z downstream, y vertical up, x outboard.

bcdi_simu_signe_phase.py

calculation of the diffraction pattern using FFTs with both conventions and kinematic
sum, to show the relationship between the phase and the displacement.
The object is a Ge-core / Si-shell nanowire.

Utilities

bcdi_angular_avg_3Dto1D.py

Plot a 1D angular average of a 3D reciprocal space map, based on the position of the
origin (direct beam or Bragg peak). If q values are provided, the data can be in an
orthonormal frame or not (detector frame in Bragg CDI). The unit expected for q
values is 1/nm. If q values are not provided, the data is supposed to be in an
orthonormal frame.

bcdi_calibration_grid_SEM.py

This script allow to plot and save linecuts through a 2D SEM image of a calibration
grid. Must be given as input: the voxel size, the direction of the cuts and a list of
points where to apply the cut along this direction. A rectangular profile is fitted
to the maxima.

bcdi_center_of_rotation.py

Calculate the vertical correction and correction along the beam to apply to a
nanocrystal, given the drift along the beam at -/+ delta_angle from the center of the
rocking curve.

bcdi_correlation_realspace.py

Compare the correlation between several 3D objects.

bcdi_crop_npz.py

Crop a stacked 3D dataset saved in NPZ format, to the desired region of interest.

bcdi_cross_corr_fast_live.py

Calculate the cross-correlation of 2D detector images in live.

bcdi_fit_1D_curve.py

Fit a reciprocal space radial profile over selected q ranges using different
lineshapes. The fit is performed simultaneously  over all q ranges defined by the
user; it is possible to define constraints  limiting the number of free fitting
parameters.

bcdi_fit_1D_background.py

Determination of the background in a reciprocal space linecut using an interactive
interface. The background-subtracted data is saved in a different .npz file with the
original field names.

bcdi_parse_fio2spec.py

Script parsing the log file of P10.

bcdi_primes.py

Check smaller or higher prime of a number, in order to determine the correct FFT
window size for phase retrieval. Adapted from PyNX.

bcdi_save_to_mat.py

Load a 2D or 3D object and save it into Matlab .mat format.

XCCA

bcdi_view_ccf.py

Load the output file of xcca_3D_polar.py or xcca_3D_rect.py and plot the
cross-correlation function.

Input: a NPZ file with the fields 'angles', 'ccf', 'points':
    - 'angles': values between [0, 180] where the cross-correlation function was
      calculated
    - 'ccf': cross-correlation function values at these angles
    - 'points': number of points contributing to the cross-correlation function at
      these angles

bcdi_view_ccf_map.py

Load the output file of xcca_3D_map_polar.py or xcca_3D_map_rect.py and plot the 2D
cross-correlation map. When clicking on the 2D map, the 1D cross-correlation at the
clicked q value is plotted.

Input: a NPZ file with the fields 'angles', 'q_range', 'ccf', 'points':
    - 'angles': angle values between [0, 180] where the cross-correlation function
      was calculated
    - 'q_range': q values where the cross-correlation CCF(q,q) was calculated
    - 'ccf': cross-correlation function values at these angles and q_values (2D array)
    - 'points': number of points contributing to the cross-correlation function at
      these angles and q values (2D array)

bcdi_xcca_3D_map_polar.py

Calculate the angular cross-correlation in a 3D reciprocal space dataset over a range
in q values, at the same q value or between two different q values. The 3D dataset is
expected to be interpolated on an orthonormal grid. The intensity used for
cross-correlation calculation is interpolated using the golden spiral method on a
sphere of the desired q radius, using original voxels belonging to a slice at this q
value. Downsampling can be applied for faster calculation.

Input: the 3D dataset, an optional 3D mask, (qx, qy, qz) values

Laboratory frame convention (CXI): z downstream, y vertical up, x outboard.
Reciprocal space basis:            qx downstream, qz vertical up, qy outboard.

bcdi_xcca_3D_map_rect.py

Calculate the angular cross-correlation in a 3D reciprocal space dataset over a range
in q values, at the same q value or between two different q values. The 3D dataset is
expected to be interpolated on an orthonormal grid.  The voxels belonging to a slice at
the defined q value are used for the calculation without further interpolation.

Input: the 3D dataset, an optional 3D mask, (qx, qy, qz) values

Laboratory frame convention (CXI): z downstream, y vertical up, x outboard.
Reciprocal space basis:            qx downstream, qz vertical up, qy outboard.

bcdi_xcca_3D_polar.py

Calculate the angular cross-correlation in a 3D reciprocal space dataset at the same
q value or between two different q values. The 3D dataset is expected to be
interpolated on an orthonormal grid. The intensity used for cross-correlation
calculation is interpolated using the golden spiral method on a sphere of the desired
q radius, using original voxels belonging to a slice at this q value. Downsampling
can be applied for faster calculation.

Input: the 3D dataset, an optional 3D mask, (qx, qy, qz) values

Laboratory frame convention (CXI): z downstream, y vertical up, x outboard.
Reciprocal space basis:            qx downstream, qz vertical up, qy outboard.

bcdi_xcca_3D_rect.py

Calculate the angular cross-correlation in a 3D reciprocal space dataset at the same
q value or between two different q values. The 3D dataset is expected to be
interpolated on an orthonormal grid. The voxels belonging to a slice at the defined q
value are used for the calculation without further interpolation.

Input: the 3D dataset, an optional 3D mask, (qx, qy, qz) values

Laboratory frame convention (CXI): z downstream, y vertical up, x outboard.
Reciprocal space basis:            qx downstream, qz vertical up, qy outboard.