ENH: Add ngff-zarr multi-resolution registration example

[thewtex]

Add Example 23 demonstrating a workflow that combines ngff-zarr multi-resolution image pyramids with ITKElastix registration:

• Convert ITK images to ngff-zarr Multiscales via to_multiscales
• Register at a coarse resolution (rigid + affine + bspline)
• Convert Elastix results to itk.CompositeTransform
• Apply the transform at full resolution in parallel using dask.array.map_blocks with itk.resample_image_filter

Uses itk_image_to_ngff_image and ngff_image_to_itk_image to bridge between ITK and ngff-zarr data representations.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[N-Dekker]

@thewtex Please do git rebase main on this PR! It appears 14 commits behind!

By the way, what does "9566-example-demonstr" mean?

[thewtex]

@thewtex Please do git rebase main on this PR! It appears 14 commits behind!

@N-Dekker 👍 done!

By the way, what does "9566-example-demonstr" mean?

This is a unique identifier for the git worktree I am using.

[N-Dekker]

Thanks for looking at my initial comments, Matt! Did you push the changes you made to address them?

[N-Dekker]

Maybe beyond the scope of this PR, but "CT_2D_head_fixed.mha" looks a bit warped. Especially when looking at the border of the skull. I see, you introduced the image by 56caa00 (back in 2020).

In MeVisLab ("CT_2D_head_fixed.mha" at the left side, "CT_2D_head_moving.mha" at the right):

Do you still remember where "CT_2D_head_fixed.mha" and "CT_2D_head_moving.mha" came from?

[thewtex]

Thanks for looking at my initial comments, Matt! Did you push the changes you made to address them?

@N-Dekker oops, I think I pushed them to the wrong remote -- re-pushed!

[thewtex]

Maybe beyond the scope of this PR, but "CT_2D_head_fixed.mha" looks a bit warped. Especially when looking at the border of the skull. I see, you introduced the image by 56caa00 (back in 2020).

This is intentional, an artificially induced warp. I believe these images come from the ITK Software Guide.

[N-Dekker]

This is intentional, an artificially induced warp. I believe these images come from the ITK Software Guide.

Ah, thanks, I see similar images now, in InsightSoftwareGuide-Book2-5.4.6.pdf, although not warped:

Still, I would expect the warping to take place on the moving image, during registration (bspline), and no warping of the fixed image 🤷

---

Update, I see now, the T1 image (before warping) is at https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/7510e24a4dd8e98b6ee582c2468961f69ca1ec4b/SoftwareGuide/Art/BrainT1Slice.jpg

[N-Dekker]

@thewtex Thanks for addressing my initial comments, Matt. Feel free to ignore my comment about the artificially warped image. It appears that Marius (@mstaring) actually likes the warped image 😃 I think the other remaining comments that I had are still relevant. Please consider them, when you have the time.

[vboussot]

Hi @N-Dekker, @thewtex,

