# Diagnose automatic registration failures in 3D Slicer (BRAINS/Elastix)

Diagnose 3D Slicer automatic registration failures: triage 'completed with error' from the Error Log commandline entry (input checks, BRAINS phase/transform/masking consistency), the 5-10mm/5-degree initial-alignment rule with landmark initialization, distance-map conversion for binary images, and Elastix exit status 3221225477 (0xC0000005 access violation) crash triage.

Exact reference: {"kind":"skill_version","skill_id":"skl_zapmr3Z8HGIarurZN9ImvQ","version_id":"skv_jawbI96Hrw4Yz6Q0ahKlvQ"}

Applicability: [{"constraint":">=5.0","technology":"3D Slicer","version_scheme":"semver"}]

# Diagnose automatic registration failures in 3D Slicer (BRAINS / Elastix)

Use this when an automatic registration (General Registration (BRAINS),
General Registration (Elastix), or BRAINSFit/Elastix under the hood) reports
"completed with error", crashes, hangs, or produces a wrong result. Registration
runs as a command-line module, so the GUI stays responsive while it works — the
evidence is in the **Error Log** (View / Error Log), not in the status message
alone. Open it and scroll to the bottom: you will see the `commandline` entry
with the arguments passed to the algorithm and the algorithm's own output.

## 1. "Completed with error" — check the inputs before anything else

Per the official registration FAQ, the most common failures are wrong or
inconsistent inputs. Verify all of these:

1. Both a **fixed** and a **moving** image are selected.
2. An **output** is selected (output transform and/or output volume). Registering
   without an output target goes nowhere.
3. The two images **overlap** — can you see both in the slice views? If not,
   recenter first (the FAQ's "Manual Recenter" step) and rerun with an
   initializer.
4. Input consistency: General Registration (BRAINS) errors if you check a
   **BSpline registration phase without selecting a BSpline output
   transform**, or request masking without providing masking inputs/outputs.

If the inputs check out, read the Error Log's `commandline`/`standard output`
entries for the algorithm's own error — input-argument problems are reported
there.

## 2. Registration "succeeds" but the result is wrong or unchanged

Automatic intensity-based registration only converges from a reasonable start.
The documented rule of thumb from core developers: the initial error must be
within **5–10 mm translation and 5 degrees rotation**. A grossly misaligned
pair (e.g. a 180° flip) will never converge. Fix:

- Run a **landmark-based registration first** to get a rough alignment, then
  feed that transform in as the initial transform of the automatic registration.
- Center-of-gravity / moments-based initializers handle pure translation
  automatically when the physical extents are similar, but they cannot fix
  large rotation errors.

## 3. You are registering binary images (labelmaps, segmentations)

Intensity-based registration **cannot align binary images**. Convert first:
run a DistanceMap filter from the **Simple Filters** module on both images and
register the resulting distance maps instead of the binary masks.

## 4. Elastix: `Command 'elastix' returned non-zero exit status 3221225477`

Exit status 3221225477 is 0xC0000005 — an **access violation**; the elastix
binary crashed rather than failing cleanly. The Error Log shows the full
command line the SlicerElastix module used (input `.mha` files under a temp
directory like a per-run temp folder under the user profile (`AppData/Local/Temp/Slicer/Elastix/[timestamp]/` on Windows),
parameter files such as `Par0000affine.txt` and `Par0000bspline.txt` from the
extension's `Resources/RegistrationParameters`). Triage:

1. Simplify the pipeline: run a **single rigid/affine stage** first. If affine
   works but the multi-stage run crashes, the bspline stage or a parameter
   file is the culprit.
2. Read the tail of the elastix log (the Error Log reproduces the algorithm
   output): crashes right after "Reading images" point at the input volumes;
   crashes mid-resolution point at memory or the parameter set.
3. Reproduce elastix **outside** Slicer on the same temp inputs if you need to
   isolate whether the crash is the binary or the data.

Warnings like `The parameter "UseDirectionCosines" ... does not exist at all`
are informational (elastix ≥ 4.8 defaults it to true) — do not chase them as
the cause.

## 5. It hangs instead of failing

Registration is a separate process; the Slicer GUI stays usable, so a "hang"
is often just a long computation (bspline on large volumes, multi-threaded).
Before killing it, check the Error Log for progress output and Task Manager /
Activity Monitor for CPU activity on the CLI process. If CPU is idle and no
log output appears for many minutes, kill the process and treat it as case 1
or 4.

## Quick triage checklist

1. Error Log → `commandline` entry: capture the exact failure line.
2. Inputs: fixed + moving + output selected; images overlap; BRAINS phase /
   transform-type / masking consistency (section 1).
3. Wrong result: initial alignment within 5–10 mm / 5°? If not, landmark
   initialization first (section 2).
4. Binary inputs: distance maps, not masks (section 3).
5. Elastix 3221225477: crashed binary — simplify to single affine stage, read
   the log tail (section 4).


## Supporting basis and limitations

Built from the Slicer wiki 'Registration FAQ' (input-consistency checks, initializer selection, Error Log commandline inspection, Manual Recenter), Discourse threads 'Error: Command elastix returned non-zero exit status 3221225477' (crash log with Par0000affine/Par0000bspline parameter files and temp-dir layout), 'Problem with Elastix' (binary/library diagnosis), and 'Registration request for 3D objects' (lassoan's 5-10mm/5-degree rule, landmark initialization, distance maps for binary images via Simple Filters).

## Change and rationale

New skill: diagnose automatic registration failures in 3D Slicer (BRAINS/Elastix).

Registration failures are a perennial Slicer support category and the failure modes need opposite fixes: bad inputs vs too-large initial misalignment vs binary images vs a crashed elastix binary. The official FAQ plus core-developer forum answers give concrete diagnostic evidence (Error Log commandline entry, the 5-10mm/5-degree convergence rule, 0xC0000005 = access violation). This skill turns that into a triage procedure.