Calibration tool: MX-calibrate
==============================

Purpose
-------
MX-Calibrate - calibrate the distance of a detector from a set of powder
diffraction patterns taken at various sample-detector distance.

This tool has been developed for ESRF MX-beamlines where an acceptable calibration is
usually present is the header of the image. PyFAI reads it and does a "recalib" on
each of them before exporting a linear regression of all parameters versus this distance.

Most standard calibrants are directly installed together with pyFAI.
If you prefer using your own, you can provide a "d-spacing" file
containing the spacing of Miller plans in Angstrom (in decreasing order).
Most crystal powders used for calibration are available in the American Mineralogist
database [AMD]_ or in the [COD]_.

Nota: this tool is deprecated in favor of the jupyter notebook found in the documentation
(with the same name).

Usage:
------

MX-Calibrate -w 1.54 -c CeO2 file1.cbf file2.cbf ...

Options:
--------
usage: MX-Calibrate -w 1.54 -c CeO2 file1.cbf file2.cbf ...

Calibrate automatically a set of frames taken at various sample-detector
distance. Return the linear regression of the fit in funtion of the sample-
detector distance.

Options:
--------

**-h**, **--help**
   show this help message and exit

**-V**, **--version**
   show program's version number and exit

**-v**, **--verbose**
   switch to debug/verbose mode

**-c** FILE, **--calibrant** FILE
   file containing d-spacing of the calibrant reference sample
   (MANDATORY)

**-w** WAVELENGTH, **--wavelength** WAVELENGTH
   wavelength of the X-Ray beam in Angstrom

**-e** ENERGY, **--energy** ENERGY
   energy of the X-Ray beam in keV (hc=12.398419843320026keV.A)

**-P** POLARIZATION_FACTOR, **--polarization** POLARIZATION_FACTOR
   polarization factor, from **-1** (vertical) to +1 (horizontal),
   default is 0, synchrotrons are around 0.95

**-b** BACKGROUND, **--background** BACKGROUND
   Automatic background subtraction if no value are provided

**-d** DARK, **--dark** DARK
   list of dark images to average and subtract

**-f** FLAT, **--flat** FLAT
   list of flat images to average and divide

**-s** SPLINE, **--spline** SPLINE
   spline file describing the detector distortion

**-p** PIXEL, **--pixel** PIXEL
   size of the pixel in micron

**-D** DETECTOR_NAME, **--detector** DETECTOR_NAME
   Detector name (instead of pixel size+spline)

**-m** MASK, **--mask** MASK
   file containing the mask (for image reconstruction)

**--filter** FILTER
   select the filter, either mean(default), max or median

**--saturation** SATURATION
   consider all pixel>max*(1-saturation) as saturated and reconstruct
   them

**-r** MAX_RINGS, **--ring** MAX_RINGS
   maximum number of rings to extract

**--weighted**
   weight fit by intensity

**-l** DISTANCE, **--distance** DISTANCE
   sample-detector distance in millimeter

**--tilt**
   Allow initially detector tilt to be refined (rot1, rot2, rot3).
   Default: Activated

**--no-tilt**
   Deactivated tilt refinement and set all rotation to 0

**--dist** DIST
   sample-detector distance in meter

**--poni1** PONI1
   poni1 coordinate in meter

**--poni2** PONI2
   poni2 coordinate in meter

**--rot1** ROT1
   rot1 in radians

**--rot2** ROT2
   rot2 in radians

**--rot3** ROT3
   rot3 in radians

**--fix-dist**
   fix the distance parameter

**--free-dist**
   free the distance parameter

**--fix-poni1**
   fix the poni1 parameter

**--free-poni1**
   free the poni1 parameter

**--fix-poni2**
   fix the poni2 parameter

**--free-poni2**
   free the poni2 parameter

**--fix-rot1**
   fix the rot1 parameter

**--free-rot1**
   free the rot1 parameter

**--fix-rot2**
   fix the rot2 parameter

**--free-rot2**
   free the rot2 parameter

**--fix-rot3**
   fix the rot3 parameter

**--free-rot3**
   free the rot3 parameter

**--fix-wavelength**
   fix the wavelength parameter

**--free-wavelength**
   free the wavelength parameter

**--no-gui**
   force the program to run without a Graphical interface

**--gui**
   force the program to run with a Graphical interface

**--no-interactive**
   force the program to run and exit without prompting for refinements

**--interactive**
   force the program to prompt for refinements

**--peak-picker** PEAKPICKER
   Uses the 'massif', 'blob' or 'watershed' peak-picker algorithm
   (default: blob)

This tool has been developed for ESRF MX-beamlines where an acceptable
calibration is usually present is the header of the image. PyFAI reads
it and does a "recalib" on each of them before exporting a linear
regression of all parameters versus this distance.