Metadata-Version: 2.4
Name: midas-nf-preprocess
Version: 0.1.0
Summary: Differentiable PyTorch port of NF-HEDM preprocessing (CPU/CUDA/MPS): hex grid, tomo filter, diffraction-spot prediction, image processing
Author-email: Hemant Sharma <hsharma@anl.gov>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/marinerhemant/MIDAS
Project-URL: Documentation, https://github.com/marinerhemant/MIDAS/tree/master/packages/midas_nf_preprocess
Project-URL: Issues, https://github.com/marinerhemant/MIDAS/issues
Keywords: MIDAS,NF-HEDM,diffraction,PyTorch,differentiable,image processing,peak detection,near-field,preprocessing,hex grid,tomography
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.22
Requires-Dist: torch>=2.1
Requires-Dist: tifffile>=2022.0
Requires-Dist: midas-diffract>=0.1.0
Requires-Dist: midas-stress>=0.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: scipy>=1.9; extra == "dev"
Provides-Extra: parity
Requires-Dist: scipy>=1.9; extra == "parity"

# midas-nf-process-images

Differentiable PyTorch port of `NF_HEDM/src/ProcessImagesCombined.c` for CPU, CUDA, and MPS.

## Pipeline

For one layer of a near-field HEDM scan:

1. **Load** `NrFilesPerLayer` raw TIFF frames into a `[N, Z, Y]` tensor.
2. **Temporal median** across frames → per-pixel background `[Z, Y]`.
3. **Per-frame**:
   - Subtract median + `BlanketSubtraction`, clamp at 0.
   - Spatial median (3x3 or 5x5).
   - LoG response at one or more scales.
   - Threshold and label connected components → integer spot labels (detached).
   - Sigmoid surrogate → continuous spot-probability map (autograd path).
4. **Accumulate** spot pixels into a bit-packed `SpotsInfo.bin` mmap (drop-in compatible
   with `FitOrientationOMP` / `simulateNF`).

Phases 1, 2, and 3 (filtered, log_response, soft spot probability) are differentiable
end-to-end. Connected components and the binary `SpotsInfo.bin` output are computed on
detached tensors and do not participate in autograd.

## Quickstart

```python
from midas_nf_process_images import ProcessParams, ProcessImagesPipeline

params = ProcessParams.from_paramfile("ps.txt")
pipe = ProcessImagesPipeline(params, device="cuda")  # or "mps", "cpu"
spots = pipe.process_layer(layer_nr=1)
spots.write("/path/to/SpotsInfo.bin")

# Or all layers in one call:
spots = pipe.process_all(layers=range(1, params.n_distances + 1))
```

## CLI

```bash
midas-nf-process-images <ParameterFile> <LayerNr> [--device cuda] [--dtype fp32] [--n-cpus 8]
```

Behaves like the C `ProcessImagesCombined` executable.

## Backend selection

Same contract as `midas-transforms`:

- Default device: `cuda` -> `mps` -> `cpu`.
- Default dtype: `float64` on CPU, `float32` on CUDA/MPS.
- Override with `device=` / `dtype=` kwargs, or env vars
  `MIDAS_NF_PROCESS_IMAGES_DEVICE` / `MIDAS_NF_PROCESS_IMAGES_DTYPE`.

## Differentiability

The end-to-end pipeline produces three tensors:

- `filtered`: median-subtracted, spatial-median-filtered image (autograd).
- `log_response`: LoG convolution output (autograd).
- `spot_prob`: soft, continuous spot-probability map via `sigmoid(L / temperature)` (autograd).

Plus one detached output:

- `labels`: integer connected-component IDs from hard-thresholded LoG (no gradient).

Optimization through the discrete spot mask uses the soft `spot_prob` surrogate.
