BUG: Read MPP Metadata From NGFF v0.4 Zattrs (#486)

This PR adds support for reading MPP metadata from v0.4 NGFF which was missing.
It currently only supports units in micrometers and will use the first scale transform in the axis `coordainteTransformations` list in `.zattrs`.

## To-Do
- [x] Unit test coverage

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Shan E Ahmed Raza <[email protected]>

Author: 3 people

tests/test_wsireader.py

@@ -1903,6 +1903,69 @@ def test_is_ngff_regular_zarr(tmp_path):
     assert not is_ngff(zarr_path)
 
 
+def test_ngff_zattrs_non_micrometer_scale_mpp(tmp_path):
+    """Test that mpp is None if scale is not in micrometers."""
+    sample = _fetch_remote_sample("ngff-1")
+    # Create a copy of the sample with a non-micrometer scale
+    sample_copy = tmp_path / "ngff-1"
+    shutil.copytree(sample, sample_copy)
+    with open(sample_copy / ".zattrs", "r") as fh:
+        zattrs = json.load(fh)
+    zattrs["multiscales"][0]["axes"][0]["unit"] = "foo"
+    with open(sample_copy / ".zattrs", "w") as fh:
+        json.dump(zattrs, fh, indent=2)
+    with pytest.warns(UserWarning, match="micrometer"):
+        wsi = wsireader.NGFFWSIReader(sample_copy)
+    assert wsi.info.mpp is None
+
+
+def test_ngff_zattrs_missing_axes_mpp(tmp_path):
+    """Test that mpp is None if axes are missing."""
+    sample = _fetch_remote_sample("ngff-1")
+    # Create a copy of the sample with no axes
+    sample_copy = tmp_path / "ngff-1"
+    shutil.copytree(sample, sample_copy)
+    with open(sample_copy / ".zattrs", "r") as fh:
+        zattrs = json.load(fh)
+    zattrs["multiscales"][0]["axes"] = []
+    with open(sample_copy / ".zattrs", "w") as fh:
+        json.dump(zattrs, fh, indent=2)
+    wsi = wsireader.NGFFWSIReader(sample_copy)
+    assert wsi.info.mpp is None
+
+
+def test_ngff_empty_datasets_mpp(tmp_path):
+    """Test that mpp is None if there are no datasets."""
+    sample = _fetch_remote_sample("ngff-1")
+    # Create a copy of the sample with no axes
+    sample_copy = tmp_path / "ngff-1"
+    shutil.copytree(sample, sample_copy)
+    with open(sample_copy / ".zattrs", "r") as fh:
+        zattrs = json.load(fh)
+    zattrs["multiscales"][0]["datasets"] = []
+    with open(sample_copy / ".zattrs", "w") as fh:
+        json.dump(zattrs, fh, indent=2)
+    wsi = wsireader.NGFFWSIReader(sample_copy)
+    assert wsi.info.mpp is None
+
+
+def test_nff_no_scale_transforms_mpp(tmp_path):
+    """Test that mpp is None if no scale transforms are present."""
+    sample = _fetch_remote_sample("ngff-1")
+    # Create a copy of the sample with no axes
+    sample_copy = tmp_path / "ngff-1"
+    shutil.copytree(sample, sample_copy)
+    with open(sample_copy / ".zattrs", "r") as fh:
+        zattrs = json.load(fh)
+    for i, _ in enumerate(zattrs["multiscales"][0]["datasets"]):
+        datasets = zattrs["multiscales"][0]["datasets"][i]
+        datasets["coordinateTransformations"][0]["type"] = "identity"
+    with open(sample_copy / ".zattrs", "w") as fh:
+        json.dump(zattrs, fh, indent=2)
+    wsi = wsireader.NGFFWSIReader(sample_copy)
+    assert wsi.info.mpp is None
+
+
 class TestReader:
     scenarios = [
         (
@@ -2084,3 +2147,10 @@ def test_file_path_does_not_exist(sample_key, reader_class):
         """Test that FileNotFoundError is raised when file does not exist."""
         with pytest.raises(FileNotFoundError):
             _ = reader_class("./foo.bar")
+
+    @staticmethod
+    def test_read_mpp(sample_key, reader_class):
+        """Test that the mpp is read correctly."""
+        sample = _fetch_remote_sample(sample_key)
+        wsi = reader_class(sample)
+        assert wsi.info.mpp == pytest.approx(0.25, 1)

tiatoolbox/wsicore/metadata/ngff.py

@@ -96,8 +96,8 @@ class CoordinateTransform:
             The scale factors. Must be one for each axis.
     """
 
-    type: str = "scale"  # noqa: A003
-    scale: List[float] = field(default_factory=lambda: [1.0, 0.5, 0.5])
+    type: str = "identity"  # noqa: A003
+    scale: Optional[List[float]] = None
 
 
 @dataclass

tiatoolbox/wsicore/wsireader.py

@@ -4200,7 +4200,15 @@ def __init__(self, path, **kwargs):
             multiscales=ngff.Multiscales(
                 version=multiscales.get("version"),
                 axes=[ngff.Axis(**axis) for axis in axes],
-                datasets=[ngff.Dataset(**dataset) for dataset in datasets],
+                datasets=[
+                    ngff.Dataset(
+                        path=dataset["path"],
+                        coordinateTransformations=dataset.get(
+                            "coordinateTransformations",
+                        ),
+                    )
+                    for dataset in datasets
+                ],
             ),
             omero=ngff.Omero(
                 name=omero.get("name"),
@@ -4217,17 +4225,60 @@ def __init__(self, path, **kwargs):
         }
 
     def _info(self):
+        multiscales = self.zattrs.multiscales
         return WSIMeta(
-            axes="".join(axis.name.upper() for axis in self.zattrs.multiscales.axes),
+            axes="".join(axis.name.upper() for axis in multiscales.axes),
             level_dimensions=[
                 array.shape[:2][::-1]
                 for _, array in sorted(self._zarr_group.arrays(), key=lambda x: x[0])
             ],
             slide_dimensions=self._zarr_group[0].shape[:2][::-1],
             vendor=self.zattrs._creator.name,  # skipcq
             raw=self._zarr_group.attrs,
+            mpp=self._get_mpp(),
         )
 
+    def _get_mpp(self) -> Optional[Tuple[float, float]]:
+        """Get the microns-per-pixel (MPP) of the slide.
+
+        Returns:
+            Tuple[float, float]:
+                The mpp of the slide an x,y tuple. None if not available.
+
+        """
+        # Check that the required axes are present
+        multiscales = self.zattrs.multiscales
+        axes_dict = {a.name.lower(): a for a in multiscales.axes}
+        if "x" not in axes_dict or "y" not in axes_dict:
+            return None
+        x = axes_dict["x"]
+        y = axes_dict["y"]
+
+        # Check the units,
+        # Currently only handle micrometer units
+        if x.unit != y.unit != "micrometer":
+            warnings.warn(
+                f"Expected units of micrometer, got {x.unit} and {y.unit}",
+                UserWarning,
+            )
+            return None
+
+        # Check that datasets is non-empty and has at least one coordinateTransformation
+        if (
+            not multiscales.datasets
+            or not multiscales.datasets[0].coordinateTransformations
+        ):
+            return None
+
+        # Currently simply using the first scale transform
+        transforms = multiscales.datasets[0].coordinateTransformations
+        for t in transforms:
+            if "scale" in t and t.get("type") == "scale":
+                x_index = multiscales.axes.index(x)
+                y_index = multiscales.axes.index(y)
+                return (t["scale"][x_index], t["scale"][y_index])
+        return None
+
     def read_rect(
         self,
         location,

whitelist.txt

@@ -18,6 +18,7 @@ DICOM
 DNS
 Dataloader
 Dataset
+Datasets
 Delaunay
 E1120
 FCN