diff --git a/optika/vignetting/_vignetting.py b/optika/vignetting/_vignetting.py index 074f9c2..6409146 100644 --- a/optika/vignetting/_vignetting.py +++ b/optika/vignetting/_vignetting.py @@ -23,7 +23,8 @@ class AbstractVignettingModel( ): """ An interface describing an arbitrary vignetting model, which maps scene - coordinates to the fraction of light transmitted by the optical system. + coordinates to the relative illumination of the optical system (the spatial + response normalized to one at the center of the field of view). """ @abc.abstractmethod @@ -32,8 +33,7 @@ def __call__( coordinates: na.AbstractSpectralPositionalVectorArray, ) -> na.AbstractScalar: """ - Compute the fraction of light transmitted for the given scene - coordinates. + Compute the relative illumination for the given scene coordinates. Parameters ---------- @@ -46,7 +46,7 @@ def inverse( coordinates: na.AbstractSpectralPositionalVectorArray, ) -> na.AbstractScalar: r""" - Compute the inverse of the transmission, :math:`1 / T`, the factor + Compute the inverse of the illumination, :math:`1 / I`, the factor which corrects for the vignetting at the given scene coordinates. Parameters @@ -63,10 +63,10 @@ class AbstractInterpolatedVignettingModel( ): """ A vignetting model defined by interpolating between known scene coordinates - and their measured transmission. + and their measured illumination. This class has two main members, :attr:`coordinates_scene` and - :attr:`transmission`, the calibration points between which subclasses + :attr:`illumination`, the calibration points between which subclasses interpolate. """ @@ -79,9 +79,9 @@ def coordinates_scene(self) -> na.AbstractSpectralPositionalVectorArray: @property @abc.abstractmethod - def transmission(self) -> na.AbstractScalar: + def illumination(self) -> na.AbstractScalar: """ - The fraction of light transmitted at each calibration point. + The relative illumination at each calibration point. """ @property @@ -100,14 +100,14 @@ class PolynomialVignettingModel( AbstractInterpolatedVignettingModel, ): """ - A vignetting model which fits a polynomial to the measured transmission at + A vignetting model which fits a polynomial to the measured illumination at known scene coordinates. Examples -------- - Build a vignetting model with a radial transmission falloff fit by a - deliberately underfit (linear) polynomial, then plot the transmission and + Build a vignetting model with a radial illumination falloff fit by a + deliberately underfit (linear) polynomial, then plot the illumination and the fit residual. .. jupyter-execute:: @@ -126,11 +126,11 @@ class PolynomialVignettingModel( num=13, ), ) - transmission = 1 - 0.1 * (scene.position.length / u.deg) ** 2 + illumination = 1 - 0.1 * (scene.position.length / u.deg) ** 2 model = optika.vignetting.PolynomialVignettingModel( coordinates_scene=scene, - transmission=transmission, + illumination=illumination, axis_wavelength="wavelength", axis_field=("field_x", "field_y"), degree=1, @@ -146,8 +146,8 @@ class PolynomialVignettingModel( coordinates_scene: na.AbstractSpectralPositionalVectorArray = dataclasses.MISSING """The wavelength and position of each calibration point in the scene.""" - transmission: na.AbstractScalar = dataclasses.MISSING - """The fraction of light transmitted at each calibration point.""" + illumination: na.AbstractScalar = dataclasses.MISSING + """The relative illumination at each calibration point.""" axis_wavelength: str = dataclasses.MISSING """The logical axis corresponding to changing wavelength.""" @@ -168,11 +168,11 @@ def _axis_scene(self) -> tuple[str, ...]: @functools.cached_property def fit(self) -> na.PolynomialFitFunctionArray: - """The polynomial fit mapping scene coordinates to transmission.""" + """The polynomial fit mapping scene coordinates to illumination.""" scene = self.coordinates_scene return na.PolynomialFitFunctionArray( inputs=scene, - outputs=self.transmission, + outputs=self.illumination, center=scene.mean(self._axis_scene), degree=self.degree, where_polynomial=self.where, @@ -197,7 +197,7 @@ def plot_residual( a separate subplot for each wavelength. The residual is the absolute difference between the calibration - :attr:`transmission` and the transmission predicted by the polynomial + :attr:`illumination` and the illumination predicted by the polynomial fit. Parameters @@ -219,8 +219,8 @@ def plot_residual( :func:`named_arrays.plt.pcolormesh`. """ return self._plot( - abs(self.transmission - self.fit.predictions), - label="transmission residual", + abs(self.illumination - self.fit.predictions), + label="illumination residual", figsize=figsize, cmap=cmap, vmin=vmin, @@ -237,7 +237,7 @@ def plot( **kwargs, ) -> tuple[matplotlib.figure.Figure, na.ScalarArray]: """ - Plot the calibration :attr:`transmission` as a function of field angle, + Plot the calibration :attr:`illumination` as a function of field angle, with a separate subplot for each wavelength. Parameters @@ -247,20 +247,20 @@ def plot( If :obj:`None`, the size is chosen automatically from the number of wavelengths and the aspect ratio of the field of view. cmap - The colormap used to map the transmission to colors. + The colormap used to map the illumination to colors. vmin - The transmission value mapped to the lowest color. + The illumination value mapped to the lowest color. If :obj:`None`, defaults to zero. vmax - The transmission value mapped to the highest color. - If :obj:`None`, defaults to the maximum transmission. + The illumination value mapped to the highest color. + If :obj:`None`, defaults to the maximum illumination. kwargs Additional keyword arguments passed to :func:`named_arrays.plt.pcolormesh`. """ return self._plot( - self.transmission, - label="transmission", + self.illumination, + label="illumination", figsize=figsize, cmap=cmap, vmin=vmin, diff --git a/optika/vignetting/_vignetting_test.py b/optika/vignetting/_vignetting_test.py index d6618db..0692e15 100644 --- a/optika/vignetting/_vignetting_test.py +++ b/optika/vignetting/_vignetting_test.py @@ -20,7 +20,7 @@ def _scene() -> na.SpectralPositionalVectorArray: ) -def _transmission() -> na.AbstractScalar: +def _illumination() -> na.AbstractScalar: return 1 - 0.1 * (_scene().position.length / u.deg) ** 2 @@ -50,11 +50,11 @@ def test_coordinates_scene( ): assert isinstance(a.coordinates_scene, na.AbstractSpectralPositionalVectorArray) - def test_transmission( + def test_illumination( self, a: optika.vignetting.AbstractInterpolatedVignettingModel, ): - assert isinstance(a.transmission, na.AbstractScalar) + assert isinstance(a.illumination, na.AbstractScalar) def test_axis_wavelength( self, @@ -75,7 +75,7 @@ def test_axis_field( argvalues=[ optika.vignetting.PolynomialVignettingModel( coordinates_scene=_scene(), - transmission=_transmission(), + illumination=_illumination(), axis_wavelength="wavelength", axis_field=("field_x", "field_y"), degree=degree,