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

TL;DR

For "completed with error": both a fixed and a moving image are selected. An output is selected (output transform and/or output volume). If not, recenter first (the FAQ's "Manual Recenter" step) and rerun with an initializer. 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.

completed with error

When to use

You are seeing this: 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. Use this skill when you run into "Diagnose automatic registration failures in 3D Slicer (BRAINS/Elastix)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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

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