I updated the example so the full-resolution resampling is out-of-core: the new ngff_zarr.itk_transform_resample_bounding_box (fideus-labs/ngff-zarr#632) computes from geometry alone the moving-image region the resample will read, and only that region is materialized. The output grid is also re-chunked so map_blocks really resamples 16 blocks in parallel.

[thewtex]

@vboussot looking good 🔢

To make the functionality more illustrative, can we draw colored bounding boxes in images with matplotlib for:

1. A single region in the fixed image, the corresponding resampling region in the moving image
2. A region with different padding parameters in the moving, different shades of the same color
3. All the regions from the fixed image and their correspondence in the moving image, different colors per region, that are used in a full block-wise resample

?

[N-Dekker]

@thewtex @vboussot I see that this pull request is very much renewed now, wow! Are my original comments (from before July) still going to be addressed?

[vboussot]

Hi @niels !

All your comments are addressed, squashed into a single commit: no more =None defaults, variables renamed to *_image, and the float casts removed.

The example now also demonstrates out-of-core resampling: with ngff_zarr.itk_transform_resample_bounding_box, each block reads only the moving-image region its resample needs that's what map_blocks adds over ITK's own multi-threading and the new figures visualize those regions.

Thanks for the careful review!

[thewtex]

@vboussot thanks for the updates 💯

Can we please run the notebook, save the cell outputs? That way people can see the figures in the rendered notebooks on GitHub with a web browser.

[N-Dekker]

Hi (@)niels !

Thanks for the careful review!

Hi @vboussot,

You're welcome, but honestly I still need to review most of your part! Please wait! Today I'll have a look!

Minor nitpick: "Niels" is my first name, but it's not my GitHub name! On GitHub, just use @N-Dekker to address me!

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

N-Dekker commented on 2026-08-14T14:12:59Z
----------------------------------------------------------------

Line #2.    itk_composite_transform = itk.CompositeTransform[itk.D, 2].cast(

Please do not do cast here, if possible. The ITKElastix function registration_method.ConvertToItkTransform already returns an itk.CompositeTransform[itk.D, 2] object. (We should try to avoid unnecessary casts.)

---

Update: I see now, removing the itk.CompositeTransform[itk.D, 2].cast triggers an error, locally on my PC. I don't know why 🤷 Here is the output that I locally got from cell 15:

AttributeError                            Traceback (most recent call last)
Cell In[15], line 5
      1 # 1. One fixed block and the moving-image region its resample reads.
      2 locations = block_locations(fixed_grid)
      3 location = locations[5]  # an interior block
      4 
----> 5 region = block_bounding_box(location)
      6 
      7 fig, axs = plt.subplots(1, 2, figsize=[12, 6])
      8 axs[0].imshow(fixed_array, cmap="gray")

Cell In[14], line 28, in block_bounding_box(array_location, padding)
     24         dims=fixed_full.dims,
     25         scale=fixed_full.scale,
     26         translation=block_translation,
     27     )
---> 28     return itk_transform_resample_bounding_box(
     29         itk_composite_transform, block_grid, moving_full, padding=padding
     30     )

File ~\.conda\envs\ITKElx-0254-pip-py313\Lib\site-packages\ngff_zarr\itk_transform_resample_bounding_box.py:425, in itk_transform_resample_bounding_box(transform, fixed, moving, padding)
    413     zeros = dict.fromkeys(fixed_spatial, 0)
    414     return ResampleBoundingBox(
    415         dims=tuple(fixed_spatial),
    416         start_index=dict(zeros),
   (...)    422         moving_shape=moving_shape,
    423     )
--> 425 transform_list = _as_itk_transform_list(transform)
    426 fixed_direction = _itk_direction(fixed, itk_dims)
    427 moving_direction = _itk_direction(moving, itk_dims)

File ~\.conda\envs\ITKElx-0254-pip-py313\Lib\site-packages\ngff_zarr\itk_transform_resample_bounding_box.py:294, in _as_itk_transform_list(transform)
    291 if hasattr(transform, "GetTransformTypeAsString"):
    292     import itk
--> 294     as_dict = itk.dict_from_transform(transform)
    295     if isinstance(as_dict, dict):
    296         as_dict = [as_dict]

File ~\.conda\envs\ITKElx-0254-pip-py313\Lib\site-packages\itk\support\extras.py:1100, in dict_from_transform(transform)
   1098         add_transform_dict(t)
   1099 else:
-> 1100     multi = add_transform_dict(transform)
   1102 if multi:
   1103     return dict_array

File ~\.conda\envs\ITKElx-0254-pip-py313\Lib\site-packages\itk\support\extras.py:1087, in dict_from_transform.<locals>.add_transform_dict(transform)
   1083 transform_type = transform.GetTransformTypeAsString()
   1084 if "CompositeTransform" in transform_type:
   1085     # Add the transforms inside the composite transform
   1086     # range is over-ridden so using this hack to create a list
