`TIFFWriter` should write resolution when given `ImageData`

[JeppeKlitgaard]

Description

I think it would be very helpful if TIFFWriter.write() added the correct metadata to the TIFF Files for at least the X and Y resolutions, which I observe to be present in other datasets (https://www.morphosource.org/concern/media/000905028?locale=en as an example).

This data is available in ImageData.geometry (an ImageGeometry instance), so could be used without cost.

Additionally it would be nice to optionally add a JSON or similar sidecar file to the output with the full ImageGeometry, i.e. writer.write(sidecar="json") would dump a JSON representation of the ImageGeometry next to the TIFF stack.

Aside

As an aside: from what I can tell the NikonDataReader doesn't read the distance units (or at least my AcquisitionGeometry ends up reporting distance_units="distance", though I think maybe distance_units is not suppose to be a unit, but rather a quantity (length, pixel, angle))

In any case, it would be neat if the unit data from NikonDataReader could be propagated throughout a reconstruction pipeline without manually keeping track of it.

Current workaround

I currently create a dataclass:

@dataclass(frozen=True, slots=True)
class ReconstructionGeometry:
    voxel_num_x: int
    voxel_num_y: int
    voxel_num_z: int
    voxel_size_x_m: float
    voxel_size_y_m: float
    voxel_size_z_m: float
    center_x_m: float
    center_y_m: float
    center_z_m: float

    @classmethod
    def from_cil_image_geometry(
        cls, ig: ImageGeometry, physical_unit_scale_to_m: float = 1.0
    ) -> Self:
        return cls(
            voxel_num_x=ig.voxel_num_x,
            voxel_num_y=ig.voxel_num_y,
            voxel_num_z=ig.voxel_num_z,
            voxel_size_x_m=ig.voxel_size_x * physical_unit_scale_to_m,
            voxel_size_y_m=ig.voxel_size_y * physical_unit_scale_to_m,
            voxel_size_z_m=ig.voxel_size_z * physical_unit_scale_to_m,
            center_x_m=ig.center_x * physical_unit_scale_to_m,
            center_y_m=ig.center_y * physical_unit_scale_to_m,
            center_z_m=ig.center_z * physical_unit_scale_to_m,
        )

    def save_as_json(self, path: str | Path) -> None:
        path = Path(path)

        with path.open("w") as f:
            json.dump(asdict(self), f, indent=4)

Which I then construct with physical_unit_scale_to_m=1e-3 since my Nikon data is in millimeters. I then save the sidecar after doing writer.write().

Environment

import cil, sys
print(cil.version.version, cil.version.commit_hash, sys.version, sys.platform)
> 26.0.0  3.13.15 | packaged by conda-forge | (main, Aug 10 2026, 13:05:01) [GCC 14.4.0] linux

[gfardell]

In terms of the meta data for TIFFs, I agree this would be a great addition for writing. Would you then expect the reader to parse the json and create the ImageData too? We were previously thinking of making use of the numpy fileformat so allow you to save and load the full CIL ImageData and AcquisitionData.

---

In terms of the units. We currently don't handle units at all. It's expected when you create your acquisition geometry that everything is consistent (i.e. pixel size is in the same units as system distances), and that is consistent with your image geometry. The member does exist, but not used anywhere and no conversion happens. I think it got deprioritised as "a nice idea, but more work that it initially seemed".

If you get the image geometry from the acquisition geometry (ag.get_ImageGeometry()) it'll use the pixel size and magnification to set the voxel size and keep things consistent. The units of your image data is in the inverse of that unit.

It sounds like your pixel size is in different units to your system distances, so potentially that's a issue with the NikonReader. Does that seem likely? Can you post you acquisition geometry, and the NikonReader you are using?

[JeppeKlitgaard]

Thanks for taking a look Gemma!

In terms of the meta data for TIFFs, I agree this would be a great addition for writing. Would you then expect the reader to parse the json and create the ImageData too? We were previously thinking of making use of the numpy fileformat so allow you to save and load the full CIL ImageData and AcquisitionData.

I wouldn't necessarily expect the sidecar to be parseable by CIL again, as I would expect the reconstruction volume not to see CIL again. Mostly I would want to make sure that the size information gets saved somewhere alongside the reconstruction data such that it isn't lost when my messy data bookkeeping means I can't remember the origin of the data.

As such, I don't need it to be a perfect, universal solution. I expect that when doing fuller pipelines I would anyway need to do some tidying up of the reconstruction volume data to get it into the exact format desired by the end user, so the JSON sidecar is just to make sure that the size information never strays to far from the reconstruction data.

For that reason, I think a numpy .npy would not be an ergonomic solution since it can't be read by a human and would be difficult for non-Python tooling to read automatically — the .npy serialization sounds like a good solution, but to a different problem.

This is really 2 separate requests, both of which I think would be nice to have simultaneously:

• Option (perhaps default enabled) to store sidecar with size information next to TIFF stack
  • Purpose: ensure size data is easily viewable at a glance and doesn't get misplaced. Should be human readable without tools (i.e not .npy or .tiff metadata)
• Option to embed size information in the TIFF metadata
  • To work out-of-the-box with various tools (3D Slicer, Napari, ...)

In terms of the units. We currently don't handle units at all. It's expected when you create your acquisition geometry that everything is consistent (i.e. pixel size is in the same units as system distances), and that is consistent with your image geometry. The member does exist, but not used anywhere and no conversion happens. I think it got deprioritised as "a nice idea, but more work that it initially seemed".

I understand, I imagine it would take some significant plumbing to propagate through all of CIL.

If you get the image geometry from the acquisition geometry (ag.get_ImageGeometry()) it'll use the pixel size and magnification to set the voxel size and keep things consistent. The units of your image data is in the inverse of that unit.

It sounds like your pixel size is in different units to your system distances, so potentially that's a issue with the NikonReader. Does that seem likely? Can you post you acquisition geometry, and the NikonReader you are using?

I don't think there is anything wrong with the NikonReader, it correctly reads them in millimetres here. I only do the conversion because I want ReconstructionVolume to be very simple (so distances must be given in one specific unit rather than also storing the unit as a string). I make the choice to have the distances in metres, but this is of course an arbitrary choice.