# Nabu configuration parameters This file lists all the current configuration parameters available in the [configuration file](nabu_config_file.md). ### dataset Dataset location, either a directory or a HDF5-Nexus file. ```ini location = ``` Entry in the HDF5 file, if applicable. Default is the first available entry. ```ini hdf5_entry = ``` Nexus version to use when browsing the HDF5 dataset. Default is 1.0. ```ini nexus_version = 1.0 ``` Path to a directory where XXX_flats.h5 and XXX_darks.h5 are to be found, where 'XXX' denotes the dataset basename. If these files are found, then reduced flats/darks will be loaded from them. Otherwise, reduced flats/darks will be saved to there once computed, either in the .nx directory, or in the output directory. Mind that the HDF5 entry corresponds to the one of the dataset. ```ini darks_flats_dir = ``` Binning factor in the horizontal dimension when reading the data. The final slices dimensions will be divided by this factor. ```ini binning = 1 ``` Binning factor in the vertical dimension when reading the data. This results in a lesser number of reconstructed slices. ```ini binning_z = 1 ``` Projections subsampling factor: take one projection out of 'projection_subsampling'. The format can be an integer (take 1 projection out of N), or N:M (take 1 projection out of N, start with the projection number M) For example: 2 (or 2:0) to reconstruct from even projections, 2:1 to reconstruct from odd projections. ```ini projections_subsampling = 1 ``` Projection to exclude from the reconstruction. It can be: -indices = exclude_projections_indices.txt : Path to a text file with one integer per line. Each corresponding projection INDEX will be ignored. -angles = exclude_projections_angles.txt : Path to a text file with angle in DEGREES, one per line. The corresponding angles will be ignored -angular_range = [a, b] : ignore angles belonging to angular range [a, b] in degrees, with b included. ```ini exclude_projections = ``` Which metadata to overwrite, separated by a semicolon, and with units. Example: 'energy = 19 kev; pixel_size = 1.6 um' ```ini overwrite_metadata = ``` ### preproc How to perform flat-field normalization. The parameter value can be: - 1 or True: enabled. - 0 or False: disabled - forced or force-load: perform flatfield regardless of the dataset by attempting to load darks/flats - force-compute: perform flatfield, ignore all .h5 files containing already computed darks/flats. ```ini flatfield = 1 ``` Whether to correct for flat distortion. If activated, each radio is correlated with its corresponding flat, in order to determine and correct the flat distortion. ```ini flat_distortion_correction_enabled = 0 ``` Advanced parameters for flat distortion correction ```ini flat_distortion_params = tile_size=100; interpolation_kind='linear'; padding_mode='edge'; correction_spike_threshold=None ``` Whether to normalize frames with Synchrotron Current. This can correct the effect of a beam refill not taken into account by flats. ```ini normalize_srcurrent = 1 ``` Whether to enable the CCD hotspots correction. ```ini ccd_filter_enabled = 0 ``` If ccd_filter_enabled = 1, a median filter is applied on the 3X3 neighborhood of every pixel. If a pixel value exceeds the median value more than this parameter, then the pixel value is replaced with the median value. ```ini ccd_filter_threshold = 0.04 ``` Apply coordinate transformation on the raw data, at the reading stage. Default (empty) is None. Available are: None, identity(for testing the pipeline), map_xz. This latter method requires two URLs being passed by detector_distortion_correction_options: map_x and map_z pointing to two 2D arrays containing the position where each pixel can be interpolated at in the raw data ```ini detector_distortion_correction = ``` Options for detector_distortion_correction. Example, for mapx_xz: detector_distortion_correction_options=map_x="silx:./dm.h5?path=/coords_source_x" ; map_z="silx:./dm.h5?path=/coords_source_z" Mind the semicolon separator (;). ```ini detector_distortion_correction_options = ``` Whether to enable the 'double flat-field' filetering for correcting rings artefacts. ```ini double_flatfield_enabled = 0 ``` Enable high-pass filtering on double flatfield with this value of 'sigma' ```ini dff_sigma = ``` Whether to take logarithm after flat-field and phase retrieval. ```ini take_logarithm = 1 ``` After division by the FF, and before the logarithm, the is clipped to this minimum. Enabled only if take_logarithm=1 ```ini log_min_clip = 1e-6 ``` After division by the FF, and before the logarithm, the is clipped to this maximum. Enabled only if take_logarithm=1 ```ini log_max_clip = 10.0 ``` Sinogram normalization method. Available methods are: chebyshev, subtraction, division, none. Default is none (no normalization) ```ini sino_normalization = ``` Path to the file when sino_normalization is either 'subtraction' or 'division'. To specify the path within a HDF5 file, the syntax is /path/to/file?path=/entry/data ```ini sino_normalization_file = ``` Path to the file where some operations should be stored for later use. By default it is 'xxx_nabu_processes.h5' ```ini processes_file = ``` Sinogram rings removal method. Default (empty) is None. Available are: None, munch, vo, mean-subtraction, mean-division. See also: sino_rings_options ```ini sino_rings_correction = ``` Options for sinogram rings correction methods. The parameters are separated by commas and passed as 'name=value'. Mind the semicolon separator (;). The default options are the following: -For munch: sigma=1.0 ; levels=10 ; padding=False -For vo: snr=3.0; la_size=51; sm_size=21; dim=1 -For mean-subtraction and mean-division: filter_cutoff=(0, 30) ```ini sino_rings_options = ``` Whether to rotate each projection image with a certain angle (in degree). By default (empty) no rotation is done. ```ini rotate_projections = ``` Center of rotation when 'rotate_projections' is non-empty. By default the center of rotation is the middle of each radio, i.e ((Nx-1)/2.0, (Ny-1)/2.0). ```ini rotate_projections_center = ``` Detector tilt correction. Default (empty) means no tilt correction. The following values can be provided for automatic tilt estimation, in this case, the projection images are rotated by the found tilt value: - A scalar value: tilt correction angle in degrees - 1d-correlation: auto-detect tilt with the 1D correlation method (fastest, but works best for small tilts) - fft-polar: auto-detect tilt with polar FFT method (slower, but works well on all ranges of tilts) ```ini tilt_correction = ``` Options for methods computing automatically the detector tilt. The parameters are separated by commas and passed as 'name=value', for example: low_pass=1; high_pass=20. Mind the semicolon separator (;). Use 'value' ('') for values that are strings ```ini autotilt_options = ``` ### phase Phase retrieval method. Available are: Paganin, CTF, None ```ini method = none ``` Single-distance phase retrieval related parameters delta/beta ratio for the Paganin/CTF method ```ini delta_beta = 100.0 ``` Unsharp mask strength. The unsharped image is equal to UnsharpedImage = (1 + coeff)*originalPaganinImage - coeff * ConvolvedImage. Setting this coefficient to zero means that no unsharp mask will be applied. ```ini unsharp_coeff = 0 ``` Standard deviation of the Gaussian filter when applying an unsharp mask after the phase filtering. Disabled if set to 0. ```ini unsharp_sigma = 0 ``` Which type of unsharp mask filter to use. Available values are gaussian, laplacian and imagej. Default is gaussian. ```ini unsharp_method = gaussian ``` Padding type for the filtering step in Paganin/CTF. Available are: mirror, edge, zeros ```ini padding_type = edge ``` Geometric parameters for CTF phase retrieval. Length units are in meters. ```ini ctf_geometry = z1_v=None; z1_h=None; detec_pixel_size=None; magnification=True ``` Advanced parameters for CTF phase retrieval. ```ini ctf_advanced_params = length_scale=1e-5; lim1=1e-5; lim2=0.2; normalize_by_mean=True ``` ### reconstruction Reconstruction method. Possible values: FBP, cone, none. If value is 'none', no reconstruction will be done. ```ini method = FBP ``` In the case you want to override the angles found in the files metadata. The angles are in degree. ```ini angles_file = ``` Rotation axis position. It can be a number or the name of an estimation method (empty value means the middle of the detector). The following methods are available to find automatically the Center of Rotation (CoR): - centered : a fast and simple auto-CoR method. It only works when the CoR is not far from the middle of the detector. It does not work for half-tomography. - global : a slow but robust auto-CoR. - sliding-window : semi-automatically find the CoR with a sliding window. You have to specify on which side the CoR is (left, center, right). Please see the 'cor_options' parameter. - growing-window : automatically find the CoR with a sliding-and-growing window. You can tune the option with the parameter 'cor_options'. - sino-coarse-to-fine: Estimate CoR from sinogram. Only works for 360 degrees scans. - composite-coarse-to-fine: Estimate CoR from composite multi-angle images. Only works for 360 degrees scans. - fourier-angles: Estimate CoR from sino based on an angular correlation analysis. You can tune the option with the parameter 'cor_options'. - octave-accurate: Legacy from octave accurate COR estimation algorithm. It first estimates the COR with global fourier-based correlation, then refines this estimation with local correlation based on the variance of the difference patches. You can tune the option with the parameter 'cor_options'. ```ini rotation_axis_position = sliding-window ``` Options for methods finding automatically the rotation axis position. The parameters are separated by commas and passed as 'name=value'. For example: low_pass=1; high_pass=20. Mind the semicolon separator (;) and the '' for string values that are strings. If 'side' is set, it is expected to be either: - 'from_file' (to pick the value in the NX file.) - or an relative CoR position in pixels (if so, it overrides the value in the NX file), or any of 'left', 'center', 'right', 'all', 'near'. The default value for 'side' is 'from_file'. ```ini cor_options = side='from_file' ``` Which slice to use for estimating the Center of Rotation (CoR). This parameter can be an integer or 'top', 'middle', 'bottom'. If provided, the CoR will be estimated from the correspondig sinogram, and 'cor_options' can contain the parameter 'subsampling'. ```ini cor_slice = ``` In the case where the axis position is specified for each angle ```ini axis_correction_file = ``` A file where each line describes the horizontal and vertical translations of the sample (or detector). The order is 'horizontal, vertical'. ```ini translation_movements_file = ``` Use this if you want to obtain a rotated reconstructed slice. The angle is in degrees. ```ini angle_offset = 0 ``` Filter type for FBP method. Available are: none, ramlak, shepp-logan, cosine, hamming, hann, tukey, lanczos, hilbert ```ini fbp_filter_type = ramlak ``` Cut-off frequency for Fourier filter used in FBP, in normalized units. Default is the Nyquist frequency 1.0 ```ini fbp_filter_cutoff = 1. ``` In cone-beam geometry, distance (in meters) between the X-ray source and the center of the sample. Default is infinity. ```ini source_sample_dist = ``` In cone-beam geometry, distance (in meters) between the center of the sample and the detector. Default is read from the input dataset. ```ini sample_detector_dist = ``` Padding type for FBP. Available are: zeros, edges ```ini padding_type = edges ``` Whether to enable half-acquisition. Default is auto. You can enable/disable it manually by setting 1 or 0. ```ini enable_halftomo = auto ``` Whether to set to zero voxels falling outside of the reconstruction region ```ini clip_outer_circle = 0 ``` If set to true, the reconstructed region is centered on the rotation axis, i.e the center of the image will be the rotation axis position. ```ini centered_axis = 1 ``` Parameters for sub-volume reconstruction. Indices start at 0, and upper bounds are INCLUDED! (x, y) are the dimension of a slice, and (z) is the 'vertical' axis By default, all the volume is reconstructed slice by slice, along the axis 'z'. ```ini start_x = 0 ``` ```ini end_x = -1 ``` ```ini start_y = 0 ``` ```ini end_y = -1 ``` ```ini start_z = 0 ``` ```ini end_z = -1 ``` ### output Directory where the output reconstruction is stored. ```ini location = ``` File prefix. Optional, by default it is inferred from the scanned dataset. ```ini file_prefix = ``` Output file format. Available are: hdf5, tiff, jp2, edf, vol ```ini file_format = hdf5 ``` What to do in the case where the output file exists. By default, the output data is never overwritten and the process is interrupted if the file already exists. Set this option to 1 if you want to overwrite the output files. ```ini overwrite_results = 1 ``` Whether to create a single large tiff file for the reconstructed volume. ```ini tiff_single_file = 0 ``` Compression ratio for Jpeg2000 output. ```ini jpeg2000_compression_ratio = ``` Lower and upper bounds to use when converting from float32 to int. Floating point values are clipped to these (min, max) values before being cast to integer. ```ini float_clip_values = ``` ### postproc Whether to compute a histogram of the volume. ```ini output_histogram = 0 ``` Number of bins for the output histogram. Default is one million. ```ini histogram_bins = 1000000 ``` ### resources Computations distribution method. It can be: - local: run the computations on the local machine - slurm: run the computations through SLURM - preview: reconstruct the slices/volume as quickly as possible, possibly doing some binning. ```ini method = local ``` Number of GPUs to use. ```ini gpus = 1 ``` For method = local only. List of GPU IDs to use. This parameter overwrites 'gpus'. If left blank, exactly one GPU will be used, and the best one will be picked. ```ini gpu_id = ``` ### pipeline Save intermediate results. This is a list of comma-separated processing steps, for ex: flatfield, phase, sinogram. Each step generates a HDF5 file in the form name_file_prefix.hdf5 (ex. 'sinogram_file_prefix.hdf5') ```ini save_steps = ``` Resume the processing from a previously saved processing step. The corresponding file must exist in the output directory. ```ini resume_from_step = ``` File where the intermediate processing steps are written. By default it is empty, and intermediate processing steps are written in the same directory as the reconstructions, with a file prefix, ex. sinogram_mydataset.hdf5. ```ini steps_file = ``` Level of verbosity of the processing. 0 = terse, 3 = much information. ```ini verbosity = 2 ```