docs-Optics (#324)

* Implemented future type hints and removed union.

* typo

* Added: Warning for non-mie scatterers.

* Added comment to import statement

Author: Pwhsky

deeptrack/optics.py

@@ -131,9 +131,9 @@ def _pad_volume(
 >>> image.plot(cmap="gray")
 
 """
-
+from __future__ import annotations
 from pint import Quantity
-from typing import Any, Dict, List, Tuple, Union
+from typing import Any, Dict, List, Tuple
 from deeptrack.backend.units import (
     ConversionTable,
     create_context,
@@ -143,15 +143,15 @@ def _pad_volume(
 from deeptrack.math import AveragePooling
 from deeptrack.features import propagate_data_to_dependencies
 import numpy as np
-from .features import DummyFeature, Feature, StructuralFeature
-from .image import Image, pad_image_to_fft, maybe_cupy
-from .types import ArrayLike, PropertyLike
-from .backend._config import cupy
+from deeptrack.features import DummyFeature, Feature, StructuralFeature
+from deeptrack.image import Image, pad_image_to_fft, maybe_cupy
+from deeptrack.types import ArrayLike, PropertyLike
+from deeptrack.backend._config import cupy
 from scipy.ndimage import convolve
 import warnings
 
 from . import units as u
-from .backend import config
+from deeptrack.backend import config
 from deeptrack import image
 
 
@@ -203,7 +203,7 @@ class Microscope(StructuralFeature):
     __distributed__ = False
 
     def __init__(
-        self:  'Microscope',
+        self:  Microscope,
         sample: Feature,
         objective: Feature,
         **kwargs: Dict[str, Any],
@@ -235,8 +235,8 @@ def __init__(
         self._sample.store_properties()
 
     def get(
-        self: 'Microscope',
-        image: Union[Image, None],
+        self: Microscope,
+        image: Image | None,
         **kwargs:  Dict[str, Any],
     ) -> Image:
         """Generate an image of the sample using the defined optical system.
@@ -246,7 +246,7 @@ def get(
 
         Parameters
         ----------
-        image: Union[Image, None]
+        image: Image | None
             The input image to be processed. If None, a new image is created.
         **kwargs: Dict[str, Any]
             Additional parameters for the imaging process.
@@ -480,11 +480,11 @@ class Optics(Feature):
     )
 
     def __init__(
-        self:  'Optics',
+        self: Optics,
         NA: PropertyLike[float] = 0.7,
         wavelength: PropertyLike[float] = 0.66e-6,
         magnification: PropertyLike[float] = 10,
-        resolution: PropertyLike[Union[float, ArrayLike[float]]] = 1e-6,
+        resolution: PropertyLike[float | ArrayLike[float]] = 1e-6,
         refractive_index_medium: PropertyLike[float] = 1.33,
         padding: PropertyLike[ArrayLike[int]] = (10, 10, 10, 10),
         output_region: PropertyLike[ArrayLike[int]] = (0, 0, 128, 128),
@@ -563,7 +563,7 @@ def __init__(
         """
 
         def get_voxel_size(
-            resolution: Union[float, ArrayLike[float]], 
+            resolution: float | ArrayLike[float], 
             magnification: float,
         ) -> ArrayLike[float]:
             """ Calculate the voxel size.
@@ -587,7 +587,7 @@ def get_voxel_size(
             return np.ones((3,)) * props["resolution"] / props["magnification"]
 
         def get_pixel_size(
-            resolution: Union[float, ArrayLike[float]],
+            resolution: float | ArrayLike[float],
             magnification: float,
         ) -> float:
             """ Calculate the pixel size.
@@ -641,8 +641,8 @@ def get_pixel_size(
         )
 
     def _process_properties(
-        self:   'Optics',
-        propertydict:   Dict[str, Any],
+        self: Optics,
+        propertydict: Dict[str, Any],
     ) -> Dict[str, Any]:
         """Processes and validates the input properties.
 
@@ -681,13 +681,13 @@ def _process_properties(
         return propertydict
 
     def _pupil(
-        self:  'Optics',
+        self: Optics,
         shape: ArrayLike[int],
         NA: float,
         wavelength: float,
         refractive_index_medium: float,
         include_aberration: bool = True,   
-        defocus: Union[float, ArrayLike[float]] = 0,
+        defocus: float | ArrayLike[float] = 0,
         **kwargs: Dict[str, Any],
     ):
         """Calculates the pupil function at different focal points.
@@ -787,7 +787,7 @@ def _pupil(
         return pupil_functions
 
     def _pad_volume(
-        self:   'Optics',
+        self: Optics,
         volume: ArrayLike[complex],
         limits: ArrayLike[int] = None,
         padding: ArrayLike[int] = None,
@@ -884,7 +884,7 @@ def _pad_volume(
         return new_volume, new_limits
 
     def __call__(
-        self:  'Optics',
+        self: Optics,
         sample: Feature,
         **kwargs: Dict[str, Any],
     ) -> Microscope:
@@ -915,7 +915,16 @@ def __call__(
         True
 
         """
-        
+        from deeptrack.scatterers import MieScatterer # Temporary place for this import.
+
+        if isinstance(self, (Darkfield, ISCAT, Holography)) and not isinstance(sample, MieScatterer):
+            warnings.warn(
+                f"{type(self).__name__} optics must be used with Mie scatterers "
+                f"to produce a {type(self).__name__} image. "
+                f"Got sample of type {type(sample).__name__}.",
+                UserWarning
+            )
+
         return Microscope(sample, self, **kwargs)
 
     # def _no_wrap_format_input(self, *args, **kwargs) -> list:
@@ -1013,7 +1022,7 @@ class Fluorescence(Optics):
     __gpu_compatible__ = True
 
     def get(
-        self:  'Fluorescence', 
+        self:  Fluorescence, 
         illuminated_volume: ArrayLike[complex], 
         limits: ArrayLike[int], 
         **kwargs: Dict[str, Any]
@@ -1246,7 +1255,7 @@ class Brightfield(Optics):
     )
 
     def get(
-        self:  'Brightfield',
+        self: Brightfield,
         illuminated_volume: ArrayLike[complex],
         limits: ArrayLike[int],
         fields: ArrayLike[complex],
@@ -1504,7 +1513,7 @@ class ISCAT(Brightfield):
     """
 
     def __init__(
-        self:  'ISCAT',
+        self:  ISCAT,
         illumination_angle: float = np.pi,
         amp_factor: float = 1, 
         **kwargs: Dict[str, Any],
@@ -1592,7 +1601,7 @@ class Darkfield(Brightfield):
     """
 
     def __init__(
-        self: 'Darkfield', 
+        self: Darkfield, 
         illumination_angle: float = np.pi/2, 
         **kwargs: Dict[str, Any]
     ) -> None:
@@ -1613,7 +1622,7 @@ def __init__(
 
     #Retrieve get as super
     def get(
-        self: 'Darkfield',
+        self: Darkfield,
         illuminated_volume: ArrayLike[complex],
         limits: ArrayLike[int],
         fields: ArrayLike[complex],
@@ -1693,7 +1702,7 @@ class IlluminationGradient(Feature):
     """
 
     def __init__(
-        self: 'IlluminationGradient',
+        self: IlluminationGradient,
         gradient: PropertyLike[ArrayLike[float]] = (0, 0),
         constant: PropertyLike[float] = 0,
         vmin: PropertyLike[float] = 0,
@@ -1725,7 +1734,7 @@ def __init__(
         )
 
     def get(
-        self: 'IlluminationGradient',
+        self: IlluminationGradient,
         image: ArrayLike[complex],
         gradient: ArrayLike[float],
         constant: float,
@@ -1787,7 +1796,7 @@ def get(
 
 
 def _get_position(
-    image:  Image,
+    image: Image,
     mode: str = "corner",
     return_z: bool = False,
 ) -> np.ndarray:
@@ -2033,4 +2042,4 @@ def _create_volume(
             int(within_volume_position[2]) : 
             int(within_volume_position[2] + shape[2]),
         ] += scatterer
-    return volume, limits
+    return volume, limits