Images

Images#

The images module provides the core functionality of MPoL via mpol.images.ImageCube.

class mpol.images.BaseCube(coords: GridCoords, nchan: int = 1, pixel_mapping: Callable[[Tensor], Tensor] | None = None, base_cube: Tensor | None = None)[source]#

A base cube of the same dimensions as the image cube. Designed to use a pixel mapping function \(f_\mathrm{map}\) from the base cube values to the ImageCube domain.

\[I = f_\mathrm{map}(b)\]

The base_cube pixel values are set as PyTorch parameters.

Parameters:

  • coords (mpol.coordinates.GridCoords) – an object instantiated from the GridCoords class, containing information about the image cell_size and npix.

  • nchan (int) – the number of channels in the base cube. Default = 1.

  • pixel_mapping (function) – a PyTorch function mapping the base pixel representation to the cube representation. If None, defaults to torch.nn.Softplus(). Output of the function should be in units of [\(\mathrm{Jy}\,\mathrm{arcsec}^{-2}\)].

  • base_cube (torch.double tensor, optional) – a pre-packed base cube to initialize the model with. If None, assumes torch.zeros. See Image Cube Packing for FFTs for more information on the expectations of the orientation of the input image.

forward() → Tensor[source]#

Calculate the image representation from the base_cube using the pixel mapping

\[I = f_\mathrm{map}(b)\]

Returns : an image cube in units of [\(\mathrm{Jy}\,\mathrm{arcsec}^{-2}\)].

class mpol.images.HannConvCube(nchan: int, requires_grad: bool = False)[source]#

This convolutional layer convolves an input cube by a small 3x3 filter with shape

\[\begin{split}\begin{bmatrix} 0.0625 & 0.1250 & 0.0625 \\ 0.1250 & 0.2500 & 0.1250 \\ 0.0625 & 0.1250 & 0.0625 \\ \end{bmatrix}\end{split}\]

which is the 2D version of the discretely-sampled response function corresponding to a Hann window, i.e., it is two 1D Hann windows multiplied together. This is a convolutional kernel in the image plane, and so effectively acts as apodization by a Hann window function in the Fourier domain. For more information, see the following Wikipedia articles on Window Functions in general and the Hann Window specifically.

The idea is that this layer would help naturally attenuate high spatial frequency artifacts by baking in a natural apodization in the Fourier plane.

Parameters:

  • nchan (int) – number of channels

  • requires_grad (bool) – keep kernel fixed

forward(cube: Tensor) → Tensor[source]#
Parameters:

  • cube (image) – a prepacked

  • cube

  • example (for)

  • ImageCube.forward() (from)

Returns:

the FFT of the image cube, in packed format and of shape (nchan, npix, npix)

Return type:

torch.complex tensor

class mpol.images.GaussConvImage(coords: GridCoords, nchan: int, FWHM_maj: float, FWHM_min: float, Omega: float = 0, requires_grad: bool = False)[source]#

This convolutional layer will convolve the input cube with a 2D Gaussian kernel. The filter is the same for all channels in the input cube. Because the operation is carried out in the image domain, note that it may become computationally prohibitive for large kernel sizes. In that case, mpol.images.GaussConvFourier may be preferred.

Parameters:

  • coords (mpol.coordinates.GridCoords) – an object instantiated from the GridCoords class, containing information about the image cell_size and npix.

  • nchan (int) – the number of channels in the base cube. Default = 1.

  • FWHM_maj (float, units of arcsec) – the FWHH of the Gaussian along the major axis

  • FWHM_min (float, units of arcsec) – the FWHM of the Gaussian along the minor axis

  • Omega (float, degrees) – the rotation of the major axis of the PSF, in degrees East of North. 0 degrees rotation has the major axis aligned in the North-South direction.

  • requires_grad (bool) – Should the kernel parameters be trainable? Most applications will want to use False.

forward(sky_cube: Tensor) → Tensor[source]#
Parameters:

sky_cube (torch.double tensor, of shape (nchan, npix, npix)) – an image cube in sky format (note, not packed).

Returns:

the FFT of the image cube, in sky format and of shape (nchan, npix, npix)

Return type:

torch.complex tensor

class mpol.images.GaussConvFourier(coords: GridCoords, FWHM_maj: float, FWHM_min: float, Omega: float = 0)[source]#

