Skip to content

Image: pixelised brightness

A pixel image is one more component of a System, for image reconstruction. Its visibilities are the exact Fourier transform of the pixels.

virgil.models.Image

Bases: _BrightnessImage

Pixelised brightness distribution, for image reconstruction.

Pixel fluxes are softmax(log_brightness) over the pixels in support: positive, summing to one, zero outside. Inside a System it has a flux weight and offset like any component, so unresolved sources stay analytic; visibilities are the exact Fourier transform of the pixels, each a point at its centre. A constant added to log_brightness changes nothing, so fit fixes it (a free array comes back as log of the pixel fluxes); a pixel whose optimum is zero flux can fit far below the rest (-1e3 or lower, set by rounding): read an image from brightness, not from those values.

Parameters:

Name Type Description Default
log_brightness array-like, shape (nrow, ncol), or GaussianField

Log pixel fluxes up to a constant, oriented as render (row 0 North, column 0 East), or an object with evaluate(pixel_scale_mas) such as a GaussianField.

required
pixel_scale_mas float

Pixel size in mas; the image centre, index ((nrow - 1) / 2, (ncol - 1) / 2), is at (dra, ddec).

required
support array-like of bool

Pixels allowed to carry flux, same shape as log_brightness (default all); see circular_support.

None
flux optional

As for any Component.

1.0
dra optional

As for any Component.

1.0
ddec optional

As for any Component.

1.0
rotation_deg float or grid

Position angle (North to East) of the grid's "up" axis (default 0); matching data.uv_grid.rotation_deg gives a much faster exact two-sided matrix transform. "grid" (provisional) follows the data's uv lattice, North up without one, so DISCO data always take the matrix transform. The pixels are the parameters, so with "grid" they mean different skies on data with different lattices (or none), and render and model without data are North up: fit one lattice, or give a number (as starting_image does).

0.0
ft (auto, dft, nufft)

Transform for irregular uv points (default "auto", whichever is faster; see set_ft_defaults).

"auto"
blur_fwhm_mas float

FWHM in mas of a fixed (not fitted) Gaussian blurring kernel in the forward model: the data are compared with the blurred image, so the pixels are the unblurred sky. Default None, recommended; blur for display after the fit (smoothed() gives the blurred pixels). Compounds with CalibrationNuisance.blur_fwhm_mas. Source: MPoL's Gaussian base layer, Czekala et al. (2025), references.

None
smooth_fwhm_mas float

Deprecated alias of blur_fwhm_mas.

required

Examples:

>>> image = Image(np.zeros((32, 32)), pixel_scale_mas=2.0)
>>> envelope = Image.from_model(GaussianDisk(sigma=8.0), 32, 2.0, flux=0.3)

brightness property

Pixel fluxes: positive, unit sum, zero outside support.

eta property

The log-brightness array, evaluated if it is a field.

from_brightness(brightness, pixel_scale_mas, *, floor=1e-06, **kwargs) classmethod

Build an image from non-negative pixel fluxes.

Pixels fainter than floor times the brightest are raised to that level, so that their logarithm is finite. Other keyword arguments (support, flux, dra, ddec, rotation_deg) go to Image.

from_model(model, npix, pixel_scale_mas, **kwargs) classmethod

Pixelise a model, e.g. a parametric fit, as a starting image.

The pixels sample model on an npix x npix grid (rotated by rotation_deg, if given); see from_brightness for the keyword arguments.

virgil.models.LinearImage

Bases: _BrightnessImage

Pixel image whose fitted values are the pixel fluxes themselves.

The free array pixels is the flux of each pixel in support (parametrization="linear", to be kept non-negative by bounds: see bounds) or its square root ("sqrt", flux x**2, unbounded and so usable with any fit method). The total flux is the sum of the pixel fluxes: there is no separate flux to fit (a free flux times free pixel amplitudes is an exact scale degeneracy), and inside a System the component's weight is that sum. The flux field is fixed at 1 and must not be fitted. brightness is the unit-sum image, as for an Image.

Provisional

May change in any 0.4.x release without a deprecation cycle.

The data see the total flux only through a System's weights or, in the radio χ², CalibrationNuisance(..., fit_flux=False) (Σ pixels in Jy). A lone LinearImage elsewhere fixes nothing, so TSV, TV or StarletL1 shrink it towards zero: put it in a System with a fixed-flux component, or use MaxEntropy. diagnose and the ensemble helpers do not cover it yet.

Unlike the softmax of an Image, pixels can reach exactly zero, which the minimiser of TSV, TV, StarletL1 or an unregularised fit needs. The "sqrt" form is the choice for MaxEntropy: it keeps the entropy's interior minimum, and its metric 4 I is that of entropic mirror descent. x = 0 is a stationary point, so start strictly positive.

Regularizers act on fluxes / reference_flux, so their weights keep their meaning and TSV, TV and StarletL1 stay convex in a linear image; the weight drifts by (F / reference_flux)**2 if the fitted flux F moves far from it. Source: SMILI's non-negative linear pixels, Akiyama et al. (2017) (also AJ 153, 159); the "sqrt" form is experimental, with no published source found.

Parameters:

Name Type Description Default
pixels (array - like, shape(nrow, ncol))

Pixel fluxes ("linear", non-negative) or their square roots ("sqrt"), oriented as render (row 0 North, column 0 East).

required
pixel_scale_mas float

Pixel size in mas, as for Image.

required
support optional

As for Image.

None
rotation_deg optional

As for Image.

None
ft optional

As for Image.

None
blur_fwhm_mas optional

As for Image.

None
dra optional

As for any Component.

0.0
ddec optional

As for any Component.

0.0
parametrization (linear, sqrt)

What pixels holds (default "linear").

"linear"
reference_flux float

The fixed flux F0 that regularizers divide by (default: the sum of the starting pixel fluxes).

None

Examples:

>>> image = LinearImage(np.full((8, 8), 0.01), pixel_scale_mas=2.0)
>>> round(float(image.total_flux), 4)
0.64

brightness property

Pixel fluxes divided by the total: unit sum, zero outside support.

fluxes property

Pixel fluxes: non-negative, zero outside support.

total_flux property

The image's flux, the sum of fluxes.

bounds()

(lower, upper) arrays for a bounded optimiser, or None.

Linear pixels have 0 <= flux < inf inside support and (0, 0) outside it; the square-root form needs no bounds.

virgil.models.circular_support(npix, pixel_scale_mas, radius_mas, inner_radius_mas=0.0)

Pixels of an npix x npix image within radius_mas of its centre.

Returns a boolean array for the support of an Image. With inner_radius_mas, pixels closer to the centre than that are left out too: a hole under an analytic star, so that the image cannot pile flux onto it.