Merge pull request #70 from QPG-MIT/calibration_changes

Calibration changes

docs/source/api.rst

@@ -65,5 +65,79 @@ The unification of these two categories is stored in:
 
    cameraslms
 
+API Formalism
+=============
+
+Conventions
+~~~~~~~~~~~
+:mod:`slmsuite` follows the ``shape = (h, w)`` and ``vector = (x, y)`` formalism adopted by
+the :mod:`numpy` ecosystem. :mod:`numpy`, :mod:`scipy`, :mod:`matplotlib`, etc generally follow this
+formalism. The ``shape`` and indexing of an array or image always uses the inverted ``(h, w)`` form,
+but other functions such as ``numpy.meshgrid(x, y)`` (default), ``scipy.odr.Data(x, y)``, or
+``matplotlib.pyplot.scatter(x, y)`` use the standard cartesian ``(x, y)`` form that is more familiar
+to users. This is not ideal and causes confusion, but this is the formalism generally
+adopted by the community.
+
+We additionally adopt the convention that
+a list of :math:`N` vectors with dimension :math:`D` is represented with shape
+``(D, N)``. This is so that linear transformations can be done with a direct and easy
+multiplication with a ``(D, D)`` matrix.
+Stacks of :math:`W \times H` images, however,
+are stored with the inverted shape ``(N, H, W)``.
+These conventions are arguably consistent with the chosen ordering.
+
+Bases
+~~~~~
+This package uses a number of spatial bases or coordinate spaces. Some coordinate spaces are
+directly used by the user (most often the camera basis ``"ij"`` used for feedback).
+Other bases are less often used directly, but are important to how holograms are
+optimized under the hood (esp. ``"knm"``, the coordinate space of optimization when
+using discrete Fourier transforms).
+
+.. list-table:: Bases used in :mod:`slmsuite`.
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Basis
+     - Meaning
+   * - ``"kxy"``
+     - Normalized basis of the SLM's :math:`k`-space in normalized units.
+       Centered at ``(kx, ky) = (0, 0)``. This basis is what the SLM projects in angular
+       space (which maps to the camera's image space via the Fourier transform
+       implemented by free space and lens separating the two).
+
+       The edge of Fourier space corresponds to when
+       :math:`|k_x|` or :math:`|k_y|` equal 1.
+       Note that the small angle approximation breaks down in this limit.
+   * - ``"knm"``
+     - Nyquist basis of the SLM's computational :math:`k`-space for a given
+       discrete computational grid of shape ``shape``.
+       Centered at ``(kn, km) = (shape[1]/2, shape[0]/2)``.
+       ``"knm"`` is a discrete version of the continuous ``"kxy"``. This is
+       important because holograms need to be stored in computer memory, a discrete
+       medium with pixels, rather than being purely continuous. For instance, in
+       :class:`SpotHologram`, spots targeting specific continuous angles are rounded to
+       the nearest discrete pixels of ``"knm"`` space in practice
+       (though :class:`CompressedSpotHologram` transcends this limitation).
+       Then, this ``"knm"`` space image is handled as a
+       standard image/array, and operations such as the discrete Fourier transform
+       (instrumental for numerical hologram optimization) can be applied.
+
+       The edge of ``"knm"`` space is bounded by zero and the extent of ``shape``.
+       In ``"kxy"`` space, this edge corresponds to the Nyquist limit of the SLM
+       and is strictly smaller than the full extent of Fourier space. Increasing the
+       ``shape`` of ``"knm"`` space increases the resolution of the grid in Fourier
+       space, as the edge of ``"knm"`` space is fixed by the SLM.
+   * - ``"ij"``
+     - Pixel basis of the camera.
+       Centered at ``(i, j) = (cam.shape[1]/2, cam.shape[0]/2)``.
+       Is in the image space of the camera.
+
+       The bounds of pixel space may be larger or smaller than Fourier or Nyquist space,
+       depending upon the imaging optics that separate the camera and SLM.
+
+See the first tip in :class:`Hologram` to learn more about ``"kxy"`` and ``"knm"``
+space.
+
 .. |slmsuite| replace:: :mod:`slmsuite`
 .. _slmsuite: https://github.com/QPG-MIT/slmsuite