This layer will convolve the input cube with a (potentially non-circular) Gaussian beam, using a Fourier strategy. The size of the beam is set upon initialization of the layer.

Parameters:

  • coords (mpol.coordinates.GridCoords) – an object instantiated from the GridCoords class, containing information about the image cell_size and npix.

  • FWHM_maj (float, units of arcsec) – the FWHH of the Gaussian along the major axis

  • FWHM_min (float, units of arcsec) – the FWHM of the Gaussian along the minor axis

  • Omega (float, degrees) – the rotation of the major axis of the PSF, in degrees East of North. 0 degrees rotation has the major axis aligned in the North-South direction.

forward(packed_cube, thresh=1e-06)[source]#

Convolve a packed_cube image with a 2D Gaussian PSF. Operation is carried out in the Fourier domain using a Gaussian taper.

Parameters:

packed_cube (torch.Tensor type) – shape (nchan, npix, npix) image cube in packed format.

Returns:

The convolved cube in packed format.

Return type:

torch.Tensor

class mpol.images.ImageCube(coords: GridCoords, nchan: int = 1)[source]#

The parameter set is the pixel values of the image cube itself. The pixels are assumed to represent samples of the specific intensity and are given in units of [\(\mathrm{Jy}\,\mathrm{arcsec}^{-2}\)].

All keyword arguments are required unless noted. The passthrough argument is essential for specifying whether the ImageCube object is the set of root parameters (passthrough==False) or if its simply a passthrough layer (pasthrough==True). In either case, ImageCube is essentially an identity layer, since no transformations are applied to the cube tensor. The main purpose of the ImageCube layer is to provide useful functionality around the cube tensor, such as returning a sky_cube representation and providing FITS writing functionality. In the case of passthrough==False, the ImageCube layer also acts as a container for the trainable parameters.

Parameters:

  • coords (mpol.coordinates.GridCoords) – an object instantiated from the GridCoords class, containing information about the image cell_size and npix.

  • nchan (int) – the number of channels in the base cube. Default = 1.

forward(packed_cube: Tensor) → Tensor[source]#

Pass the cube through as an identity operation, storing the value to the internal buffer. After the cube has been passed through, convenience instance attributes like sky_cube and flux will reflect the updated cube.

Parameters:

packed_cube (torch.Tensor of type torch.double) – 3D torch tensor of shape (nchan, npix, npix)) in ‘packed’ format

Returns:

tensor of shape (nchan, npix, npix)), same as cube

Return type:

torch.Tensor

property sky_cube: Tensor#

The image cube arranged as it would appear on the sky.

Returns:

3D image cube of shape (nchan, npix, npix)

Return type:

torch.double

property flux: Tensor#

The spatially-integrated flux of the image. Returns a ‘spectrum’ with the flux in each channel in units of Jy.

Returns:

a 1D tensor of length (nchan)

Return type:

torch.double

to_FITS(fname: str = 'cube.fits', overwrite: bool = False, header_kwargs: dict | None = None) → None[source]#

Export the image cube to a FITS file.

Parameters:

  • fname (str) – the name of the FITS file to export to.

  • overwrite (bool) – if the file already exists, overwrite?

  • header_kwargs (dict) – Extra keyword arguments to write to the FITS header.

Returns:

None

mpol.images.uv_gaussian_taper(coords: GridCoords, FWHM_maj: float, FWHM_min: float, Omega: float) → ndarray[Any, dtype[floating[Any]]][source]#

Compute a packed Gaussian taper in the Fourier domain, to multiply against a packed visibility cube. While similar to mpol.utils.fourier_gaussian_lambda_arcsec(), this routine delivers a visibility-plane taper with maximum amplitude normalized to 1.0.

Parameters:

  • coords (mpol.coordinates.GridCoords) – object indicating image and Fourier grid specifications.

  • FWHM_maj (float, units of arcsec) – the FWHH of the Gaussian along the major axis

  • FWHM_min (float, units of arcsec) – the FWHM of the Gaussian along the minor axis

  • Omega (float, degrees) – the rotation of the major axis of the PSF, in degrees East of North. 0 degrees rotation has the major axis aligned in the East-West direction.

Returns:

The Gaussian taper in packed format.

Return type:

np.ndarray , shape (npix, npix)