magtrack.simulation
===================

.. py:module:: magtrack.simulation

.. autoapi-nested-parse::

   Simulations for generating realistic synthetic images and Z-LUTs of beads.



Functions
---------

.. autoapisummary::

   magtrack.simulation.simulate_beads
   magtrack.simulation.simulate_zlut


Module Contents
---------------

.. py:function:: simulate_beads(xyz_nm, nm_per_px: float = 100.0, size_px: int = 64, radius_nm: float = 1500.0, wavelength_nm: float = 550.0, n_sphere: float = 1.59, n_medium: float = 1.33, absorption_per_nm: float = 0.0, background_level=0.4, contrast_scale=1.0, pad_factor=2.0)

   Simulate brightfield images of spherical beads.

   Generates a 3D stack of normalized brightfield images for beads located at
   the provided coordinates in nanometers. The simulation models refraction and
   absorption through a spherical object, applies a sampling-limited pupil
   defined by the imaging wavelength and medium, and returns images
   cropped to the requested pixel size.

   :param xyz_nm: Nanometer coordinates ``[x_nm, y_nm, z_nm]`` for each bead.
   :type xyz_nm: array_like, shape (n_beads, 3)
   :param nm_per_px: Nanometers per pixel. Defaults to 100.0 nm/px.
   :type nm_per_px: float, optional
   :param size_px: Output image width and height in pixels. Defaults to 64.
   :type size_px: int, optional
   :param radius_nm: Bead radius in nanometers. Defaults to 1500.0 nm.
   :type radius_nm: float, optional
   :param wavelength_nm: Illumination wavelength in nanometers. Defaults to 550.0 nm.
   :type wavelength_nm: float, optional
   :param n_sphere: Refractive index of the bead. Defaults to 1.59.
   :type n_sphere: float, optional
   :param n_medium: Refractive index of the surrounding medium. Defaults to 1.33.
   :type n_medium: float, optional
   :param absorption_per_nm: Absorption coefficient per nanometer. Defaults to 0.0.
   :type absorption_per_nm: float, optional
   :param background_level: Baseline background intensity scaling. Defaults to 0.4.
   :type background_level: float, optional
   :param contrast_scale: Contrast scaling relative to the background. Defaults to 1.0.
   :type contrast_scale: float, optional
   :param pad_factor: Factor for zero-padding the pupil function to reduce edge effects.
                      Defaults to 2.0.
   :type pad_factor: float, optional

   :returns: **stack** -- Normalized simulated bead images with intensities clipped to ``[0, 1]``.
   :rtype: ndarray, shape (size_px, size_px, n_beads)


.. py:function:: simulate_zlut(z_nm, nm_per_px: float = 100.0, size_px: int = 64, oversample: int = 1, **simulate_beads_kwargs)

   Simulate a Z look-up table (Z-LUT) from synthetic bead images.

   This convenience function renders a stack of bead images at the supplied
   axial positions using :func:`simulate_beads`, converts each frame into a
   radial profile via :func:`magtrack.core.radial_profile`, and assembles the
   results into a Z-LUT where the first row stores the z positions.

   :param z_nm: Z coordinates in nanometers for the reference stack.
   :type z_nm: array_like, shape (n_planes,)
   :param nm_per_px: Nanometers per pixel used for the simulation. Defaults to 100.0.
   :type nm_per_px: float, optional
   :param size_px: Width/height in pixels of the simulated frames. Defaults to 64.
   :type size_px: int, optional
   :param oversample: Oversampling factor passed to :func:`magtrack.core.radial_profile`.
                      Defaults to 1.
   :type oversample: int, optional
   :param \*\*simulate_beads_kwargs: Additional keyword arguments forwarded to :func:`simulate_beads` (for
                                     example ``radius_nm`` or ``wavelength_nm``).
   :type \*\*simulate_beads_kwargs: dict, optional

   :returns: **zlut** -- Z look-up table where ``zlut[0, :]`` contains the reference z positions
             and the remaining rows contain the corresponding radial profiles.
   :rtype: ndarray, shape (1 + n_bins, n_planes)