:py:mod:`pytomography.transforms`
=================================

.. py:module:: pytomography.transforms

.. autoapi-nested-parse::

   This module contains transforms; operators that map within the same vector space; such operators are used to build the system matrix. For example, the ``SPECTAttenuationTransform`` is an operator :math:`A:\mathbb{U} \to \mathbb{U}` which adjusts each voxel in an image based on the probability of it being attenuated before it reaches a detector at the :math:`+x` axis. As another example, the ``CutOffTransform`` is an operator :math:`B:\mathbb{V} \to \mathbb{V}` which sets all pixels in image space equal to zero which exist beyond the detector boundaries. Since operators are often used in reconstruction algorithms, their transpose also must be implemented



Subpackages
-----------
.. toctree::
   :titlesonly:
   :maxdepth: 3

   PET/index.rst
   SPECT/index.rst


Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   transform/index.rst


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

Classes
~~~~~~~

.. autoapisummary::

   pytomography.transforms.Transform
   pytomography.transforms.SPECTAttenuationTransform
   pytomography.transforms.SPECTPSFTransform
   pytomography.transforms.CutOffTransform
   pytomography.transforms.PETAttenuationTransform
   pytomography.transforms.PETPSFTransform




.. py:class:: Transform

   The parent class for all transforms used in reconstruction (obj2obj, im2im, obj2im). Subclasses must implement the ``__call__`` method.

   :param device: Pytorch device used for computation
   :type device: str

   .. py:method:: configure(object_meta, image_meta)

      Configures the transform to the object/image metadata. This is done after creating the network so that it can be adjusted to the system matrix.

      :param object_meta: Object metadata.
      :type object_meta: ObjectMeta
      :param image_meta: Image metadata.
      :type image_meta: ImageMeta


   .. py:method:: forward(x)
      :abstractmethod:

      Abstract method; must be implemented in subclasses to apply a correction to an object/image and return it



   .. py:method:: backward(x)
      :abstractmethod:

      Abstract method; must be implemented in subclasses to apply a correction to an object/image and return it




.. py:class:: SPECTAttenuationTransform(CT)

   Bases: :py:obj:`pytomography.transforms.Transform`

   obj2obj transform used to model the effects of attenuation in SPECT.

   :param CT: Tensor of size [batch_size, Lx, Ly, Lz] corresponding to the attenuation coefficient in :math:`{\text{cm}^{-1}}` at the photon energy corresponding to the particular scan
   :type CT: torch.tensor

   .. py:method:: forward(object_i, ang_idx)

      Forward projection :math:`A:\mathbb{U} \to \mathbb{U}` of attenuation correction

      :param object_i: Tensor of size [batch_size, Lx, Ly, Lz] being projected along ``axis=1``.
      :type object_i: torch.tensor
      :param ang_idx: The projection indices: used to find the corresponding angle in image space corresponding to each projection angle in ``object_i``.
      :type ang_idx: torch.Tensor

      :returns: Tensor of size [batch_size, Lx, Ly, Lz] such that projection of this tensor along the first axis corresponds to an attenuation corrected projection.
      :rtype: torch.tensor


   .. py:method:: backward(object_i, ang_idx, norm_constant = None)

      Back projection :math:`A^T:\mathbb{U} \to \mathbb{U}` of attenuation correction. Since the matrix is diagonal, the implementation is the same as forward projection. The only difference is the optional normalization parameter.

      :param object_i: Tensor of size [batch_size, Lx, Ly, Lz] being projected along ``axis=1``.
      :type object_i: torch.tensor
      :param ang_idx: The projection indices: used to find the corresponding angle in image space corresponding to each projection angle in ``object_i``.
      :type ang_idx: torch.Tensor
      :param norm_constant: A tensor used to normalize the output during back projection. Defaults to None.
      :type norm_constant: torch.tensor, optional

      :returns: Tensor of size [batch_size, Lx, Ly, Lz] such that projection of this tensor along the first axis corresponds to an attenuation corrected projection.
      :rtype: torch.tensor



