ivis.utils.dutils

Utility Functions for IViS Imaging

This module provides a collection of utility functions used in IViS for radio interferometric reconstruction, model fitting, and image-domain operations.

It includes tools for:

  • WCS construction and reprojection using astropy.wcs

  • Edge apodization (cosine taper) for windowing

  • Construction of Laplacian kernels for regularization

  • Synthetic Gaussian beam generation and injection

  • Coordinate grid generation for PyTorch-based warping

  • Elliptical Gaussian fitting for beam or source characterization

Functions

  • wcs2D: Build a 2D WCS object from a FITS header.

  • apodize: Create a cosine taper for edge apodization.

  • ROHSA_kernel: Return a discrete Laplacian kernel used in ROHSA.

  • laplacian: Create a Laplacian kernel padded into a full-size map.

  • ROHSA_bounds: Generate lower and upper parameter bounds.

  • gauss_beam: Generate a normalized 2D Gaussian kernel.

  • get_grid: Generate a sampling grid for torch.nn.functional.grid_sample.

  • format_input_tensor: Reshape tensors for compatibility with PyTorch ops.

  • insert_elliptical_gaussian_source: Inject an elliptical Gaussian model into an image.

  • fit_elliptical_gaussian: Fit an elliptical Gaussian and visualize the result.

Dependencies

  • numpy

  • torch

  • matplotlib

  • astropy

Author

Antoine Marchal, 2024–2025

Functions

ROHSA_bounds(data_shape, lb_amp, ub_amp)

Create lower and upper bounds arrays for ROHSA optimization.

ROHSA_kernel()

Return a Laplacian-like kernel used in ROHSA.

apodize(radius, shape)

from JF Robitaille package.

downsample_grid(grid, factor)

Downsample uv-grid array with trailing complex axis (...,2).

downsample_hdr(hdr, factor)

Return a copy of FITS-like header with updated NAXIS and CDELT.

downsample_pb(pb, factor)

Downsample primary beam array (real, 2D/3D) with bilinear interpolation.

fit_elliptical_gaussian(cutout[, ...])

Fit elliptical Gaussian to image cutout and return flux, Bmaj, Bmin in arcsec.

format_input_tensor(input_tensor)

Format a 2D or 3D input tensor into a 4D tensor for grid sampling.

gauss_beam(sigma, shape[, FWHM])

Generate a circular symmetric 2D Gaussian kernel.

get_device([spec])

get_grid(shape_input_tensor, wcs_in, ...)

Create a normalized sampling grid for spatial reprojecting in PyTorch.

gpu_mem_str(dev)

Return a formatted string describing CUDA memory usage for a device.

insert_elliptical_gaussian_source(shape, ...)

Generate a sky model with an elliptical Gaussian source.

laplacian(shape)

Construct a 2D Laplacian kernel map for convolution in Fourier space.

wcs2D(hdr)

Construct a 2D WCS object from a FITS header.
ivis.utils.dutils.ROHSA_bounds(data_shape, lb_amp, ub_amp)[source]

Create lower and upper bounds arrays for ROHSA optimization.

Parameters:

  • data_shape (tuple) – Shape of the model parameter array.

  • lb_amp (float) – Lower bound for amplitude.

  • ub_amp (float) – Upper bound for amplitude.

Returns:

bounds – Array of shape (N, 2), with N = np.prod(data_shape), where each row is (lower, upper).

Return type:

ndarray

ivis.utils.dutils.ROHSA_kernel()[source]

Return a Laplacian-like kernel used in ROHSA.

Returns:

kernel – 3x3 Laplacian kernel normalized by 1/4.

Return type:

ndarray

ivis.utils.dutils.apodize(radius, shape)[source]

from JF Robitaille package. Create edges apodization tapper

Parameters:

  • nx (integers)

  • ny (integers)

  • tapper (size of the)

  • radius (float)

  • 0. (radius must be lower than 1 and greater than)

Returns:

  • tapper (numpy array ready to multiply on your image)

  • to apodize edges

ivis.utils.dutils.downsample_grid(grid, factor)[source]

Downsample uv-grid array with trailing complex axis (…,2).

Return type:

ndarray

ivis.utils.dutils.downsample_hdr(hdr, factor)[source]

Return a copy of FITS-like header with updated NAXIS and CDELT.

ivis.utils.dutils.downsample_pb(pb, factor)[source]

Downsample primary beam array (real, 2D/3D) with bilinear interpolation.

Return type:

ndarray

