Scripts Reference¶
Command-line scripts are available, both Ptychography and CDI scripts.
Ptychography¶
These are instructions to run the command-line scripts such as pynx-ptycho-cxi, pynx-ptycho-id01, pynx-ptycho-id13, pynx-ptycho-id16a, etc…
This help text can be simply obtained by typing the script without any parameter.
Generic instructions¶
Here are generic instructions applying to all the scripts:
generic (not beamline-specific) command-line arguments: (all keywords are case-insensitive)
scan=56: scan number (e.g. in specfile) [mandatory, unless cxifile is used as input].
Alternatively a list or range of scans can be given:
scan=12,23,45 or scan="range(12,25)" (note the necessary quotes when using range)
maxframe=128: limit the total number of frames used to the first N
[default=None, all frames are used]
maxsize=256: the frames are automatically cropped to the largest possible size while keeping
the center of gravity of diffraction in the frame center. Use this to limit the
maximum frame size, for tests or limiting memory use [default=512]
detectordistance=1.3: detector distance in meters. 'distance=1.3' is also accepted.
This parameter is mandatory unless the file format embeds that information.
obj_max_pix=10000: the maximum allowed size in pixels for the object (by default 8000). This
allows to avoid mistake when scan coordinates are e.g. in meters instead
of microns, resulting in a very large object.
obj_margin=32: margin (in pixels) around the calculated object area. This is useful
when refining positions, to avoid getting outside the object area.
[default: 32]
moduloframe=n1,n2: instead of using all sequential frames of the scan, only take one in n1.
if n2<n1 is also given, then the frame numbers taken will be the n for which
n % n1 == n2. This can be used to perform two reconstructions with half of
the frames, and then analyse the resolution using Fourier ring correlation.
If both moduloframe and maxframe are given, the total number of frames taken
is still maxframe.
[default: take all frames]
algorithm=ML**50,DM**100,probe=1: algorithm for the optimization: [default='ML**50,DM**100']
The algorithm used is:
- divided in 'steps' separated by commas, e.g: ML**50,DM**100
- interpreted from right to left, as a mathematical operator to an object on the
right-hand side
- should not contain any space, unless it is given between quotes ('')
- the first type of commands can change basic parameters or perform some analysis:
- probe=1 or 0: activate or deactivate the probe optimisation (by default only the
object is optimised)
- object=1 or 0: activate or deactivate the object optimisation
- background=1 or 0: activate or deactivate the background optimisation.
When set to 1, this will initialise the background to at least 1e-2 to
enable the background optimisation.
- background_smooth=3: gaussian sigma for smoothing the updated background
[default:3, large values are possible and will use FFT convolution]
- position=N or 0: activate or deactivate (0) position optimisation every N cycles
(preferably for AP or ML, some prior convergence is needed.
Can also work with DM but is not recommended).
Recommended value is every 5 cycles
- pos_mult=1: multiplier for the calculated position shift. Can be used to accelerate
convergence or make it more cautious. (default:5, suitable
for an object with reasonable contrast)
- pos_max_shift: maximum shift of position update in pixels between iterations (default:2)
- pos_min_shift: minimum shift of position update in pixels between iterations (default:0)
- pos_threshold: if the integrated norm of the object gradient multiplied by the probe is lower
than the average value (for all positions) multiplied by this threshold,
the position is not changed. This allows to avoid updating positions
in area where the object is flat, and sensitivity to shifts is low.
[default:0.2]
- nbprobe=3: change the number of modes for the probe (can go up or down)
- regularization=1e-4: setting the regularization parameter for the object, to penalize
local variations in ML runs and smooth the solution
- obj_smooth=1.5 or probe_smooth=1.0: these parameters will partially smooth the object and probe inertia,
softening the resulting arrays. This applies to DM and AP algorithms.
- obj_inertia=0.01 or obj_probe=0.001: these parameters set the inertia of the object and/or probe update,
yielding more stable result. This applies to DM and AP algorithms.
- ortho: will perform orthogonalisation of the probe modes. The modes are sorted by
decreasing intensity.
- analysis: perform an analysis of the probe (propagation, modes). Useful combined
with 'saveplot' to save the analysis plots
- the second type are operators which will be applied to the Ptycho object:
- AP: alternate projections. Slow but converging algorithm
- DM: difference map. Fast early convergence, oscillating after.
- ML: maximum likelihood conjugate gradient (Poisson-noise). Robust, converging,
for final optimization.
These operators can be combined mathematically, e.g.:
- DM**100: corresponds to 100 cycles of difference map
- ML**40*DM**100: 100 cycles of DM followed by 40 cycles of ML (note the order)
Example algorithms chains:
- algorithm=ML**40,DM**100,probe=1: activate probe optimisation,
then 100 DM and 40 ML (quick)
- algorithm=ML**100,DM**200,nbprobe=3,ML**40,DM**100,probe=1,DM**100: first DM with
object update only, then 100 DM also updating the probe, then use 3 probe modes
and do 100 DM followed by 40 ML
- algorithm=ML**100*AP**200*DM**200,probe=1: 200 DM then 200 AP then 100 ML (one step)
- algorithm='(ML**10*DM**20)**5,probe=1':
repeat 5 times [20 cycles of DM followed by 5 cycles of ML]
(note the quotes necessary for the parenthesis)
nbrun=10: number of optimizations to perform [default=1]
run0=10: number for the first run (can be used to overwrite previous run results)
[default: after previous results or 1]
liveplot: liveplot during optimization [default: no display]
saveplot: will save plot at the end of the optimization (png file) [default= not saved].
Optionally this can also specify if only the object phase should be plotted, e.g.:
saveplot=object_phase: will display the object phase
saveplot=object_rgba: will use RGBA to display both amplitude and phase.
saveprefix=ResultsScan%04d/Run%04d: prefix to save the optimized object and probe
(as a .cxi or .npz file) and optionally image (png).
Use "saveprefix=none" to disable saving (e.g. for tests)
This can be used without a sub-directory, e.g. saveprefix=scan%04d_run%04d
[default='ResultsScan%04d/Run%04d']
output_format='cxi': choose the output format for the final object and support.
Possible choices: 'cxi', 'npz'
[Default='cxi']
cxi_output='object_probe': choose the data which will be included in the cxi result file.
This only affects the large object and probe arrays.
- 'object_probe': all object and probe modes are saved as complex objects.
- 'object_phase': only the first mode of the object's phase is saved (as float16).
This is the format which saves the most space
- 'object': save only the complex object
- 'probe': save only the complex probe
remove_obj_phase_ramp=0 or 1: if 1 (True, the default), the final object will be saved after
removing the phase ramp estimated from the imperfect
centring of the diffraction data (sub-pixel shift). Calculated
diffraction patterns using such a corrected object will present
a sub-pixel shift relative to the diffraction data.
save=all: either 'final' or 'all' this keyword will activate saving after each optimization
step (ptycho, ML) of the algorithm in any given run [default=final]
load=Results0057/Run0001.cxi (or .npz): load object and probe from previous optimization. Note that the
object and probe will be scaled if the number of pixels is different for the probe.
[default: start from a random object, simulate probe]
loadprobe=Results0057/Run0001.npz (or .cxi): load only probe from previous optimization
[default: simulate probe]
loadpixelsize=8.6e-9: specify the pixel size (in meters) from a loaded probe
(and possibly object). If the pixel size is different,
the loaded arrays will be scaled to match the new pixel size.
[default: when loading previous files, object/probe pixel size is
calculated from the size of the probe array, assuming same detector
distance and pixel size]
probe=focus,60e-6x200e-6,0.09: define the starting probe, either using:
focus,60e-6x200e-6,0.09: slits size (horizontal x vertical),
focal distance (all in meters)
focus,200e-6,0.09: radius of the circular aperture,
focal distance (all in meters)
gaussian,100e-9x200e-9: gaussian type with horizontal x vertical
FWHM, both given in meters
disc,100e-9: disc-shape, with diameter given in meters
[mandatory, ignored if 'load' or 'loadprobe' is used, or for near-field]
defocus=1e-6: defocused position (+: towards detector). The initial probe is propagated
by this distance before being used. This is true both for calculated probes
(using 'probe=...') and for probes loaded from a previous file.
rotate=30: rotate the probe (either simulated or loaded) by X degrees [default: no rotation]
object=random,0.9,1,0,6: specify the original object values. The object will be initialised
over the entire area using random values: random,0-1,0-6.28 : random
amplitudes between 0 and 1, random phases between 0 and 6.28.
For high energy small-angle ptycho (i.e. high transmission),
recommended value is: random,0.9,1,0,0
[default: random,0,1,0,6.28]
verbose=20: print evolution of llk (and display plot if 'liveplot' is set) every N cycle
[default=50]
data2cxi: if set, the raw data will be saved in CXI format (http://cxidb.org/cxi.html),
will all the required information for a ptychography experiment (energy, detector
distance, scan number, translation axis are all required). if 'data2cxi=crop'
is used, the data will be saved after centering and cropping (default is to save
the raw data). If this keyword is present, the processing stops after exporting the data.
mask= or loadmask=mask.npy: the mask to be used for detector data, which should have the same 2D
shape as the raw detector data.
This should be a boolean or integer array with good pixels=0 and bad ones>0
(values are expected to follow the CXI convention)
Acceptable formats:
- mask.npy, mask.npz (the first data array will be used)
- mask.edf or mask.edf.gz (a single 2D array is expected)
- "mask.h5:/entry_1/path/to/mask" hdf5 format with the full path to the
2D array. 'hdf5' is also accepted as extension.
- 'maxipix': if this special name is entered, the masked pixels will be rows
and columns multiples of 258+/-3
roi=xmin,xmax,ymin,ymax: the region-of-interest to be used for actual inversion. The area is taken
with python conventions, i.e. pixels with indices xmin<= x < xmax and
ymin<= y < ymax.
Additionally, the shape of the area must be square, and
n=xmax-xmin=ymax-ymin must also be a suitable integer number
for OpenCL or CUDA FFT, i.e. it must be a multiple of 2 and the largest number in
its prime factor decomposition must be less or equal to the largest value
acceptable by clFFT (<=13 as of November 2016) or cuFFT (<=7).
If n does not fulfill these constraints,
it will be reduced using the largest possible integer smaller than n.
This option supersedes 'maxsize' unless roi='auto'.
Other possible values:
- 'auto': automatically selects the roi from the center of mass
and the maximum possible size. [default]
- 'all' or 'full': use the entire, uncentered frames. Only useful for pre-processed
data. Cropping may still be performed to get a square and
FFT-friendly size.
rebin=2: the experimental images can be rebinned (i.e. a group of n x n pixels is replaced by a
single one whose intensity is equal to the sum of all the pixels). This 'rebin' is
performed last: the ROI, mask, background, pixel size should all correspond to
full (non-rebinned) frames.
[default: no rebin]
autocenter=0: by default, the object and probe are re-centered automatically after each
optimisation step, to avoid drifts. This can be used to deactivate this behaviour
[default=True]
center_probe_n, center_probe_max_shift: during DM, the probe can shift. The probe center of mass will be checked
every center_probe_n cycles, and the object and probe position will be
corrected if the center deviates by more than center_probe_max_shift pixels.
This is ignored for near field ptycho.
[default: center_probe_n=5, center_probe_max_shift=5]
dm_loop_obj_probe=3: during DM, when both object and probe are updated, it can be more stable to loop the object
and probe update for a more stable optimisation, but slower. [default: 2]
detector_orientation=1,0,0: three flags which, if True, will do in this order:
array transpose (x/y exchange), flipud, fliplr [default: no change]
The changes also apply to the mask.
xy=y,x: order and expression to be used for the XY positions (e.g. '-x,y',...). Mathematical
operations can also be used, e.g.: xy=0.5*x+0.732*y,0.732*x-0.5*y
[default: None- may be superseded in some scripts e.g. for ptypy]
flatfield=flat.npy: the flatfield correction to be applied to the detector data. The array must
have the same shape as the frames, which will be multiplied by this
correction.
Acceptable formats:
- flat.npy, flat.npz (the first data array will be used)
- flat.edf or flat.edf.gz (a single 2D array is expected)
- "flat.h5:/entry_1/path/to/flat" hdf5 format with the full path to the
2D array. 'hdf5' is also accepted as extension.
- flat.mat: from a matlab file. The first array found is loaded
[default: no flatfield correction is applied]
dark=dark.npy: the dark correction (incoherent background). The array must have
the same shape as the frames. This will be taken into account during
the optimisation, and not subtracted from the observed data, unless
substract_dark is used.
Acceptable formats:
- dark.npy, dark.npz (the first data array will be used)
- dark.edf or dark.edf.gz (a single 2D array is expected)
- "dark.h5:/entry_1/path/to/dark" hdf5 format with the full path to the
2D array. 'hdf5' is also accepted as extension.
- dark.mat: from a matlab file. The first array found is loaded
[default: no dark correction is applied]
dark_subtract or dark_subtract=0.9: use this to subtract the dark from the observed
intensity. This is normally discouraged, as it will mess up the Poisson statistics
of the observed data, but it can be useful in the case of very high background.
If given as a simple keyword, the dark is subtracted. If given with a float,
the dark will be multiplied by this factor before subtraction.
[default: False, dark is not subtracted]
orientation_round_robin: will test all possible combinations of xy and detector_orientation
to find the correct detector configuration.
mpi=multiscan or split: when launching the script using mpiexec, this tells the script to
either distribute the list of scans to different processes (multiscan, the default),
or split a large scan in different parts, which are automatically aligned and
stitched. Examples:
mpiexec -n 2 pynx-ptycho-cxi scan=11,12,13,14 data=scan%02d.cxi mpi=multiscan
probe=focus,120e-6x120e-6,0.1 defocus=100e-6 verbose=50
algorithm=analysis,ML**100,DM**200,nbprobe=2,probe=1
mpiexec -n 4 pynx-ptycho-cxi mpi=split data=scan151.cxi verbose=50
probe=focus,120e-6x120e-6,0.1 defocus=100e-6
algorithm=analysis,ML**100,DM**200,nbprobe=2,probe=1
mpi_split_nb_overlap=2: depth of shared neighbours between overlapping regions when using
mpi=split [default:1] (experimental, may change)
mpi_split_nb_neighbour=20: target number of shared neighbours for each set for overlap
[default:20] (experimental, may change)
multiscan_reuse_ptycho: if used as a keyword, successive scans will re-start from the previous
ptycho object and probe, and skip initialisation steps. Useful for ptycho-tomo.
This can also be used to supply a shorter algorithm chain which will be used after the first
scan, e.g. with:
algorithm=ML**100,AP**100,DM**1000,nbprobe=2,probe=1
multiscan_reuse_ptycho=ML**100,AP**100,probe=1,AP**50,probe=0
In the above example, the probe would be re-used so there is no need to use 'nbprobe=2',
and the first step (AP**50) would only optimise the object.
Note that if you want to re-process the first scan with this short algorithm chain,
it is possible to list the first scan twice, e.g.: scan=12,12,13,14,15
[default: False, every scan starts from a new object and probe]
use_direct_beam: if used, and a reference frame with the direct beam is given, it
will also be used for the optimisation, giving an absolute reference for the probe.
[default: False - this may change in the future as this is in testing]
==================================================================================================
End of common help text
Instructions for the specific script are given below
==================================================================================================
Specific instructions¶
Instructions for beamline-dedicated scripts can be fully obtained by executing the script without any parameter.
pynx-ptycho-cxi:¶
Script to perform a ptychography analysis on data recorded in CXI format (http://cxidb.org/cxi.html)
Examples:
pynx-ptycho-cxi data=data.cxi probe=focus,60e-6x200e-6,0.09
algorithm=analysis,ML**100,DM**200,nbprobe=3,probe=1 verbose=10 save=all saveplot liveplot
command-line arguments:
data=/some/dir/to/data.cxi or cxifile=some/dir/to/data.cxi: path to CXI data [mandatory]
scan=56: scan number [optional: this is used to name the output directory, otherwise 0].
Several scans can also processed by giving a generic cxi name and scan numbers,
e.g.: data=data%03d.cx scan=13,45,78
gpu=Titan: GPU name for OpenCL calculation
[default = will be auto-selected from available GPUs]
xyrange=-2e-6,2e-6,-5e-6,-2e-6: range where the data points will be taken into
account (xmin, xmax, ymin, ymax). All scan positions outside this range are ignored.
This must be given in original coordinates, in meters.
[default=No spatial restrictions]
pynx-ptycho-id01:¶
Script to perform a ptychography analysis on data from ID01@ESRF
Example:
pynx-ptycho-id01 specfile=siemens.spec scan=57 detectordistance=1.3 ptychomotors=pix,piz,-x,y
probe=60e-6x200e-6,0.09 algorithm=analysis,ML**100,DM**200,nbprobe=3,probe=1
loadmask=maxipix verbose=10 save=all saveplot liveplot
pynx-ptycho-id01 h5file=/data/visitor/mi1421/id01/sample/sample_0001/sample_0001.h5
scan=2 ptychomotors=pix,piz,x,-y probe=400e-6x400e-6,1.57 detector=eiger2M
detectordistance=5 liveplot roi=0,380,1900,2160,0,400
algorithm=analysis,ML**100,position=1,ML**200,DM**300,nbprobe=3,probe=1
nbprobe=3
command-line arguments:
data=/some/dir/to/bliss.h5: path to bliss file [mandatory unless specfile is used]
detector=mpx1x4: detector used mpx1x4/eiger2M (only for BLISS data)
[optional, will be auto-detected if only one detector data is present]
or specfile=/some/dir/to/specfile.spec: path to specfile [mandatory unless data is used]
scan=56: scan number in specfile [mandatory].
Alternatively a list or range of scans can be given:
scan=12,23,45 or scan="range(12,25)" (note the quotes)
imgcounter=mpx4inr: spec counter name for image number
[default=auto, will use mpx4inr or ei2minr]
imgname=/dir/to/images/prefix%05d.edf.gz: images location with mask
[default: will be extracted from ULIMA_mpx4 or ULIMA_eiger2M the spec scan header]
nrj=8: energy in keV [default: will be extracted from UMONO spec scan header, mononrj=x.xxkeV]
detectordistance=1.3: detector distance in meters
[mandatory, unless given in spec header UDETCALIB]
pixelsize=55e-6: pixel size on detector in meters [default:55e-6]
ptychomotors=pix,piz,-x,y: name of the two motors used for ptychography, optionally followed
by a mathematical expression to be used to calculate the actual
motor positions (axis convention, angle..). Values will be extracted
from the spec files, and are assumed to be in microns.
Example 1: ptychomotors=pix,piz
Example 2: ptychomotors=pix,piz,-x,y
Note that if the 'xy=-y,x' command-line argument is used,
it is applied after this, using 'ptychomotors=pix,piz,-x,y'
is equivalent to 'ptychomotors=pix,piz xy=-x,y'
[Mandatory]
xyrange=-2e-6,2e-6,-5e-6,-2e-6: range where the data points will be taken into
account (xmin, xmax, ymin, ymax). All scan positions outside this range are ignored.
This must be given in original coordinates, in meters.
[default=No spatial restrictions]
monitor=opt2: spec name for the monitor counter. The frames will be normalized by the ratio
of the counter value divided by the median value of the counter over the entire
scan (so as to remain close to Poisson statistics). A monitor intensity lower
than 10% of the median value will be interpreted as an image taken without beam
and will be skipped.
[default = None]
kmapfile=detector/kmap/kmap_00000.edf.gz: if images are saved in a multiframe data file
This superseeds imgname=...
livescan: if set, this keyword will trigger the analysis of all scans of a given type
(by default 'spiralscan') in the supplied spec file. If scan=NN is also given,
the analysis will start after scan #NN.
Once all scans are processed, the script will wait for new scans to arrive.
pynx-ptycho-id13:¶
Script to perform a ptychography analysis on data from id13@ESRF.
This can handle by default 2020-type data (all scans data in hdf5 and eiger images
in a per-scan hdf5 file).
Example:
pynx-ptycho-id13 data=scans.h5 scan=41 detectordistance=1.3
probe=60e-6x200e-6,0.09 verbose=10 save=all saveplot liveplot
algorithm=analysis,ML**100,DM**200,nbprobe=3,probe=1
Command-line arguments (beamline-specific):
data=/some/dir/to/data.h5: path to hdf5 scan data [mandatory, unless specfile is given]
specfile=/some/dir/to/specfile.spec: path to specfile [obsolete format]
data_detector=other/path/to/eiger/%04d/scan_%04d.h5: filename for the hdf5 data
If there are several %d fields in the name, every one but the last
will be replaced by the scan number.
scan=56: scan number in data or specfile [mandatory].
Alternatively a list or range of scans can be given:
scan=12,23,45 or scan="range(12,25)" (note the quotes)
h5data=entry/data/data_%6d: generic hdf5 path to the stack of 2d images inside hdf5 file
[default=entry_0000/measurement/data]
nrj=8: energy in keV [mandatory, but should be in hdf5 file]
pixelsize=75e-6: pixel size on detector in meters
[default: 75e-6]
ptychomotors=nnp2,nnp3,-x,y: name of the two motors used for ptychography, optionally followed
by a mathematical expression to be used to calculate the actual
motor positions (axis convention, angle..). Values will be
extracted from the edf files, and are assumed to be in microns.
Example 1: ptychomotors=nnp2,nnp3
Example 2: ptychomotors=nnp2,nnp3,-x,y
Note that if the 'xy=-y,x' command-line argument is used, it is
applied after this, using 'ptychomotors=nnp2,nnp3,-x,y' is
equivalent to 'ptychomotors=nnp2,nnp3 xy=-x,y'
[default:nnp2_position,nnp3_position xy=-x,y]
monitor=opt2: spec name for the monitor counter. The frames will be normalised by the ratio of
the counter value divided by the median value of the counter over the entire scan
(so as to remain close to Poisson statistics). A monitor intensity lower than 10%
of the median value will be interpreted as an image taken without beam and will be
skipped.
[default = None]
kmapfile=detector/kmap/kmap_00000.edf.gz: if images are saved in a multiframe data file.
This superseeds imgname=...
raster_scan=40x40: this will assume a raster scan for which regular coordinates should
be used. With the given number of points along each axis, the end and beginning
positions will be averaged and the actual positions will be put on a regular grid.
NB: raster scans should not be used, so this is only provided as a workaround
until correct motor positions are stored in the data file.
pynx-ptycho-id16a:¶
Script to perform a ptychography analysis on data from id16(a)@ESRF
Example:
pynx-ptycho-id16a h5meta=data.h5 probe=60e-6x60e-6,0.09
algorithm=analysis,ML**100,DM**200,nbprobe=3,probe=1
Command-line arguments (beamline-specific):
h5meta=data.h5: hdf5 filename with the scan metadata. The scan number, energy,
detector distance will be extracted
[mandatory - if a single *.h5 file is in the working directory,
it will be used by default]
pixelsize=55e-6: pixel size on detector in meters
[default: 55e-6 or will be read frommetadata or hdf5 data]
imgname=/dir/to/images/prefix%05d.edf: images location with mask. Images will be read starting
from 0 or 1, until no more frames are found, or maxframe
has been reached.
To process several scans, several % fields can be added, the last
will be interpreted as the image number and the others replaced by the
scan number.
Examples:
/dir/to/scan_%04d/prefix_scan%04d_img%05d.edf
/dir/to/scan_%04d/prefix__img%05d.edf
/dir/to/images/prefix_img%05d.edf
[mandatory if h5data is not supplied]
h5data=/path/to/hdf5/data/file.nxs: path to nexus data file (lambda detector).
If one or several % field are included in the name, they will be replaced by
the scan number.
Examples:
h5data=/path/to/hdf5/data/scan%d/scan%d.nxs
h5data=/path/to/hdf5/data/scan%d.nxs
h5data=/path/to/hdf5/data/data.nxs
[mandatory unless imgname is given, will default
to the only *.nxs file in directory]
ptychomotors=spy,spz,-x,y: name of the two motors used for ptychography, or the motor
positions file, optionally followed by a mathematical expression to
be used to calculate the actual motor positions (axis convention, angle..).
Values are either:
- extracted from the edf files, and are assumed to be in mm.
- or extracted from the 'mot_pos.txt' file, and assumed to
be in microns..
Example 1: ptychomotors=spy,spz
Example 2: ptychomotors=spy,spz,-x,y
Example 3: ptychomotors=mot_pos.txt
Note that if the 'xy=-y,x' command-line argument is used, it is
applied after this, using 'ptychomotors=spy,spz,-x,y'
is equivalent to 'ptychomotors=spy,spz xy=-x,y'
[Mandatory]
detectordistance=1.3: detector distance in meters [default: will be read from hdf5 metadata]
gpu=Titan: GPU name for OpenCL calculation [Mandatory]
CDI¶
These are instructions to run the command-line scripts: pynx-cdi-id01 and pynx-cdi-id10. They can also be used for generic data not from these beamlines.
This help text can be simply obtained by typing the script without any parameter.
Generic instructions¶
Here are generic instructions applying to all the scripts:
generic (not beamline-specific) command-line/file parameters arguments: (all case-insensitive)
data=data.npy: name of the data file including the 3D observed intensity.
recognized formats include .npy, .npz (if several arrays are included iobs,
should be named 'data' or 'iobs'), .tif or .tiff
(assumes a multiframe tiff image), or .cxi (hdf5).
An hdf5 file can be supplied with a path,
e.g. data=path/to/data.h5:entry/path/data
Multiple files can be processed by combining with scan, e.g.:
* data=my_data%04d.cxi scan=23,24,25
* data=my_data%sd.cxi scan=room_temperature,
[mandatory unless another beamline-specific method to import data is used]
detector_distance=0.7: detector distance in meters
pixel_size_data=55e-6: deprecated, use pixel_size_detector instead
pixel_size_detector=55e-6: pixel size of the supplied data (detector pixel size)
wavelength=1.5e-10: wavelength in meters
verbose=20: the run will print and optionally plot every 'verbose' cycles
live_plot: if used as keyword (or live_plot=True in a parameters file), a live plot
will be shown every 'verbose' cycle. If an integer number N is given,
display every N cycle.
plot_axis=1: for 3D data, this option allows to choose the direction of the axis
of the 2D cut used for live_plot [default:0]
save_plot: if used as keyword (or save_plot=True in a parameters file), a
final plot will be saved in a png file with 3 cuts of the object, some statistics
and the optimisation parameters.
The default is to show the object cuts as RGBA, or the absolute if positivity
is used. The type of plot can be changed, e.g.:
* save_plot=rgba : the default
* save_plot=abs : absolute value (default with positivity)
* save_plot=gray : specify a matplotlib colormat name
gpu=Titan: name of the gpu to use [optional, by default the fastest available will be used]
auto_center_resize: if used (command-line keyword) or =True, the input data will be centered
and cropped so that the size of the array is compatible with the (GPU)
FFT library used. If 'roi' is used, centering is based on ROI.
[default=False]
roi=0,120,0,235,0,270: set the region-of-interest to be used, with min,max given along each
dimension in python fashion (min included, max excluded), for the 2 or 3
axis. ROI coordinates should be indicated before any rebin is done.
Note that if 'auto_center_resize' is used, the ROI may still be shrunk
to obtain an array size compatible with the FFT library used. Similarly
it will be shrunk if 'max_size' is used but ROI size is larger.
Other example: roi=0,-1,300-356,300+256,500-256,500+256
[default=None]
nb_run=1: number of times to run the optimization [default=1]
nb_run_keep: number of best run results to keep, according to likelihood statistics. This is only useful
associated with nb_run [default: keep all run results]
nb_run_keep_max_obj2_out: when performing multiple runs with nb_run_keep, if the fraction
of the object square modulus outside the object support is larger than this value,
the solution will be rejected regardless of the free log-likelihood.
[default:0.1]
data2cxi: if used as keyword (or data2cxi=True in a parameters file), convert the original
data to CXI(HDF5) format. Will be saved to file 'data.cxi', or if a data file
has been supplied (e.g. data57.npz), to the same file with extension .cxi.
output_format='cxi': choose the output format for the final object and support.
Other possible choice: 'npz', 'none'
[Default='cxi']
note='This dataset was measure... Citation: Journal of coherent imaging (2018), 729...':
Optional text note which will be saved as a note in the output CXI file
(and also for data2cxi).
instrument='ESRF-idxx': the name of the beamline/instrument used for data collection
[default: depends on the script actually called]
sample_name='GaN nanowire': optional name for the sample
flatfield=flat.npz: filename with a flatfield array by which the observed intensity
will be multiplied. In order to preserve Poisson statistics, the flat correction
should be close to 1.
Accepted file formats: .npy, .npz, .edf, .mat, .tif, .h5, .cxi.
The first available array will be used if multiple are present.
For an hdf5 file (h5 or cxi), the path can be supplied e.g. using
data=path/to/flatfield.h5:entry/path/flat - if the hdf5 path is not given,
the first array with a correct shape and with 'flat' in the path is used.
If the flatfield is 2D and the observed intensity 3D, the flatfield is repeated
along the depth (first/slowest axis).
Note that if no flatfield is given and mask=maxipix1 or maxipix6, a correction is
automatically to the gap pixels (see mask documentation below).
[default=None, no flatfield correction]
mask=zero: mask for the diffraction data. If 'zero', all pixels with iobs <= 0 will be masked.
If 'negative', all pixels with iobs < 0 will be masked.
If 'maxipix', the maxipix gaps will be masked.
If 'maxipix1', the maxipix gaps will be masked, except for the large pixel one ach side of the gap,
for which the intensity will be divided by 3.
If 'maxipix6', the maxipix gaps will be linearly interpolated between the gap large pixels.
NaN-valued pixels in the observed intensity are always masked.
If a filename is given (accepted formats: .npy, .npz, .edf, .mat, .tif, .h5, .cxi):
(the first available array will be used if multiple are present) file. For an hdf5 file (.h5 or .cxi),
the path can be supplied e.g. using data=path/to/mask.h5:entry/path/mask - if the hdf5 path
is not given, the first array with a correct shape and with 'mask' in the path is used.
Pixels = 0 are valid, > 0 are masked. If the mask is 2D
and the data 3D, the mask is repeated for all frames along the first dimension (depth).
Several masks can be combined, separated by a comma, e.g. mask=maxipix,dead.npz
[default=None, no mask]
free_pixel_mask=result.cxi: pixel mask for free log-likelihood calculation. By default the free pixel mask is
randomly initialised, but this can be used to load a mask from a file for
consistency between runs. It can be loaded from a .npy, .edf, .tif, .npz or
.mat file - if .npz or .mat are used, the first array matching the iobs shape is used.
A .cxi filename can also be used as input, in which case it is assumed that this
is the result of a previous optimisation, and that the mask can be loaded from
'/entry_last/image_1/process_1/configuration/free_pixel_mask'
iobs_saturation=1e6: saturation value for the observed intensity. Any pixel above this intensity will be masked
[default: no saturation value]
zero_mask: by default masked pixels are free and keep the calculated intensities during HIO, RAAR, ER and CF cycles.
Setting this flag will force all masked pixels to zero intensity. This can be more stable with a large
number of masked pixels and low intensity diffraction data.
If a value is supplied the following options can be used:
zero_mask=0: masked pixels are free and keep the calculated complex amplitudes
zero_mask=1: masked pixels are set to zero
zero_mask=auto: this is only meaningful when using a 'standard' algorithm below. The masked pixels will
be set to zero during the first 60% of the HIO/RAAR cycles, and will be free during the
last 40% and ER, ML ones.
mask_interp=16,2: interpolate masked pixels from surrounding pixels, using an inverse distance
weighting. The first number N indicates that the pixels used for interpolation range
from i-N to i+N for pixel i around all dimensions. The second number n that the weight
is equal to 1/d**n for pixels with at a distance n.
The interpolated values iobs_m are stored in memory as -1e19*(iobs_m+1) so that the
algorithm knows these are not trul observations, and are applied with a large
confidence interval.
[default:None, no interpolation is done for masked pixels]
confidence_interval_factor_mask=0.5,1.2:
When masked pixels are interpolated using mask_interp, the calculated values iobs_m are
not observed and the amplitude projection is done for those with a confidence interval,
equal to: iobs_m*confidence_interval_factor_mask
Two values (min/max) must be given, normally around 1 [default:0.5,1.2]
object=obj.npy: starting object. Import object from .npy, .npz, .mat (the first available array
will be used if multiple are present), CXI or hdf5 modes file.
It is also possible to supply the random range for both amplitude and phase, using:
* object=support,0.9,1,0.5: this will use random values over the initial support,
with random amplitudes between 0.9 and 1 and phases with a 0.5 radians range
* object=obj.npy,0.9,1,0.5: same but the random values will be multiplied by
the loaded object.
[default=None, object will be defined as random values inside the support area]
support=sup.cxi: starting support. Different options are available:
* support=sup.cxi: Import support from .npy, .npz, .edf, .mat (the first
available array will be used if multiple are present) or CXI/hdf5 file. Pixels > 0
are in the support, 0 outside. If the support shape is different than the Iobs
array, it will be cropped or padded accordingly.
If a CXI filename is given, the support will be searched in entry_last/image_1/mask
or entry_1/image_1/mask, e.g. to load support from a previous result file.
For CXI and h5 files, the hdf5 path can also be given:
support=path/to/data.h5:entry_1/image_1/data
* support=auto: support will be estimated using the intensity
* support=circle: or 'square', the support will be initialised to a
circle (sphere in 3d), or a square (cube).
* support=object: the support will be initialised from the object
using the given support threshold and smoothing parameters - this requires
that the object itself is loaded from a file. The applied threshold is always
relative to the max in this case.
* support=object,0.1,1.0: same as above, but 0.1 will be used as the relative
threshold and 1.0 the smoothing width just for this initialisation.
All those are ignored if support_formula is given.
[default='auto', support will be defined by auto-correlation]
support_size=50: size (radius or half-size) for the initial support, to be used in
combination with 'support_type'. The size is given in pixel units.
Alternatively one value can be given for each dimension, i.e.
support_size=20,40 for 2D data, and support_size=20,40,60 for 3D data.
This will result in an initial support which is a rectangle/parallelepiped
or ellipsis/ellipsoid. Ignored if support_formula is given.
[if not given, this will trigger the use of auto-correlation
to estimate the initial support]
support_formula: formula to compute the support. This should be an equation using ix,iy,iz and ir pixel coordinates
(all centered on the array) which can be evaluated to produce an initial support (1/True inside,
0/False outside). Mathematical functions should use the np. prefix (np.sqrt, ..). Examples:
support_formula="ir<100": sphere or circle of radius 100 pixels
support_formula="(np.sqrt(ix**2+iy**2)<50)*(np.abs(iz)<100)": cylinder of radius 50 and height 200
support_autocorrelation_threshold=0.1: if no support is given, it will be estimated
from the intensity auto-correlation, with this relative threshold.
A range can also be given, e.g. support_autocorrelation_threshold=0.09,0.11
and the actual threshold will be randomly chosen between the min and max.
[default value: 0.09,0.11]
support_threshold=0.25: threshold for the support update. Alternatively two values can be given, and the threshold
will be randomly chosen in the interval given by two values: support_threshold=0.20,0.28.
This is mostly useful in combination with nb_run.
[default=0.25]
support_threshold_method=max: method used to determine the absolute threshold for the
support update. Either:'max' or 'average' or 'rms' (the default) values,
taken over the support area/volume, after smoothing.
Note that 'rms' and 'average' use the modulus or root-mean-square value normalised
over the support area, so when the support shrinks, the threshold tends to increase.
In contrast, the 'max' value tends to diminish as the optimisation
progresses. rms is varying more slowly than average and is thus more stable.
In practice, using rms or average with a too low threshold can lead to the divergence
of the support (too large), if the initial support
support_only_shrink: if set or support_only_shrink=True, the support will only shrink
(default: the support can grow again)
support_smooth_width_begin=2
support_smooth_width_end=0.25: during support update, the object amplitude is convoluted by a
gaussian with a size
(sigma) exponentially decreasing from support_smooth_width_begin
to support_smooth_width_end from the first to the last RAAR or
HIO cycle.
[default values: 2 and 0.5]
support_smooth_width_relax_n: the number of cycles over which the support smooth width will
exponentially decrease from support_smooth_width_begin to
support_smooth_width_end, and then stay constant.
This is ignored if nb_hio, nb_raar, nb_er are used,
and the number of cycles used
is the total number of HIO+RAAR cycles [default:500]
support_post_expand=1: after the support has been updated using a threshold, it can be shrunk
or expanded by a few pixels, either one or multiple times, e.g. in order
to 'clean' the support:
- support_post_expand=1 will expand the support by 1 pixel
- support_post_expand=-1 will shrink the support by 1 pixel
- support_post_expand=-1,1 will shrink and then expand the support
by 1 pixel
- support_post_expand=-2,3 will shrink and then expand the support
by 2 and 3 pixels
- support_post_expand=2,-4,2 will expand/shrink/expand the support
by 2, 4 and 2 pixels
- etc..
[default=None, no shrinking or expansion]
support_update_border_n: if > 0, the only pixels affected by the support updated lie within +/- N pixels around the
outer border of the support.
support_update_period=50: during RAAR/HIO, update support every N cycles.
If 0, support is never updated.
support_fraction_min=0.001: if the fraction of points inside the support falls below
this value, the run is aborted, and a few tries will be made by dividing the
support_threshold by support_threshold_auto_tune_factor.
[default:0.0001]
support_fraction_max=0.5: if the fraction of points inside the support becomes larger than
this value, the run is aborted, and a few tries will be made by multiplying the
support_threshold by support_threshold_auto_tune_factor.
[default:0.7]
support_threshold_auto_tune_factor: the factor by which the support threshold will be
changed if the support diverges
[default: 1.1]
positivity: if set or positivity=True, the algorithms will be biased towards a real, positive
object. Object is still complex-valued, but random start will begin with real
values. [default=False]
beta=0.9: beta value for the HIO/RAAR algorithm [default=0.9]
crop_output=0: if >0 (default:4), the output data will be cropped around the final
support plus 'crop_output' pixels. If 0, no cropping is performed.
rebin=2: the experimental data can be rebinned (i.e. a group of n x n (x n) pixels is
replaced by a single one whose intensity is equal to the sum of all the pixels).
Both iobs and mask (if any) will be rebinned, but the support (if any) should
correspond to the new size. The supplied pixel_size_detector should correspond
to the original size. The rebin factor can also be supplied as one value per
dimension, e.g. "rebin=4,1,2".
Also, instead of summing pixels with the given rebin size, it is possible
to select a single sub-pixel by skipping instead of binning:
e.g. using "rebin=4,1,2,0,0,1", the extracted pixel will use
array slicing data[0::4,0::1,1::2].
[default: no rebin]
max_size=256: maximum size for the array used for analysis, along all dimensions. The data
will be cropped to this value after rebinning and centering. [default: no maximum size]
user_config*=*: this can be used to store a custom configuration parameter which will be ignored by the
algorithm, but will be stored among configuration parameters in the CXI file (data and output).
e.g.: user_config_temperature=268K user_config_comment="Vibrations during measurement" etc...
############# ALGORITHMS: standard version, using RAAR, then HIO, then ER and ML
nb_raar=600: number of relaxed averaged alternating reflections cycles, which the
algorithm will use first. During RAAR and HIO, the support is updated regularly
nb_hio=0: number of hybrid input/output cycles, which the algorithm will use after RAAR.
During RAAR and HIO, the support is updated regularly
nb_er=200: number of error reduction cycles, performed after HIO, without support update
nb_ml=20: number of maximum-likelihood conjugate gradient to perform after ER
detwin: if set (command-line) or if detwin=True (parameters file), 10 cycles will be performed
at 25% of the total number of RAAR or HIO cycles, with a support cut in half to bias
towards one twin image
psf=pseudo-voigt,1,0.05,10: this will trigger the activation of a point-spread function
kernel to model partial coherence (and detector psf), after 66% of the total number
of HIO and RAAR have been reached.
The following options are possible for the psf:
psf=pseudo-voigt,1,0.05,10: use a pseudo-Voigt profile with FWHM 1 pixel and eta=0.05,
i.e. 5% Lorentzian and 95% Gaussian, then update every 10 cycles (using 0 for the last
number prevents the PSF update)
psf=gaussian,1.5,10: start with a Gaussian of FWHM 1.5 pixel, and update it every 10 cycles
psf=lorentzian,0.6,10: start with a Lorentzian of FWHM 0.6 pixel, and update it every 10 cycles
psf=path/to/file.npz: load the PSF array from an npz file. The array loaded will either
be named 'psf' or 'PSF', or the first found array will be loaded. The PSF must be centred
in the array, and will be resized (so it can be cropped). The PSF will be updated
every 5 cycles
psf=/path/to/file.cxi: load the PSF from a previous result from a CXI file.The PSF will be updated
every 5 cycles
psf=/path/to/file.cxi,10: same as before, update the PSF every 10 cycles
psf=/path/to/file.cxi,0: same as before, do not update the PSF
Recommended values:
- for highly coherent datasets: no PSF
- with some partial coherence: psf=pseudo-voigt,1,0.05,20
You can try different widths to start (from 0.25 to 2), and change the eta
mixing parameter.
psf_filter=hann: the PSF update can also be filtered to avoid divergence. Possible values
include "hann", "tukey" or "none" (the default, equivalent to False)
[EXPERIMENTAL, don't use]
############# ALGORITHMS: customized version
algorithm="ER**50,(Sup*ER**5*HIO**50)**10": give a specific sequence of algorithms and/or
parameters to be
used for the optimisation (note: this string is case-insensitive).
Important:
1) when supplied from the command line, there should be NO SPACE in the expression !
And if there are parenthesis in the expression, quotes are required around the
algorithm string
2) the string and operators are applied from right to left
Valid changes of individual parameters include (see detailed description above):
positivity = 0 or 1
support_only_shrink = 0 or 1
beta = 0.7
live_plot = 0 (no display) or an integer number N to trigger plotting every N cycle
support_update_period = 0 (no update) or a positive integer number
support_smooth_width_begin = 2.0
support_smooth_width_end = 0.5
support_smooth_width_relax_n = 500
support_threshold = 0.25
support_threshold_mult = 0.7 (multiply the threshold by 0.7)
support_threshold_method=max or average or rms
support_post_expand=-1#2 (in this case the commas are replaced by # for parsing)
zero_mask = 0 or 1
psf = 5: will update the PSF every 5 cycles (and init PSF if necessary with the default
pseudo-Voigt of FWHM 1 pixels and eta=0.1)
psf_init=gaussian@1.5: initialise the PSF with a Gaussian of FWHM 1.5 pixels
psf_init=lorentzian@0.5: initialise the PSF with a Lorentzian of FWHM 0.5 pixels
psf_init=pseudo-voigt@1@0.1: initialise the PSF with a pseudo-Voigt of FWHM 1 pixels
and eta=0.1
Note that using psf_init automatically triggers updating the PSF every 5 cycles,
unless it has already been set using 'psf=...'
verbose=20
fig_num=1: change the figure number for plotting
Valid basic operators include:
ER: Error Reduction
HIO: Hybrid Input/Output
RAAR: Relaxed Averaged Alternating Reflections
DetwinHIO: HIO with a half-support (along first dimension)
DetwinHIO1: HIO with a half-support (along second dimension)
DetwinHIO2: HIO with a half-support (along third dimension)
DetwinRAAR: RAAR with a half-support (along first dimension)
DetwinRAAR1: RAAR with a half-support (along second dimension)
DetwinRAAR2: RAAR with a half-support (along third dimension)
CF: Charge Flipping
ML: Maximum Likelihood conjugate gradient (incompatible with partial coherence PSF)
FAP: FourierApplyAmplitude- Fourier to detector space, apply observed amplitudes,
and back to object space.
Sup or SupportUpdate: update the support according to the support_* parameters
ShowCDI: display of the object and calculated/observed intensity. This can be used
to trigger this plot at specific steps, instead of regularly using
live_plot=N. This is thus best used using live_plot=0
Examples of algorithm strings, where steps are separated with commas (and NO SPACE!),
and are applied from right to left. Operations in a given step will be applied
mathematically, also from right to left, and **N means repeating N tymes (N cycles)
the operation on the left of the exponent:
algorithm=HIO : single HIO cycle
algorithm=ER**100 : 100 cycles of ER
algorithm=ER**50*HIO**100 : 100 cycles of HIO, followed by 50 cycles of ER
algorithm=ER**50,HIO**100 : 100 cycles of HIO, followed by 50 cycles of ER
The result is the same as the previous example, the difference between using *
and "," when switching from HIO to ER is mostly cosmetic as the process will
separate the two algorithmic steps explicitly when using a ",", which
can be slightly slower.
Moreover, when using "save=all", the different steps will be saved as
different entries in the CXI file.
algorithm="ER**50,(Sup*ER**5*HIO**50)**10" :
10 times [50 HIO + 5 ER + Support update], followed by 50 ER
algorithm="ER**50,verbose=1,(Sup*ER**5*HIO**50)**10,verbose=100,HIO**100":
change the periodicity of verbose output
algorithm="ER**50,(Sup*ER**5*HIO**50)**10,support_post_expand=1,
(Sup*ER**5*HIO**50)**10,support_post_expand=-1#2,HIO**100"
same but change the post-expand (wrap) method
algorithm="ER**50,(Sup*ER**5*HIO**50)**5,psf=5,(Sup*ER**5*HIO**50)**10,HIO**100"
activate partial correlation after a first series of algorithms
algorithm="ER**50,(Sup*HIO**50)**4,psf=5,(Sup*HIO**50)**8"
typical algorithm steps with partial coherence
algorithm="ER**50,(Sup*HIO**50)**4,(Sup*HIO**50)**4,positivity=0,
(Sup*HIO**50)**8,positivity=1"
same as previous but starting with positivity constraint, removed at the end.
[default: use nb_raar, nb_hio, nb_er and nb_ml to perform the sequence of algorithms]
save=all: either 'final' or 'all' this keyword will activate saving after each optimisation
step (comma-separated) of the algorithm in any given run. Note that the name of
the save file including the LLK ank LLK_free values will be decided by the first
step and not the final one.
[default=final]
############# MPI: distribute computing
mpi=scan or run: when launching the script using mpiexec, this tells the script to
either distribute the list of scans to different processes (mpi=scan, the default),
or (mpi=run) split the runs to the different processes. If nb_run_keep is used,
the results are merged before selecting the best results.
==================================================================================================
End of common help text
Instructions for the specific script are given below
==================================================================================================
Specific instructions¶
Instructions for beamline-dedicated scripts can be fully obtained by executing the script without any parameter.
pynx-cdi-id01:¶
Script to perform a CDI reconstruction of data from ID01@ESRF.
command-line/file parameters arguments: (all keywords are case-insensitive):
data=/some/dir/to/bliss.h5: path to bliss NeXus data [mandatory, unless specfile= is used instead]
Note: data= can also be used to load generic data (hdf5, cxi, tiff, edf...) as in
the general description.
detector=mpx1x4: detector used mpx1x4/eiger2M (only for BLISS data)
[optional, will be auto-detected if only one detector data is present]
specfile=/some/dir/to/specfile.spec: path to specfile [mandatory, unless data= is used instead]
scan=56: scan number in specfile [mandatory when using SPEC or BLISS data].
Alternatively a list or range of scans can be given:
scan=12,23,45 or scan="range(12,25)" (note the quotes)
imgcounter=mpx4inr: spec counter name for image number (only for SPEC data)
[default='auto', will use either 'mpx4inr' or 'ei2mint']
imgname=/dir/to/images/prefix%05d.edf.gz: images location with prefix (for SPEC data)
[default: will be extracted from the ULIMA_mpx4 entry in the spec scan header]
Specific defaults for this script:
auto_center_resize = True
detwin = True
nb_raar = 600
nb_hio = 0
nb_er = 200
nb_ml = 0
support_size = None
zero_mask = auto
pynx-cdi-id10:¶
Script to perform a CDI reconstruction of data from id10@ESRF.
command-line/file parameters arguments: (all keywords are case-insensitive):
Specific defaults for this script:
auto_center_resize=True
detwin = False
mask = zero # use 'mask=no' from the command-line to avoid using a mask
nb_raar = 600
nb_hio = 0
nb_er = 200
nb_ml = 0
support_size = 50
support_type = circle
zero_mask = 0
positivity = True
CDI-regrid¶
These are instructions to run the: pynx-cdi-regrid command-line script to prepare a 3D cdi CXI file from multiple projections.
Rebuild the 3D reciprocal space by projecting a set of 2d speckle SAXS pattern taken at various rotation angles into a 3D regular volume
usage: pynx-cdi-regrid.py [-h] [-V] [-v] [--debug] [-o OUTPUT] [-s SHAPE] [--scale SCALE] [-m MASK] [--dry-run] [--profile] [--maxi MAXI] [-d DISTANCE] [-b BEAM BEAM] [-p PIXELSIZE] [--rot ROT] [--scan SCAN] [--scan-len SCAN_LEN] [--oversampling-img OVERSAMPLING_IMG]
[--oversampling-rot OVERSAMPLING_ROT] [--device DEVICE DEVICE]
[IMAGE ...]
Positional Arguments¶
- IMAGE
file with input images in Bliss format HDF5
Named Arguments¶
- -V, --version
output version and exit
- -v, --verbose
show information for each conversions
Default: False
- --debug
show debug information
Default: False
main arguments¶
- -o, --output
output filename in CXI format
Default: “reciprocal_volume.cxi”
- -s, --shape
Size of the reciprocal volume, by default 512³
Default: 1024
- --scale
Scale (down) the voxel coordinates. For example a factor 2 is similar to a 2x2x2 binning of the volume
Default: 1.0
- -m, --mask
Path for the mask file containing both invalid pixels and beam-stop shadow
optional behaviour arguments¶
- --dry-run
do everything except modifying the file system
Default: False
- --profile
Turn on the profiler and print OpenCL profiling at output
Default: False
- --maxi
Limit the processing to a given number of frames
Experimental setup options¶
- -d, --distance
Detector distance in meter
- -b, --beam
Direct beam in pixels x, y, by default, the center of the image
- -p, --pixelsize
pixel size, by default 172µm
Default: 0.000172
Scan setup¶
- --rot
Name of the rotation motor
Default: “ths”
- --scan
Name of the rotation motor
Default: “dscan sz”
- --scan-len
Pick scan which match that length (unless take all scans
Default: “1”
Oversampling options to reduces the moiré pattern¶
- --oversampling-img
How many sub-pixel there are in one pixel (squared)
Default: 7
- --oversampling-rot
How many times a frame is projected
Default: 7
OpenCL options¶
- --device
Platform and device ids
Assumption: There is enough memory to hold all frames in memory
return codes: 0 means a success. 1 means the conversion contains a failure, 2 means there was an error in the arguments