.. py:class:: SPECTPSFTransform(psf_meta)

   Bases: :py:obj:`pytomography.transforms.Transform`

   obj2obj transform used to model the effects of PSF blurring in SPECT. The smoothing kernel used to apply PSF modeling uses a Gaussian kernel with width :math:`\sigma` dependent on the distance of the point to the detector; that information is specified in the ``PSFMeta`` parameter.

   :param psf_meta: Metadata corresponding to the parameters of PSF blurring
   :type psf_meta: PSFMeta

   .. py:method:: configure(object_meta, image_meta)

      Function used to initalize the transform using corresponding object and image metadata

      :param object_meta: Object metadata.
      :type object_meta: ObjectMeta
      :param image_meta: Image metadata.
      :type image_meta: ImageMeta


   .. py:method:: compute_kernel_size(radius, axis)

      Function used to compute the kernel size used for PSF blurring. In particular, uses the ``min_sigmas`` attribute of ``PSFMeta`` to determine what the kernel size should be such that the kernel encompasses at least ``min_sigmas`` at all points in the object.

      :returns: The corresponding kernel size used for PSF blurring.
      :rtype: int


   .. py:method:: get_sigma(radius)

      Uses PSF Meta data information to get blurring :math:`\sigma` as a function of distance from detector.

      :param radius: The distance from the detector.
      :type radius: float

      :returns: An array of length Lx corresponding to blurring at each point along the 1st axis in object space
      :rtype: array


   .. py:method:: apply_psf(object, ang_idx)


   .. py:method:: forward(object_i, ang_idx)

      Applies the PSF transform :math:`A:\mathbb{U} \to \mathbb{U}` for the situation where an object is being detector by a detector at the :math:`+x` axis.

      :param object_i: Tensor of size [batch_size, Lx, Ly, Lz] being projected along its first axis
      :type object_i: torch.tensor
      :param ang_idx: The projection indices: used to find the corresponding angle in image space corresponding to each projection angle in ``object_i``.
      :type ang_idx: int

      :returns: Tensor of size [batch_size, Lx, Ly, Lz] such that projection of this tensor along the first axis corresponds to n PSF corrected projection.
      :rtype: torch.tensor


   .. py:method:: backward(object_i, ang_idx, norm_constant = None)

      Applies the transpose of the PSF transform :math:`A^T:\mathbb{U} \to \mathbb{U}` for the situation where an object is being detector by a detector at the :math:`+x` axis. Since the PSF transform is a symmetric matrix, its implemtation is the same as the ``forward`` method.

      :param object_i: Tensor of size [batch_size, Lx, Ly, Lz] being projected along its first axis
      :type object_i: torch.tensor
      :param ang_idx: The projection indices: used to find the corresponding angle in image space corresponding to each projection angle in ``object_i``.
      :type ang_idx: int
      :param norm_constant: A tensor used to normalize the output during back projection. Defaults to None.
      :type norm_constant: torch.tensor, optional

      :returns: Tensor of size [batch_size, Lx, Ly, Lz] such that projection of this tensor along the first axis corresponds to n PSF corrected projection.
      :rtype: torch.tensor



.. py:class:: CutOffTransform(image)

   Bases: :py:obj:`pytomography.transforms.Transform`

   im2im transformation used to set pixel values equal to zero at the first and last few z slices. This is often required when reconstructing DICOM data due to the finite field of view of the projection data, where additional axial slices are included on the top and bottom, with zero measured detection events. This transform is included in the system matrix, to model the sharp cutoff at the finite FOV.

   :param image: Measured image data.
   :type image: torch.tensor

   .. py:method:: forward(image)

      Forward projection :math:`B:\mathbb{V} \to \mathbb{V}` of the cutoff transform.

      :param image: Tensor of size [batch_size, Ltheta, Lr, Lz] which transform is appplied to
      :type image: torch.Tensor

      :returns: Original image, but with certain z-slices equal to zero.
      :rtype: torch.tensor


   .. py:method:: backward(image, norm_constant = None)

      Back projection :math:`B^T:\mathbb{V} \to \mathbb{V}` of the cutoff transform. Since this is a diagonal matrix, the implementation is the same as forward projection, but with the optional `norm_constant` argument.

      :param image: Tensor of size [batch_size, Ltheta, Lr, Lz] which transform is appplied to
      :type image: torch.Tensor
      :param norm_constant: A tensor used to normalize the output during back projection. Defaults to None.
      :type norm_constant: torch.Tensor | None, optional

      :returns: Original image, but with certain z-slices equal to zero.
      :rtype: torch.tensor



