---
title: Under the Hood
---

# 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.