artist.flux
===========

.. py:module:: artist.flux


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/artist/flux/bitmap/index


Functions
---------

.. autoapisummary::

   artist.flux.crop_flux_distributions_around_center
   artist.flux.get_center_of_mass
   artist.flux.trapezoid_distribution


Package Contents
----------------

.. py:function:: crop_flux_distributions_around_center(flux_distributions: torch.Tensor, solar_tower: artist.field.solar_tower.SolarTower, target_area_indices: torch.Tensor, crop_width: float = constants.utis_crop_width, crop_height: float = constants.utis_crop_height, device: torch.device | None = None) -> torch.Tensor

   Crop a centered rectangular region from grayscale intensity images based on physical dimensions.

   This function identifies the center of mass in each image and then crops a region centered around this point
   with the specified physical width and height (in meters). The cropping is applied via affine transformation,
   which accounts for the desired crop size relative to the target's physical plane dimensions.

   Parameters
   ----------
   flux_distributions : torch.Tensor
       Flux density bitmaps, one per heliostat.
       Shape is ``[number_of_bitmaps, bitmap_height, bitmap_width]``.
   solar_tower : SolarTower
       Solar tower containing the physical target area dimensions.
   target_area_indices : torch.Tensor
       Global target area index for each bitmap (planar indices first, cylindrical second).
       Shape is ``[number_of_bitmaps]``.
   crop_width : float
       Desired width of the cropped region in meters (default is ``constants.utis_crop_width``).
   crop_height : float
       Desired height of the cropped region in meters (default is ``constants.utis_crop_height``).
   device : torch.device | None
       The device on which to perform computations or load tensors and models (default is None).
       If None, ``ARTIST`` will automatically select the most appropriate
       device (CUDA or CPU) based on availability and OS.

   Returns
   -------
   torch.Tensor
       Cropped and centered image regions.
       Shape is ``[number_of_bitmaps, bitmap_height, bitmap_width]``.


.. py:function:: get_center_of_mass(bitmaps: torch.Tensor, device: torch.device | None = None) -> torch.Tensor

   Calculate the coordinates of the flux density center of mass.

   Bitmaps and the resolution are conceptually defined as: [W, H] # width, height
   Tensor memory layout follows PyTorch convention: [H, W] # height, width

   First determine the indices of the bitmap center of mass.
   Next determine the position (coordinates) of the center of mass on the target.

   Returns (0.0, 0.0) for empty fluxes.

   Parameters
   ----------
   bitmaps : torch.Tensor
       Flux densities in form of bitmaps.
       Shape is ``[number_of_active_heliostats, bitmap_resolution_e, bitmap_resolution_u]``.
   device : torch.device | None
       The device on which to perform computations or load tensors and models (default is None).
       If None, ``ARTIST`` will automatically select the most appropriate
       device (CUDA or CPU) based on availability and OS.

   Returns
   -------
   torch.Tensor
       Bitmap coordinates of the flux density centers of mass (e pixel, u pixel).
       Shape is ``[number_of_active_heliostats, 2]``.


.. py:function:: trapezoid_distribution(total_width: int, slope_width: int, plateau_width: int, device: torch.device | None = None) -> torch.Tensor

   Create a one-dimensional trapezoid distribution.

   If the total width is less than ``2 * slope_width + plateau_width``, the slope is cut off.
   If the total width is greater than ``2 * slope_width + plateau_width``, the trapezoid is
   padded with zeros on both sides.

   Parameters
   ----------
   total_width : int
       The total width of the trapezoid. Must be > 0.
   slope_width : int
       The width of the slope of the trapezoid.
   plateau_width : int
       The width of the plateau.
   device : torch.device | None
       The device on which to perform computations or load tensors and models (default is None).
       If None, ``ARTIST`` will automatically select the most appropriate
       device (CUDA or CPU) based on availability and OS.

   Returns
   -------
   torch.Tensor
       The one dimensional trapezoid distribution.
       Shape is ``[total_width]``.