Under the Hood#

This section summarises the concepts that make TexTOM work. Use it to understand which parameters matter most when tuning reconstructions.

Diffractlets#

TexTOM models diffraction using either:

  • Harmonic (HSH) basis: Expands the orientation distribution in hyperspherical harmonics. Controlled by hsh_max_order; higher orders capture sharper textures at the cost of runtime.

  • Grid-based basis: Discretises orientation space directly (set odf_mode="grid" and a grid_resolution in degrees).

A diffractlet stores the scattering response of a specific Miller index under rotation. Adjust max_hkl, q_range, and cutoff_structure_factor in crystal.py to limit computation to physically relevant peaks.

Projectors#

Projectors encode which voxels contribute to each detector pixel after alignment. The workflow:

  1. Downsample and histogram the aligned tomogram.

  2. Choose a density threshold to isolate the specimen from background.

  3. Optionally smooth and fill holes to avoid discontinuities.

  4. Save the resulting operators to analysis/projectors.h5.

Lower thresholds include more voxels (safer but slower); higher thresholds risk trimming thin features. Keep an eye on the preview mesh before accepting.

Optimisation Loop#

For each voxel TexTOM tries to minimise the mismatch between measured intensities and simulated diffractlet responses:

  1. Assemble peak-specific datasets produced during preprocessing.

  2. Evaluate forward models using current ODF coefficients.

  3. Compute residuals and update coefficients via gradient-based routines.

  4. Repeat until the loss function or residual norms stabilise.

Key stopping levers:

  • Number of iterations (set in the optimisation prompt).

  • Convergence tolerance (smaller values mean tighter fits but longer runtime).

  • Regularisation options within the prompt (e.g., smoothness constraints) if overfitting occurs.

Orientation Statistics#

Post-fit, TexTOM derives summary metrics:

  • g_pref: Preferred orientation in axis-angle form.

  • a_pref, b_pref, c_pref: Unit vectors of the crystal axes aligned with the local specimen frame.

  • std: Spread of the orientation distribution. Narrow values imply well-aligned grains.

  • scaling: Proxy for crystalline volume fraction per voxel.

Misorientations (mori) and nematic order parameters help interpret fibre textures or segment the sample (see calculate_segments, calculate_order_parameters).

Visualisation Pipeline#

Visualization utilities share a few expectations:

  • They consume the results dictionary produced by calculate_orientation_statistics or loaded via load_results.

  • IPF plots require specifying crystal directions (e.g., [0,0,1]) and sample axes.

  • show_voxel_odf/show_voxel_polefigure demand voxel indices; use show_volume to locate them first.

Saving figures (save_images) is recommended when documenting experiments; combine outputs with Paraview exports for multi-tool validation.