synthesizer.imaging.image_collection

Defintions for collections of generic images.

This module contains the definition for a generic ImageCollection class. This provides the common functionality between particle and parametric imaging. The user should not use this class directly, but rather use the particle.imaging.Images and parametric.imaging.Images classes.

Example usage:

# Create an image collection
img_coll = ImageCollection(resolution=0.1 * unyt.arcsec, npix=100)

# Get histograms of the particle distribution
img_coll.get_imgs_hist(photometry, coordinates)

# Get smoothed images of the particle distribution
img_coll.get_imgs_smoothed(
    photometry,
    coordinates,
    smoothing_lengths,
    kernel,
    kernel_threshold,
)

# Get smoothed images of a parametric distribution
img_coll.get_imgs_smoothed(
    photometry,
    density_grid=density_grid,
)

# Apply PSFs to the images
img_coll.apply_psfs(psfs)

# Apply noise to the images
img_coll.apply_noise_from_stds(noise_stds)

# Plot the images
img_coll.plot_images()

# Make an RGB image
img_coll.make_rgb_image(rgb_filters, weights)

Classes

class synthesizer.imaging.image_collection.ImageCollection(resolution, fov=None, npix=None, imgs=None)[source]

A collection of Image objects.

This contains all the generic methods for creating and manipulating images. In addition to generating images it can also apply PSFs and noise.

Both parametric and particle based imaging uses this class.

resolution

The size of a pixel.

Type:

unyt_quantity

fov

The width of the image.

Type:

unyt_quantity/tuple, unyt_quantity

npix

The number of pixels in the image.

Type:

int/tuple, int

imgs

A dictionary of images.

Type:

dict

noise_maps

A dictionary of noise maps associated to imgs.

Type:

dict

weight_maps

A dictionary of weight maps associated to imgs.

Type:

dict

filter_codes

A list of the filter codes of the images.

Type:

list

rgb_img

The RGB image array.

Type:

np.ndarray

apply_noise_arrays(noise_arrs)[source]

Apply an existing noise array to each image.

Parameters:

noise_arrs (dict) – A dictionary with a noise array for each image within the ImageCollection. The key of each noise array must be the filter_code of the image it should be applied to.

Returns:

ImageCollection

A new image collection containing the images with noise applied.

Raises:

InconsistentArguments – If the noise arrays dict is missing arguments an error is raised.

apply_noise_from_snrs(snrs, depths, aperture_radius=None)[source]

Apply noise based on SNRs and depths for each image.

Parameters:

  • snrs (dict) – A dictionary containing the signal to noise ratio for each image within the ImageCollection. The key of each SNR must be the filter_code of the image it should be applied to.

  • depths (dict) – A dictionary containing the depth for each image within the ImageCollection. The key of each dpeth must be the filter_code of the image it should be applied to.

  • aperture_radius (unyt_quantity) – The radius of the aperture in which the SNR and depth is defined. This must have units attached and be in the same system as the images resolution (e.g. cartesian or angular). If not set a point source depth and SNR is assumed.

Returns:

ImageCollection

A new image collection containing the images with noise applied.

Raises:

InconsistentArguments – If a snr or depth for an image is missing an error is raised.

apply_noise_from_stds(noise_stds)[source]

Apply noise based on standard deviations of the noise distribution.

Parameters:

noise_stds (dict) – A dictionary with a standard deviation for each image within the ImageCollection. The key of each standard deviation must be the filter_code of the image it should be applied to.

Returns:

ImageCollection

A new image collection containing the images with noise applied.

Raises:

InconsistentArguments – If a standard deviation for an image is missing an error is raised.

apply_psfs(psfs)[source]

Convolve this ImageCollection’s images with their PSFs.

To more accurately apply the PSF we recommend using a super resolution image. This can be done via the supersample method and then downsampling to the native pixel scale after resampling. However, it is more efficient and robust to start at the super resolution initially and then downsample after the fact.

Parameters:

psfs (dict) – A dictionary with a point spread function for each image within the ImageCollection. The key of each PSF must be the filter_code of the image it should be applied to.

Returns:

ImageCollection

A new image collection containing the images convolved with a PSF.

Raises:

InconsistentArguments – If a dictionary of PSFs is provided that doesn’t match the filters an error is raised.

downsample(factor)[source]

Supersamples all images contained within this instance.

Useful when applying a PSF to get more accurate convolution results.

NOTE: It is more robust to create the initial “standard” image at high resolution and then downsample it after done with the high resolution version.

Parameters:

factor (float) – The factor by which to resample the image, >1 increases resolution, <1 decreases resolution.

Raises:

ValueError – If the incorrect resample function is called an error is raised to ensure the user does not erroneously resample.