-> 1087     for i, _ in enumerate([0] * transform.GetNumberOfTransforms()):
   1088         current_transform = transform.GetNthTransform(i)
   1089         dict_array.append(update_transform_dict(current_transform))

AttributeError: 'itkTransformD22' object has no attribute 'GetNumberOfTransforms'

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

thewtex commented on 2026-08-14T14:38:32Z
----------------------------------------------------------------

Since they are different modality, I think we should remove the difference here.

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

N-Dekker commented on 2026-08-14T16:28:20Z
----------------------------------------------------------------

Line #3.        block_info=None,

Sorry for nitpicking, but this =None may also be removed, right?

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

N-Dekker commented on 2026-08-14T16:28:20Z
----------------------------------------------------------------

Line #4.        *,

The use of an asterisk (*) in a function parameter list is new to me, I have to admit. Just for my understanding, is this an important part of the function declaration, or just a nicety? I read that it will make the following parameters "keyword-arguments". So then, would it be even nicer to move the asterisk one line up? As in:

def resample_block(

  block,

  *,

  block_info,

  transform,

  fixed_image,

  moving_image,

)

So that only the first parameter would be an ordinary "positional argument"...?

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

N-Dekker commented on 2026-08-21T14:13:19Z
----------------------------------------------------------------

Line #2.    # ConvertToItkTransform hands back the itk.Transform[itk.D, 2, 2] base, so the

Thank you for clarifying why the cast is necessary! In the future, I hope that such a cast is no longer necessary, as I just made a pull request to add a new member function, ElastixRegistrationMethod::ConvertCompositionToItkTransform, which returns a CompositeTransform. Please check: SuperElastix/elastix#1464 Anyway, for now I agree that the cast should still be there!

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

N-Dekker commented on 2026-08-24T12:03:16Z
----------------------------------------------------------------

Line #4.    scale_factors = [2, 4]

For the described registration use case, only the coarsest resolution level is used, so I guess a single scale factor (scale_factors=[4]) would be sufficient, right? No problem for me, just asking, for my understanding. So in practice, users would just use a single scale factor, right?

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

N-Dekker commented on 2026-08-24T13:28:22Z
----------------------------------------------------------------

Line #30.        array_location = block_info[0]["array-location"]

I find this array-location stuff a bit hard to understand. Does each block_info[i] have a different "array-location"? A previous revision had some explanation, saying:

  # block_info[0]['array-location'] gives [(y_start, y_stop), (x_start, x_stop)]

  # for a 2D array with dims (y, x)

Would this comment still be applicable?

[vboussot]

@N-Dekker @thewtex 962ce96 addresses the remaining threads; the notebook is re-executed with saved outputs.

• array-location: block_info is keyed by the position of each array passed to map_blocks. fixed_grid is the only one, so block_info[0] describes the current block of it, and its "array-location" is [(y_start, y_stop), (x_start, x_stop)], the block's index range along each dim of the fixed image. This is now commented in resample_block.
• CompositeTransform cast: ENH: Add ConvertCompositionToItkTransform to ElastixRegistrationMethod SuperElastix/elastix#1464 is merged, thanks. ITKElastix pins elastix at ef34ca99, 54 commits before that merge, and itk-elastix 0.25.4 does not expose ConvertCompositionToItkTransform yet, so the cast stays. The comment now points to the new method so it can be dropped once ITKElastix updates its elastix.
• scale_factors=[2, 4]: yes, scale_factors=[4] is enough for the registration alone. The intermediate level is what a stored OME-Zarr pyramid typically carries for visualization, and the example builds the same kind of pyramid; the markdown says this now.
• block_info=None and the * placement: already in 648a616 (block is the only positional parameter, everything after * is keyword-only with no defaults).
• Difference panel (different modalities): removed in 648a616; the final figure shows fixed, moving, and resampled moving.