Huygens MTF

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 with one exception: small features that only simplify access to certain parts of the
 ZOS-API can also be added in patch releases.
 
+## [Unreleased]
+
+### Added
+
+- MTF analysis: `huygens_mtf` (#55)
+
 ## [[1.1.1]](https://github.com/MREYE-LUMC/ZOSPy/releases/tag/v1.1.1) - 2023-09-25
 
 ### Added

scripts/generate_test_reference_data/tests.yaml

@@ -30,6 +30,17 @@ tests:
         frequency: 3
         numberofsteps: 10
         mtftype: Imaginary
+  - model: simple_system
+    analysis: mtf.huygens_mtf
+    file: test_mtf.py
+    test: test_huygens_mtf_returns_correct_result
+    parametrized: [pupil_sampling, image_sampling, image_delta, mtftype, maximum_frequency]
+    parameters:
+      - pupil_sampling: 64x64
+        image_sampling: 64x64
+        image_delta: 0.0
+        mtftype: Modulation
+        maximum_frequency: 150.0
   - model: polarized_system
     analysis: polarization.polarization_pupil_map
     file: test_polarization.py

tests/analyses/test_mtf.py

@@ -1,7 +1,12 @@
 import numpy as np
 import pytest
+from pandas.testing import assert_frame_equal
 
-from zospy.analyses.mtf import fft_through_focus_mtf, fft_through_focus_mtf_fromcfg
+from zospy.analyses.mtf import (
+    fft_through_focus_mtf,
+    fft_through_focus_mtf_fromcfg,
+    huygens_mtf,
+)
 
 _FFT_THROUGH_FOCUS_MTF_MTFTYPE_EXPECTED_RETURN = {
     # The expected return does not match constants.Analysis.Settings.Mtf.MtfTypes for fft_through_focus_mtf
@@ -86,3 +91,38 @@ def test_fft_through_focus_mtf_sets_mtftype_correctly(self, simple_system, mtfty
         )
 
         assert result.Settings["Type"] == _FFT_THROUGH_FOCUS_MTF_MTFTYPE_EXPECTED_RETURN[mtftype]
+
+
+class TestHuygensMTF:
+    def test_can_run_fft_through_focus_mtf(self, simple_system):
+        result = huygens_mtf(simple_system)
+
+        assert result.Data is not None
+
+    def test_to_json(self, simple_system):
+        result = huygens_mtf(simple_system)
+
+        assert result.from_json(result.to_json())
+
+    @pytest.mark.parametrize(
+        "pupil_sampling,image_sampling,image_delta,mtftype,maximum_frequency",
+        [
+            ("64x64", "64x64", 0.0, "Modulation", 150.0),
+            ("32x32", "64x64", 1.0, "Modulation", 450.0),
+            ("128x128", "128x128", 0.0, "Modulation", 314.5),
+            ("32x32", "32x32", 0.0, "Modulation", 150.0),
+        ],
+    )
+    def test_huygens_mtf_returns_correct_result(
+        self, simple_system, pupil_sampling, image_sampling, image_delta, mtftype, maximum_frequency, expected_data
+    ):
+        result = huygens_mtf(
+            simple_system,
+            pupil_sampling=pupil_sampling,
+            image_sampling=image_sampling,
+            image_delta=image_delta,
+            mtftype=mtftype,
+            maximum_frequency=maximum_frequency,
+        )
+
+        assert_frame_equal(result.Data.astype(float), expected_data.Data.astype(float))

zospy/analyses/mtf.py

@@ -237,3 +237,123 @@ def fft_through_focus_mtf_fromcfg(
     )
 
     return analysis.complete(oncomplete, result)
+
+
+def huygens_mtf(
+    oss: OpticStudioSystem,
+    pupil_sampling: str | int = "32x32",
+    image_sampling: str | int = "32x32",
+    image_delta: float = 0.0,
+    wavelength: str | int = "All",
+    field: str | int = "All",
+    mtftype: constants.Analysis.Settings.Mtf.HuygensMtfTypes | str = "Modulation",
+    maximum_frequency: float = 150.0,
+    use_polarization: bool = False,
+    use_dashes: bool = False,
+    oncomplete: OnComplete | str = OnComplete.Close,
+) -> AnalysisResult:
+    """Wrapper around the OpticStudio Huygens MTF.
+
+    For an in depth explanation of the parameters, see the Zemax OpticStudio user manual
+
+    Parameters
+    ----------
+    oss : zospy.core.OpticStudioSystem
+        A ZOSPy OpticStudioSystem instance. Should be sequential.
+    pupil_sampling : str | int
+        The pupil sampling, either string (e.g. '64x64') or int.
+        The integer will be treated as a ZOSAPI Constants integer.
+    image_sampling : str | int
+        The image sampling, either string (e.g., '64x64') or int.
+        The integer will be treated as a ZOSAPI Constants integer.
+    image_delta : float
+        The Image Delta, defaults to 0.0.
+    wavelength : str | int
+        The wavelength to use in the MTF. Either 'All' or an integer specifying the wavelength number.
+    field : str | int
+        The field to use in the MTF. Either 'All' or an integer specifying the field number.
+    mtftype : zospy.constants.Analysis.Settings.Mtf.MtfTypes.Modulation
+        The MTF type (e.g. `Modulation`) that is calculated.
+    maximum_frequency : float
+        The maximum frequency at which the MTF is calculated.
+        Units are either cycles/mm or cycles/mr, depending on system setting).
+        Defaults to 150.0, which is more appropriate when units are set to cycles/mm.
+    use_polarization : bool
+        Use polarization. Defaults to False.
+    use_dashes : bool
+        Use dashes. Defaults to False.
+    oncomplete : OnComplete | str
+        Defines behaviour upon completion of the analysis. Should be one of ['Close', 'Release', 'Sustain']. If 'Close',
+        the analysis will be closed after completion. If 'Release', the analysis will remain open in OpticStudio, but
+        the link with python will be destroyed. If 'Sustain' the analysis will be kept open in OpticStudio and the link
+        with python will be sustained. To enable interaction when oncomplete == 'Sustain', the OpticStudio Analysis
+        instance will be available in the returned AnalysisResult through AnalysisResult.Analysis. Defaults to 'Close'.
+
+    Returns
+    -------
+    AnalysisResult
+        A HuygensMTF analysis result
+    """
+    analysis_type = constants.Analysis.AnalysisIDM.HuygensMtf
+
+    # Create analysis
+    analysis = new_analysis(oss, analysis_type)
+
+    # Apply settings
+    analysis.Settings.PupilSampleSize = getattr(
+        constants.Analysis.SampleSizes, utils.zputils.standardize_sampling(pupil_sampling)
+    )
+    analysis.Settings.ImageSampleSize = getattr(
+        constants.Analysis.SampleSizes, utils.zputils.standardize_sampling(image_sampling)
+    )
+    analysis.Settings.ImageDelta = image_delta
+    analysis.set_wavelength(wavelength)
+    analysis.set_field(field)
+    analysis.Settings.Type = constants.process_constant(constants.Analysis.Settings.Mtf.HuygensMtfTypes, mtftype)
+    analysis.Settings.UsePolarization = use_polarization
+    analysis.Settings.UseDashes = use_dashes
+    analysis.Settings.MaximumFrequency = maximum_frequency
+
+    # Calculate
+    analysis.ApplyAndWaitForCompletion()
+
+    # Get headerdata, metadata and messages
+    headerdata = analysis.get_header_data()
+    metadata = analysis.get_metadata()
+    messages = analysis.get_messages()
+
+    # Get settings
+    settings = pd.Series(name="Settings", dtype=object)
+
+    settings.loc["PupilSampling"] = str(analysis.Settings.PupilSampleSize)
+    settings.loc["ImageSampling"] = str(analysis.Settings.ImageSampleSize)
+    settings.loc["ImageDelta"] = analysis.Settings.ImageDelta
+    settings.loc["Wavelength"] = analysis.get_wavelength()
+    settings.loc["Field"] = analysis.get_field()
+    settings.loc["Type"] = str(analysis.Settings.Type)
+    settings.loc["UsePolarization"] = analysis.Settings.UsePolarization
+    settings.loc["UseDashes"] = analysis.Settings.UseDashes
+    settings.loc["MaximumFrequency"] = analysis.Settings.MaximumFrequency
+
+    # Get data and unpack
+    data = []
+    for ii in range(analysis.Results.NumberOfDataSeries):
+        data.append(utils.zputils.unpack_dataseries(analysis.Results.DataSeries[ii]))
+
+    if not len(data):
+        data = pd.DataFrame()
+    elif len(data) == 1:
+        data = data[0]
+    else:
+        data = pd.concat(data, axis=1)
+
+    result = AnalysisResult(
+        analysistype=str(analysis_type),
+        data=data,
+        settings=settings,
+        metadata=metadata,
+        headerdata=headerdata,
+        messages=messages,
+    )
+
+    return analysis.complete(oncomplete, result)