get_imgs_hist(photometry, coordinates)[source]

Calculate an image with no smoothing.

Only applicable to particle based imaging.

Parameters:

  • photometry (PhotometryCollection) – A dictionary of photometry for each filter.

  • coordinates (unyt_array, float) – The coordinates of the particles.

get_imgs_smoothed(photometry, coordinates=None, smoothing_lengths=None, kernel=None, kernel_threshold=1, density_grid=None, nthreads=1)[source]

Calculate an images from a smoothed distribution.

In the particle case this smooths each particle’s signal over the SPH kernel defined by their smoothing length. This uses C extensions to calculate the image for each particle efficiently.

In the parametric case the signal is smoothed over a density grid. This density grid is an array defining the weight in each pixel.

Parameters:

  • signal (unyt_array, float) – The signal of each particle to be sorted into pixels.

  • coordinates (unyt_array, float) – The coordinates of the particles. (Only applicable to particle imaging)

  • smoothing_lengths (unyt_array, float) – The smoothing lengths of the particles. (Only applicable to particle imaging)

  • kernel (str) – The array describing the kernel. This is dervied from the kernel_functions module. (Only applicable to particle imaging)

  • kernel_threshold (float) – The threshold for the kernel. Particles with a kernel value below this threshold are included in the image. (Only applicable to particle imaging)

  • density_grid (np.ndarray) – The density grid to be smoothed over. (Only applicable to parametric imaging).

  • nthreads (int) – The number of threads to use when smoothing the image. This only applies to particle imaging.

items()[source]

Enables dict.items() behaviour.

keys()[source]

Enable dict.keys() behaviour.

make_rgb_image(rgb_filters, weights=None, scaling_func=None)[source]

Make an rgb image from the ImageCollection.

The filters in each channel are defined via the rgb_filters dict, with the option of providing weights for each filter.

Parameters:

  • rgb_filters (dict, array_like, str) – A dictionary containing lists of each filter to combine to create the red, green, and blue channels. e.g. { “R”: “Webb/NIRCam.F277W”, “G”: “Webb/NIRCam.F150W”, “B”: “Webb/NIRCam.F090W”, }.

  • weights (dict, array_like, float) – A dictionary of weights for each filter. Defaults to equal weights.

  • scaling_func (function) – A function to scale the image by. This function should take a single array and produce an array of the same shape but scaled in the desired manner. The scaling is done to each channel individually.

Returns:

np.ndarray

The RGB image array.

plot_images(show=False, vmin=None, vmax=None, scaling_func=None, cmap='Greys_r')[source]

Plot all images.

If this image object contains multiple filters each with an image and the filter_code argument is not specified, then all images will be plotted in a grid of images. If only a single image exists within the image object or a filter has been specified via the filter_code argument, then only a single image will be plotted.

Note: When plotting images in multiple filters, if normalisation (vmin, vmax) are not provided then the normalisation will be unique to each filter. If they are provided then then they will be global across all filters.

Parameters:

  • show (bool) – Whether to show the plot or not (Default False).

  • vmin (float) – The minimum value of the normalisation range.

  • vmax (float) – The maximum value of the normalisation range.

  • scaling_func (function) – A function to scale the image by. This function should take a single array and produce an array of the same shape but scaled in the desired manner.

  • cmap (str) – The name of the matplotlib colormap for image plotting. Can be any valid string that can be passed to the cmap argument of imshow. Defaults to “Greys_r”.

Returns:

matplotlib.pyplot.figure

The figure object containing the plot

matplotlib.pyplot.figure.axis

The axis object containing the image.

Raises:

UnknownImageType – If the requested image type has not yet been created and stored in this image object an exception is raised.

plot_rgb_image(show=False, vmin=None, vmax=None)[source]

Plot an RGB image.

Parameters:

  • show (bool) – Whether to show the plot or not (Default False).

  • vmin (float) – The minimum value of the normalisation range.

  • vmax (float) – The maximum value of the normalisation range.

Returns:

matplotlib.pyplot.figure

The figure object containing the plot

matplotlib.pyplot.figure.axis

The axis object containing the image.

np.ndarray

The rgb image array itself.

Raises:

MissingImage – If the RGB image has not yet been created and stored in this image object an exception is raised.

supersample(factor)[source]

Supersample all images contained within this instance.

Useful when applying a PSF to get more accurate convolution results.

NOTE: It is more robust to create the initial “standard” image at high resolution and then downsample it after done with the high resolution version.

Parameters:

factor (float) – The factor by which to resample the image, >1 increases resolution, <1 decreases resolution.

Raises:

ValueError – If the incorrect resample function is called an error is raised to ensure the user does not erroneously resample.

values()[source]

Enable dict.values() behaviour.