Issue(reg): requested box does not overlap layer bounds

[chourroutm]

In the branch https://github.com/HiPCTProject/ngregister/tree/feature/refine-registration-sitk, I get the following error:

RuntimeError: refine: requested box does not overlap layer bounds (gs://ucl-hip-ct-35a68e99feaae8932b1d44da0358940b/I74/brain-left_hemisphere/20.07um_overview_bm18.ome.zarr/|zarr3:); check the landmark and box size.

The state is given below:

Details

{
  "dimensions": {
    "x": [
      0.000004257,
      "m"
    ],
    "y": [
      0.000004257,
      "m"
    ],
    "z": [
      0.000004257,
      "m"
    ]
  },
  "position": [
    3929.161865234375,
    4737.76953125,
    3645.5
  ],
  "crossSectionScale": 33.20116922736548,
  "projectionOrientation": [
    0.3094263970851898,
    0.20628425478935242,
    0,
    -0.9282791018486023
  ],
  "projectionScale": 4096,
  "layers": [
    {
      "type": "image",
      "source": {
        "url": "gs://ucl-hip-ct-35a68e99feaae8932b1d44da0358940b/I74/brain-left_hemisphere/20.07um_overview_bm18.ome.zarr/|zarr3:",
        "transform": {
          "matrix": [
            [
              0.998819,
              -0.048837,
              0,
              -8380.795105
            ],
            [
              0.048837,
              0.998819,
              0,
              -11282.219083
            ],
            [
              0,
              0,
              1.000012,
              -14292.909991
            ]
          ],
          "outputDimensions": {
            "x": [
              0.000004257,
              "m"
            ],
            "y": [
              0.000004257,
              "m"
            ],
            "z": [
              0.000004257,
              "m"
            ]
          }
        }
      },
      "tab": "source",
      "opacity": 0.36,
      "shaderControls": {
        "normalized": {
          "range": [
            27070,
            35186
          ]
        }
      },
      "volumeRendering": "max",
      "volumeRenderingDepthSamples": 256,
      "name": "I74_brain_left_hemisphere_overview_20.07um_bm18"
    },
    {
      "type": "image",
      "source": "gs://ucl-hip-ct-35a68e99feaae8932b1d44da0358940b/I74/brain-left_hemisphere/4.257um_VOI-1_bm18.ome.zarr/|zarr3:",
      "tab": "source",
      "opacity": 1,
      "shaderControls": {
        "normalized": {
          "range": [
            7808,
            8562
          ]
        }
      },
      "volumeRendering": "max",
      "volumeRenderingDepthSamples": 256,
      "name": "I74_brain_left_hemisphere_VOI-1_4.257um_bm18"
    },
    {
      "type": "annotation",
      "source": {
        "url": "local://annotations",
        "transform": {
          "outputDimensions": {
            "x": [
              0.000004257,
              "m"
            ],
            "y": [
              0.000004257,
              "m"
            ],
            "z": [
              0.000004257,
              "m"
            ]
          }
        }
      },
      "tab": "source",
      "annotationColor": "#ff0000",
      "annotations": [
        {
          "point": [
            4525,
            4525,
            3645.5
          ],
          "type": "point",
          "id": "1c326f8a9fd9e1e46e7cba7cdd8d682d244bbc83"
        }
      ],
      "name": "__LANDMARK__"
    }
  ],
  "showSlices": false,
  "selectedLayer": {
    "visible": true,
    "layer": "I74_brain_left_hemisphere_VOI-1_4.257um_bm18"
  },
  "layout": "4panel"
}

[chourroutm]

Fixed in edb591b on feature/refine-registration-sitk.

Root cause. refine_registration treated each layer's neuroglancer transform.matrix as a direct array-index → global-voxel affine. It isn't: the matrix maps the source's intrinsic coordinate (its physical position expressed in global-voxel units), which stays near-identity even when the source is stored at a different resolution than the global frame.

The overview layer is an OME-Zarr whose level-0 voxel is 20.07 µm, viewed in a 4.257 µm global frame (ratio ≈ 4.715). The OME coordinateTransformations carry that scale and neuroglancer applies it, but the refinement ignored it. So the landmark at global [4525, 4525, 3645.5] mapped to overview index [13662, 15158, 17938], far outside the (7569, 7569, 8514) array — hence "requested box does not overlap layer bounds".

Fix.

• New _native_voxel_geometry recovers each source's native voxel size + origin from its resolution metadata: OME coordinateTransformations for zarr (via a refactored _ome_multiscale), resolution for precomputed.
• fetch_layer_image composes that per-axis (ratio, offset) with the layer transform into the full array-index → global-voxel affine, used for both the box clamp and the SimpleITK geometry.
• Global scales are converted to metres via a new _unit_to_meters table, so the native/global ratio is unit-correct.
• Sources stored at the global resolution fall back to an identity mapping, so existing behaviour is unchanged.

Verification. Against the real data in this issue, the corrected mapping lands the landmark at overview index [2897, 3215, 3804] (in bounds). Added test_refine_ome_coarse_resolution_recovers_shift, a coarser-than-global OME source that reproduces the out-of-bounds case; all 9 tests pass.