synthesizer.imaging.image¶

A module containing the definition of an image.

This module contains the definition of an image.

An image can be generated from particle based data with or without smoothing, and from parametric data with smoothing defined by a morphology derived density grid.

Example Usage:

# Particle based case img = Image(resolution=0.1 * kpc, fov=1.0 * kpc) img.get_img(signal, coordinates * kpc, smoothing_lengths * kpc, kernel)

# Parametric case img = Image(resolution=0.1 * kpc, fov=1.0 * kpc) img.get_img(signal, density_grid)

Classes

class synthesizer.imaging.image.Image(resolution, fov, img=None)[source]¶

A class for generating images.

This class is used to generate images from particle based data with or without smoothing, and from parametric data with smoothing defined by a morphology derived density grid.

This can be used in isolation to generate singular images or generated by an ImageCollection to generate a collection of images in various filters.

resolution¶

The resolution of the image.

Type:: unyt_quantity of float

fov¶

The field of view of the image.

Type:: unyt_quantity of float

npix¶

The number of pixels in the image.

Type:: tuple

arr¶

The array containing the image.

Type:: array_like, float

units¶

The units of the image.

Type:: unyt.Units

noise_arr¶

The noise array added to the image.

Type:: array_like, float

weight_map¶

The weight map derived from the noise array.

Type:: array_like, float

apply_correlated_noise(instrument, filter_code, correct_periodicity=True, rng_seed=None, inplace=False)[source]¶

Apply correlated noise modelled from an instrument noise map.

This requires an instrument with a correlated noise model for the requested filter. The noise template defined by this model will then be used to generate a new noise array with the same spatial correlations as the template, which is then added to the image.

Parameters:

instrument (Instrument) – The instrument whose correlated-noise model for filter_code provides the observed noise template used to model the spatial correlations.
filter_code (str) – The key identifying the noise model to use.
correct_periodicity (bool) – If True a correction factor is applied to compensate for the assumption of periodicity in the DFT. Default is True.
rng_seed (int, optional) – Seed for the random number generator. Providing the same seed reproduces an identical noise realisation.
inplace (bool) – If True, update this image in place and return it. Otherwise return a new Image. Default is False.

Returns:

A new Image with the correlated noise added. The noise_arr and weight_map attributes are populated on the returned object unless inplace=True, in which case the current image is updated and returned.

Return type:

Image

Raises:

MissingArgument – If the instrument has no correlated-noise model for the requested filter.
InconsistentArguments – If the noise model is dimensionless but the image has units.

apply_noise_array(noise_arr)[source]¶

Apply a noise array.

Parameters:

noise_arr (np.ndarray of float) – The noise array to add to the image.

Returns:

Image: The image including the noise array
np.ndarray: The weight map, derived from 1 / std^2

apply_noise_from_snr(snr, depth, aperture_radius=None)[source]¶

Apply noise derived from a SNR and depth.

This can either be for a point source or an aperture if aperture_radius is passed.

This assumes the SNR is defined as SNR = S / sqrt(noise_std)

Parameters:

snr (float) – The signal to noise ratio of the image.
depth (unyt_quantity of float) – The depth of the image, i.e. the minimum signal strength detectable at the given SNR.
aperture_radius (unyt_quantity) – The radius of the aperture. If None then a point source is assumed.

Returns:

Image: The image including the noise array
np.ndarray: The noise array.
np.ndarray: The weight map.

apply_noise_from_std(noise_std)[source]¶

Apply noise derived from a standard deviation.

This creates noise with a normal distribution centred on 0 with the passed standard deviation.

Parameters:

noise_std (float) – The standard deviation of the noise to add to the image.

Returns:

Image: The image including the noise array
np.ndarray: The weight map.

downsample(factor)[source]¶

Downsample the image by a factor.

Useful when returning from a temporarily supersampled image.

Parameters:: factor (float) – The factor by which to resample the image. Values smaller than 1 reduce the image resolution.
Raises:: ValueError – If factor is greater than 1.

generate_img_hist(signal, coordinates, normalisation=None)[source]¶

Calculate an image with no smoothing.

This is only applicable to particle based images and is just a wrapper for numpy.histogram2d.

Parameters:

signal (array_like, float) – The signal to be sorted into the image.
coordinates (unyt_array, float) – The coordinates of the particles.
normalisation (array_like, float) – The normalisation property. This is multiplied by the signal before sorting, then normalised out.

Returns:

A 2D array containing the pixel values sorted into the image. (npix, npix)

Return type:

img (array_like, float)