ivis.utils.dutils.fit_elliptical_gaussian(cutout, pixel_scale_arcsec=1.0)[source]

Fit elliptical Gaussian to image cutout and return flux, Bmaj, Bmin in arcsec.

Parameters:

  • cutout (2D ndarray) – Image array containing a single source, in units of Jy/arcsec^2.

  • pixel_scale_arcsec (float) – Pixel size in arcsec/pixel.

Returns:

  • flux (float) – Integrated flux in Jy.

  • Bmaj (float) – FWHM of major axis in arcsec.

  • Bmin (float) – FWHM of minor axis in arcsec.

  • theta (float) – Position angle in degrees (CCW from +x).

ivis.utils.dutils.format_input_tensor(input_tensor)[source]

Format a 2D or 3D input tensor into a 4D tensor for grid sampling.

Parameters:

input_tensor (torch.Tensor) – Tensor of shape (H, W) or (C, H, W).

Returns:

input_tensor_reshape – Tensor of shape (1, C, H, W).

Return type:

torch.Tensor

ivis.utils.dutils.gauss_beam(sigma, shape, FWHM=False)[source]

Generate a circular symmetric 2D Gaussian kernel.

Parameters:

  • sigma (float) – Standard deviation of the Gaussian in pixels (or FWHM if FWHM=True).

  • shape (tuple) – Shape of the output map (ny, nx).

  • FWHM (bool, optional) – If True, sigma is interpreted as FWHM. Default is False.

Returns:

gauss – 2D normalized Gaussian array.

Return type:

ndarray

ivis.utils.dutils.get_device(spec='auto')[source]
Return type:

device

Resolve a compute device from a flexible spec:

  • “auto” -> cuda:0 if available; else mps; else cpu

  • “cpu” -> cpu

  • “cuda” -> cuda:0 (if available)

  • “cuda:i” -> cuda:i if available

  • “mps” -> Apple MPS if available

  • int i -> cuda:i if available; else cpu

  • torch.device -> returned as-is

ivis.utils.dutils.get_grid(shape_input_tensor, wcs_in, wcs_out, shape_out)[source]

Create a normalized sampling grid for spatial reprojecting in PyTorch.

Parameters:

  • shape_input_tensor (tuple) – Shape of the input tensor: (B, C, H_in, W_in).

  • wcs_in (astropy.wcs.WCS) – WCS of the input image.

  • wcs_out (astropy.wcs.WCS) – Target WCS for output grid.

  • shape_out (tuple) – Shape of the output image (H_out, W_out).

Returns:

grid – Grid of shape (1, H_out, W_out, 2) normalized to [-1, 1].

Return type:

torch.Tensor

ivis.utils.dutils.gpu_mem_str(dev)[source]

Return a formatted string describing CUDA memory usage for a device. Returns empty string if dev is not a CUDA device.

Return type:

str

ivis.utils.dutils.insert_elliptical_gaussian_source(shape, cell_size, flux_jy=1.0, fwhm_maj_arcsec=15.0, fwhm_min_arcsec=7.5, pa_deg=0.0, center=None)[source]

Generate a sky model with an elliptical Gaussian source.

Parameters:

  • shape (tuple) – Output image shape (ny, nx).

  • cell_size (float) – Pixel size in arcsec.

  • flux_jy (float, optional) – Total integrated flux of the source in Jy. Default is 1.0.

  • fwhm_maj_arcsec (float, optional) – FWHM of the major axis in arcsec. Default is 15.0.

  • fwhm_min_arcsec (float, optional) – FWHM of the minor axis in arcsec. Default is 7.5.

  • pa_deg (float, optional) – Position angle in degrees (counter-clockwise from x-axis). Default is 0.0.

  • center (tuple, optional) – Pixel coordinates of the source center (y, x). Default is center of image.

Returns:

sky_model – 2D image array (float32) in units of Jy/pixel.

Return type:

ndarray

ivis.utils.dutils.laplacian(shape)[source]

Construct a 2D Laplacian kernel map for convolution in Fourier space.

Parameters:

shape (tuple) – Shape of the output Laplacian map (ny, nx).

Returns:

kernel_map – Laplacian kernel zero-padded in a map of the given shape.

Return type:

ndarray

ivis.utils.dutils.wcs2D(hdr)[source]

Construct a 2D WCS object from a FITS header.

Parameters:

hdr (dict-like) – FITS header containing WCS keywords.

Returns:

w – 2D WCS object.

Return type:

astropy.wcs.WCS