Align container algorithm output grid to input (header-only fix, configurable)

Open
#191 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend

Research direction

Start with the output paths in infer_single and infer_batch, then read the algorithm constructor and scripts/_shared.py::validate_output to understand how outputs and affine mismatches are handled. Add unit tests for orientation-only mismatches, already matching affines, other grid mismatches, and disabled alignment; done means the output data stays unchanged and only qualifying headers are aligned by default, with a per-call and constructor opt-out.

Written by the indexing model from the issue text.

Description

Problem

Some containerized algorithms write an output whose header affine does not match the input even though the output volume is on the input voxel grid. Observed with metastases.BraTS23_2 (Siwei Yang) via the verification suite:

  • input t1c affine is LPS, output mask affine is RAS
  • abs(output.affine) equals abs(input.affine) and shapes match
  • mask data is index-aligned with the input (98.6% of mask voxels fall inside the input brain at identical indices)

Because the header is wrong, any consumer that honors the affine (nibabel, resampling, overlays) will place the mask at the wrong world position.

Decision

Add an opt-out output-grid alignment to the package that only triggers on a detected mismatch:

  • Trigger: only when abs(output.affine) == abs(reference.affine) (within tolerance) and shapes match.
  • Action: copy the reference/input affine onto the output (header-only fix), leaving the data array unchanged.
  • Do NOT reorient/flip the data: as_reoriented changes the array and, for the observed case, the index-overlap drops from 0.986 to 0.880, i.e. it would physically rotate the mask (producing a wrong output).
  • Any other mismatch (scale/shear/translation) is left untouched.

Behavior & configuration

  • Default ON (align only on mismatch), opt-out.
  • Configurable per call (infer_single / infer_batch) and on the algorithm constructor.
  • When disabled, output is written exactly as produced by the algorithm.

Risks

  • Critical change: it touches every algorithm's output path. Must be covered by unit tests (mismatch aligned, matching output unchanged, non-header mismatch untouched, flag disables) and called out in the release notes.
  • The assumption "mismatch implies index alignment" holds for the observed case; for a genuinely world-correct output with a different grid this must not auto-fix (guarded by the abs-affine + shape condition).

Detection

The verification suite's -m integration run flags this class of mismatch today (orientation-only warning); see scripts/verify/validation.py and scripts/_shared.py::validate_output.

Dominant language
Python
Stars
89
Forks
19
Avg merge
2d 23h
Merged PRs (30d)
4

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from BrainLesion/BraTS

All issues in BrainLesion/BraTS

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.