generate_img_smoothed(signal, coordinates=None, smoothing_lengths=None, kernel=None, kernel_threshold=1, density_grid=None, normalisation=None, nthreads=1)[source]¶

Calculate a smoothed image.

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. Images can optionally be normalised by a secondary property.

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 (array_like, float) – The signal to be sorted into the image.
coordinates (unyt_array, float) – The coordinates of the particles. (particle case only)
smoothing_lengths (unyt_array, float) – The smoothing lengths of the particles. (particle case only)
kernel (np.ndarray or Kernel) – The kernel lookup table, or a Kernel instance to extract the lookup table from. (particle case only)
kernel_threshold (float) – The threshold for the kernel. (particle case only)
density_grid (array_like, float) – The density grid to smooth over. (parametric case only)
normalisation (array_like, float) – The normalisation property to be used for the signal. This is multiplied by the signal before smoothing, then normalised out. (particle case only).
nthreads (int) – The number of threads to use for the C extension. (particle case only)

Returns:

array_like (float):: A 2D array containing particles sorted into an image. (npix[0], npix[1])

Return type:

img

Raises:

InconsistentArguments – If conflicting particle and parametric arguments are passed or any arguments are missing an error is raised.

get_signal_in_aperture(aperture_radius, aperture_cent=None, nthreads=1)[source]¶

Return the sum of the image within an aperture.

This uses fractional pixel coverage to calculate the overlap between the aperture and each pixel.

Parameters:

aperture_radius (unyt_quantity of float) – The radius of the aperture.
aperture_cent (unyt_array, float) – The centre of the aperture (in pixel coordinates, i.e. the centre is [npix/2, npix/2], top left is [0, 0], and bottom right is [npix, npix]). If None then the centre is assumed to be the maximum pixel.
nthreads (int) – The number of threads to use for the calculation. Default is 1.

Returns:

float: The sum of the image within the aperture.

property img¶: The image array with units.

plot_img(show=False, cmap='Greys_r', norm=None, fig=None, ax=None)[source]¶

Plot an image.

Parameters:

show (bool) – Whether to show the plot or not (Default False).
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”.
norm (function) – A normalisation function. This can be custom made or one of matplotlib’s normalisation functions. It must take an array and return the same array after normalisation.
tick_formatter (matplotlib.ticker.FuncFormatter) – An instance of the tick formatter for formatting the colorbar ticks.
fig (matplotlib.pyplot.figure) – The figure object to plot on. If None a new figure is created.
ax (matplotlib.pyplot.figure.axis) – The axis object to plot on. If None a new axis is created.

Returns:

matplotlib.pyplot.figure: The figure object containing the plot
matplotlib.pyplot.figure.axis: The axis object containing the image.

plot_map(show=False, extent=None, cmap='Greys_r', cbar_label=None, norm=None, tick_formatter=None, fig=None, ax=None)[source]¶

Plot a map.

Unlike an image we want a colorbar and axes for a map.

Parameters:

show (bool) – Whether to show the plot or not (Default False).
extent (list) – The extent of the x and y axes.
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”.
cbar_label (str) – The label for the colorbar.
norm (function) – A normalisation function. This can be custom made or one of matplotlib’s normalisation functions. It must take an array and return the same array after normalisation.
tick_formatter (matplotlib.ticker.FuncFormatter) – An instance of the tick formatter for formatting the colorbar ticks.
fig (matplotlib.pyplot.figure) – The figure object to plot on. If None a new figure is created.
ax (matplotlib.pyplot.figure.axis) – The axis object to plot on. If None a new axis is created.

Returns:

matplotlib.pyplot.figure: The figure object containing the plot
matplotlib.pyplot.figure.axis: The axis object containing the image.

plot_unknown_pleasures(contrast=100, target_lines=50, figsize=(8, 8), title='SYNTHESIZER')[source]¶

Plot the image in the style of Unknown Pleasures.

Creates a representation of an image similar in style to Joy Division’s seminal 1979 album Unknown Pleasures.

Borrows some code from this matplotlib examples: https://matplotlib.org/stable/gallery/animation/unchained.html

Parameters:

contrast (float) – The contrast, i.e. the maximum value in the image.
target_lines (int) – The target number of individual lines to use.
figsize (tuple) – The size of the figure to create.
title (str) – The title to add to the image. If None no title is added.

print_ascii()[source]¶: Print an ASCII representation of an image.

resample(factor)[source]¶

Resample the image by factor.

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

property shape¶

Return the shape of the image.

Returns:

tuple: The shape of the image.