.. py:class:: PETAttenuationTransform(CT)

   Bases: :py:obj:`pytomography.transforms.Transform`

   im2im mapping used to model the effects of attenuation in PET.

   :param CT: Tensor of size [batch_size, Lx, Ly, Lz] corresponding to the attenuation coefficient in :math:`{\text{cm}^{-1}}` at a photon energy of 511keV.
   :type CT: torch.tensor
   :param device: Pytorch device used for computation. If None, uses the default device `pytomography.device` Defaults to None.
   :type device: str, optional

   .. py:method:: configure(object_meta, image_meta)

      Function used to initalize the transform using corresponding object and image metadata

      :param object_meta: Object metadata.
      :type object_meta: ObjectMeta
      :param image_meta: Image metadata.
      :type image_meta: ImageMeta


   .. py:method:: forward(image)

      Applies forward projection of attenuation modeling :math:`B:\mathbb{V} \to \mathbb{V}` to a 2D PET image.

      :param image: Tensor of size [batch_size, Ltheta, Lr, Lz] which transform is appplied to
      :type image: torch.Tensor

      :returns: Tensor of size [batch_size, Ltheta, Lr, Lz]  corresponding to attenuation-corrected image.
      :rtype: torch.Tensor


   .. py:method:: backward(image, norm_constant = None)

      Applies back projection of attenuation modeling :math:`B^T:\mathbb{V} \to \mathbb{V}` to a 2D PET image. Since the matrix is diagonal, its the ``backward`` implementation is identical to the ``forward`` implementation; the only difference is the optional ``norm_constant`` which is needed if one wants to normalize the back projection.

      :param image: Tensor of size [batch_size, Ltheta, Lr, Lz] which transform is appplied to
      :type image: torch.Tensor
      :param norm_constant: A tensor used to normalize the output during back projection. Defaults to None.
      :type norm_constant: torch.Tensor | None, optional

      :returns: Tensor of size [batch_size, Ltheta, Lr, Lz]  corresponding to attenuation-corrected image.
      :rtype: torch.tensor



.. py:class:: PETPSFTransform(kerns)

   Bases: :py:obj:`pytomography.transforms.Transform`

   im2im transform used to model the effects of PSF blurring in PET. The smoothing kernel is assumed to be independent of :math:`\theta` and :math:`z`, but is dependent on :math:`r`.

   :param kerns: A sequence of PSF kernels applied to the Lr dimension of the image with shape [batch_size, Lr, Ltheta, Lz]
   :type kerns: Sequence[callable]

   .. py:method:: configure(object_meta, image_meta)

      Function used to initalize the transform using corresponding object and image metadata

      :param object_meta: Object metadata.
      :type object_meta: ObjectMeta
      :param image_meta: Image metadata.
      :type image_meta: ImageMeta


   .. py:method:: construct_matrix()

      Constructs the matrix used to apply PSF blurring.



   .. py:method:: forward(image)

      Applies the forward projection of PSF modeling :math:`B:\mathbb{V} \to \mathbb{V}` to a PET image.

      :param image: Tensor of size [batch_size, Ltheta, Lr, Lz] corresponding to the image
      :type image: torch.tensor]

      :returns: Tensor of size [batch_size, Ltheta, Lr, Lz] corresponding to the PSF corrected image.
      :rtype: torch.tensor


   .. py:method:: backward(image, norm_constant = None)

      Applies the back projection of PSF modeling :math:`B^T:\mathbb{V} \to \mathbb{V}` to a PET image.

      :param image: Tensor of size [batch_size, Ltheta, Lr, Lz] corresponding to the image
                    norm_constant (torch.tensor, optional): A tensor used to normalize the output during back projection. Defaults to None.
      :type image: torch.tensor]

      :returns: Tensor of size [batch_size, Ltheta, Lr, Lz] corresponding to the PSF corrected image.
      :rtype: torch.tensor



