Add get_FOV_size() (#65)

* add dimensions_in_pixels and dimensions_in_voxels

* update mock functions

* update README

* update docs

* update notebooks

* update changelog

* Add FOV size calculation methods for Planar and Volumetric Imaging Spaces

* Fix pixel_size_in_um type in mock_PlanarImagingSpace function

* Add tests for FOV size calculations

* update README

* update CHANGELOG

* update docs

Author: alessandratrapani

CHANGELOG.md

@@ -16,6 +16,7 @@
 - Refactored segmentation classes: Sub-Issue[#56](https://github.com/catalystneuro/ndx-microscopy/issues/56)
   - Renamed `Segmentation2D` to `PlanarSegmentation`
   - Renamed `Segmentation3D` to `VolumetricSegmentation`
+- Added `get_FOV_size()` method to both `PlanarImagingSpace` and `VolumetricImagingSpace` classes for calculating Field of View size in micrometers Sub-Issue[#53](https://github.com/catalystneuro/ndx-microscopy/issues/53)
 
 # v0.2.1 (March 28, 2025)
 

README.md

@@ -367,6 +367,10 @@ classDiagram
         --------------------------------------
         pixel_size_in_um : float64[2], optional
         dimensions_in_pixels : float64[2], optional 
+        --------------------------------------
+        methods
+        --------------------------------------
+        get_FOV_size()
     }
 
     class VolumetricImagingSpace {
@@ -376,6 +380,10 @@ classDiagram
         --------------------------------------
         voxel_size_in_um : float64[3], optional
         dimensions_in_voxels : float64[3], optional 
+        --------------------------------------
+        methods
+        --------------------------------------
+        get_FOV_size()
     }
 
     class MicroscopyRig {

docs/source/api.rst

@@ -85,12 +85,19 @@ PlanarImagingSpace
    :undoc-members:
    :show-inheritance:
 
+Methods
+^^^^^^^
+.. automethod:: ndx_microscopy.PlanarImagingSpace.get_FOV_size
 VolumetricImagingSpace
 ---------------------
 .. autoclass:: ndx_microscopy.VolumetricImagingSpace
    :members:
    :undoc-members:
    :show-inheritance:
+   
+Methods
+^^^^^^^
+.. automethod:: ndx_microscopy.VolumetricImagingSpace.get_FOV_size
 
 Microscopy Series Components
 =========================

docs/source/release_notes.rst

@@ -3,6 +3,28 @@
 *************
 Release Notes
 *************
+Version 0.3.0 (May, 2025)
+==============================
+
+Deprecations and Changes
+-------------------------
+
+
+Features
+--------
+
+
+Improvements
+------------
+
+* Added `dimensions_in_pixels` to `PlanarImagingSpace` and `dimensions_in_voxels` to `VolumetricImagingSpace`
+* Added `get_FOV_size()` method to both `PlanarImagingSpace` and `VolumetricImagingSpace` classes for calculating Field of View size in micrometers
+
+Notes
+------
+
+
+
 
 Version 0.3.0 (Jun 3, 2025)
 ==============================

src/pynwb/ndx_microscopy/ndx_microscopy.py

@@ -5,6 +5,121 @@
 
 extension_name = "ndx-microscopy"
 
+# PlanarImagingSpace API functions
+
+PlanarImagingSpace = get_class("PlanarImagingSpace", extension_name)
+
+
+@docval(
+    {
+        "name": "dimensions_in_pixels",
+        "type": (tuple, "array_data"),
+        "doc": "the size of the image in pixels",
+        "default": None,
+    },
+    {
+        "name": "pixel_size_in_um",
+        "type": (tuple, "array_data"),
+        "doc": "the size of a pixel in micrometers",
+        "default": None,
+    },
+    allow_extra=True,
+)
+def get_FOV_size(self, **kwargs):
+    """Get the size of the Field of View (FOV) in micrometers.
+
+    Parameters
+    ----------
+    dimension_in_pixels : int or tuple, optional
+        The size of the image in pixels. If not provided, will use the imaging space's dimension.
+    pixel_size_in_um : float or tuple, optional
+        The size of a pixel in micrometers. If not provided, will use the imaging space's pixel size.
+
+    Returns
+    -------
+    tuple
+        The size of the FOV in micrometers as (height, width).
+    """
+    dimensions_in_pixels, pixel_size_in_um = popargs("dimensions_in_pixels", "pixel_size_in_um", kwargs)
+    # Use instance attributes if parameters not provided
+    if dimensions_in_pixels is None:
+        dimensions_in_pixels = getattr(self, "dimensions_in_pixels", None)
+        if dimensions_in_pixels is None:
+            raise ValueError("dimensions_in_pixels must be provided either as parameter or set on the imaging space")
+
+    if pixel_size_in_um is None:
+        pixel_size_in_um = getattr(self, "pixel_size_in_um", None)
+        if pixel_size_in_um is None:
+            raise ValueError("pixel_size_in_um must be provided either as parameter or set on the imaging space")
+
+    # Convert to numpy arrays for element-wise multiplication
+    dimensions_in_pixels = np.asarray(dimensions_in_pixels)
+    pixel_size_in_um = np.asarray(pixel_size_in_um)
+
+    FOV_size = dimensions_in_pixels * pixel_size_in_um
+    return tuple(FOV_size)
+
+
+PlanarImagingSpace.get_FOV_size = get_FOV_size
+
+
+# VolumetricImagingSpace API functions
+
+VolumetricImagingSpace = get_class("VolumetricImagingSpace", extension_name)
+
+
+@docval(
+    {
+        "name": "dimensions_in_voxels",
+        "type": (tuple, "array_data"),
+        "doc": "the size of the image in voxels",
+        "default": None,
+    },
+    {
+        "name": "voxel_size_in_um",
+        "type": (tuple, "array_data"),
+        "doc": "the size of a voxel in micrometers",
+        "default": None,
+    },
+    allow_extra=True,
+)
+def get_FOV_size(self, **kwargs):
+    """Get the size of the Field of View (FOV) in micrometers.
+
+    Parameters
+    ----------
+    dimension_in_voxels : int or tuple, optional
+        The size of the image in voxels. If not provided, will use the imaging space's dimension.
+    voxel_size_in_um : float or tuple, optional
+        The size of a voxel in micrometers. If not provided, will use the imaging space's voxel size.
+
+    Returns
+    -------
+    tuple
+        The size of the FOV in micrometers as (depth, height, width).
+    """
+    dimensions_in_voxels, voxel_size_in_um = popargs("dimensions_in_voxels", "voxel_size_in_um", kwargs)
+    # Use instance attributes if parameters not provided
+    if dimensions_in_voxels is None:
+        dimensions_in_voxels = getattr(self, "dimensions_in_voxels", None)
+        if dimensions_in_voxels is None:
+            raise ValueError("dimensions_in_voxels must be provided either as parameter or set on the imaging space")
+
+    if voxel_size_in_um is None:
+        voxel_size_in_um = getattr(self, "voxel_size_in_um", None)
+        if voxel_size_in_um is None:
+            raise ValueError("voxel_size_in_um must be provided either as parameter or set on the imaging space")
+
+    # Convert to numpy arrays for element-wise multiplication
+    dimensions_in_voxels = np.asarray(dimensions_in_voxels)
+    voxel_size_in_um = np.asarray(voxel_size_in_um)
+
+    FOV_size = dimensions_in_voxels * voxel_size_in_um
+    return tuple(FOV_size)
+
+
+VolumetricImagingSpace.get_FOV_size = get_FOV_size
+
 
 # PlanarSegmentation API functions
 

src/pynwb/ndx_microscopy/testing/_mock.py

@@ -169,7 +169,7 @@ def mock_PlanarImagingSpace(
     name: Optional[str] = None,
     description: str = "A mock instance of a PlanarImagingSpace type to be used for rapid testing.",
     origin_coordinates: Tuple[float, float, float] = (-1.2, -0.6, -2),
-    pixel_size_in_um: Tuple[float, float, float] = (20, 20),
+    pixel_size_in_um: Tuple[float, float] = (20, 20),
     dimensions_in_pixels: Tuple[int, int] = (100, 100),
     location: str = "The location targeted by the mock imaging space.",
     reference_frame: str = "The reference frame of the mock planar imaging space.",

src/pynwb/tests/test_api_functions.py

@@ -18,6 +18,56 @@
 )
 
 
+def test_planar_get_fov_size_with_parameters():
+    """Test PlanarImagingSpace.get_FOV_size with explicit parameters."""
+    planar_imaging_space = mock_PlanarImagingSpace()
+
+    # Test with explicit parameters
+    dimensions = (100, 200)  # x, y in pixels
+    pixel_size = (0.5, 0.5)  # x, y in micrometers
+
+    fov_size = planar_imaging_space.get_FOV_size(dimensions_in_pixels=dimensions, pixel_size_in_um=pixel_size)
+
+    expected_fov = (50.0, 100.0)  # 100*0.5, 200*0.5
+    assert fov_size == expected_fov
+
+
+def test_planar_get_fov_size_with_instance_attributes():
+    """Test PlanarImagingSpace.get_FOV_size using instance attributes."""
+    planar_imaging_space = mock_PlanarImagingSpace(dimensions_in_pixels=[150, 300], pixel_size_in_um=[0.2, 0.3])
+
+    fov_size = planar_imaging_space.get_FOV_size()
+
+    expected_fov = (30.0, 90.0)  # 150*0.2, 300*0.3
+    assert fov_size == expected_fov
+
+
+def test_volumetric_get_fov_size_with_parameters():
+    """Test VolumetricImagingSpace.get_FOV_size with explicit parameters."""
+    volumetric_imaging_space = mock_VolumetricImagingSpace()
+
+    # Test with explicit parameters
+    dimensions = (50, 100, 200)  # x, y, z in voxels
+    voxel_size = (0.5, 0.5, 1.0)  # x, y, z in micrometers
+
+    fov_size = volumetric_imaging_space.get_FOV_size(dimensions_in_voxels=dimensions, voxel_size_in_um=voxel_size)
+
+    expected_fov = (25.0, 50.0, 200.0)  # 50*0.5, 100*0.5, 200*1.0
+    assert fov_size == expected_fov
+
+
+def test_volumetric_get_fov_size_with_instance_attributes():
+    """Test VolumetricImagingSpace.get_FOV_size using instance attributes."""
+    volumetric_imaging_space = mock_VolumetricImagingSpace(
+        dimensions_in_voxels=[60, 120, 240], voxel_size_in_um=[0.2, 0.3, 0.5]
+    )
+
+    fov_size = volumetric_imaging_space.get_FOV_size()
+
+    expected_fov = (12.0, 36.0, 120.0)  # 60*0.2, 120*0.3, 240*0.5
+    assert fov_size == expected_fov
+
+
 def test_planar_pixel_to_image_conversion():
     """Test conversion from pixel_mask to image_mask for 2D."""
     planar_imaging_space = mock_PlanarImagingSpace()