distroi.data.image module#

A module for handling images and their fast Fourier transform (FFT).

Warning

Currently only supports images with an even amount of pixels.

class distroi.data.image.Image(dictionary: dict[str, ndarray | float | int], sp_dep: SpecDep | None = None, padding: tuple[int, int] | None = None)#

Bases: object

Contains information on an image and its FFT.

Contains all attributes in order to fully describe both a regular grid image and its FFT. Note that all these attributes are expected if all class methods are to work. It can easily be generalized to different RT codes by defining a corresponding image reader function analogous to read_image_fft_mcfost. Can handle any amount of pixels in an image, as long as the amount of pixels in each dimension is even.

Parameters:

  • dictionary (dict) – Dictionary containing keys and values representing several instance variables described below. Should include wavelength, pixelscale_x/y, num_pix_x/y, img, and ftot. The other required instance variables (related to the FFT) are set automatically through do_fft.

  • sp_dep (SpecDep, optional) – Optional spectral dependence of the image. This will only be used if this Image is used on its own in methods calculating interferometric observables. If instead multiple Image objects or an SED are passed along as well, this property of the image will be ignored. By default, the spectral dependency will be assumed to be flat in F_lam across wavelengths.

  • padding (tuple of int, optional) – Number of (x, y)-pixels to which an image should be 0-padded before performing the FFT. I.e. padding=(680, 540) will 0-pad an image to 680 and 540 pixels in the x and y dimensions, respectively. If smaller than the number of pixels already in the img array, no padding will be added in the respective dimension. These should both be even numbers!

wavelength#

Image wavelength in micron.

Type:

float

pixelscale_x#

Pixelscale in radian in x (East-West) direction.

Type:

float

pixelscale_y#

Pixelscale in radian in y (North-South) direction.

Type:

float

num_pix_x#

Amount of image pixels in the x direction.

Type:

int

num_pix_y#

Amount of image pixels in the y direction.

Type:

int

img#

2D numpy array containing the image flux in Jy. 1st index = image y-axis, 2nd index = image x-axis.

Type:

np.ndarray

ftot#

Total image flux in Jy.

Type:

float

sp_dep#

Optional spectral dependence of the image. Assumed flat in F_lam by default.

Type:

SpecDep

fft#

Complex 2D numpy FFT of img in Jy, i.e. in correlated flux formulation.

Type:

np.ndarray

num_pix_fft_x#

Amount of image FFT pixels in the x direction. This can be different from num_pix_x due to padding.

Type:

int

num_pix_fft_y#

Amount of image FFT pixels in the y direction. This can be different from num_pix_y due to padding.

Type:

int

w_x#

1D array with numpy FFT x-axis frequencies in units of 1/pixelscale_x.

Type:

np.ndarray

w_y#

1D array with numpy FFT y-axis frequencies in units of 1/pixelscale_y.

Type:

np.ndarray

uf#

1D array with FFT spatial x-axis frequencies in cycles/radian, i.e. uf = w_x/pixelscale_x.

Type:

np.ndarray

vf#

1D array with FFT spatial y-axis frequencies in cycles/radian, i.e. vf = w_y/pixelscale_y.

Type:

np.ndarray

Warning

The default value of sp_dep assumes a flat spectrum in F_lam. This implies a spectral dependency ~ frequency^-2 ~ wavelength^2 for F_nu. Thus the total correlated flux of the image FFT will not be flat accross wavelength.

diagnostic_plot(fig_dir: str | None = None, plot_vistype: Literal['vis2', 'vis', 'fcorr'] = 'vis2', log_plotv: bool = False, log_ploti: bool = False, show_plots: bool = True, plot_prefix: str = '') → None#

Create diagnostic plots.

Makes diagnostic plots showing both the model image and the FFT (squared) visibilities and complex phases.

Parameters:

  • fig_dir (str, optional) – Directory to store plots in.

  • plot_vistype ({'vis2', 'vis', 'fcorr'}, optional) – Sets the type of visibility to be plotted. ‘vis2’ for squared visibilities, ‘vis’ for visibilities or ‘fcorr’ for correlated flux in Jy.

  • log_plotv (bool, optional) – Set to True for a logarithmic y-scale in the (squared) visibility plot.

  • log_ploti (bool, optional) – Set to True for a logarithmic intensity scale in the model image plot.

  • show_plots (bool, optional) – Set to False if you do not want the plots to be shown during your script run. Note that if True, this freezes further code execution until the plot windows are closed.

  • plot_prefix (str, optional) – Prefix to add to the names of the plots to be saved.

Return type:

None

Raises:

ValueError – If an invalid plot_vistype is provided.

do_fft(padding: tuple[int, int] | None = None) → None#

Perform an FFT on the image.

Perform the numpy FFT on the img property and set the other required attributes related to the image’s FFT.

Parameters:

padding (tuple of int, optional) – Number of (x, y)-pixels to which an image should be 0-padded before performing the FFT. I.e. padding=(680, 540) will 0-pad an image to 680 and 540 pixels in the x and y dimensions, respectively. If smaller than the number of pixels already in the img array, no padding will be added in the respective dimension. These should both be even numbers!

Return type:

None

Raises:

ValueError – If the padding dimensions are not even numbers.

freq_info() → str#

Get a string with frequency domain info.

Returns a string containing information on both the spatial frequency domain/sampling and the corresponding projected baselines.

Returns:

info_str – String containing frequency info which can be printed.

Return type:

str

half_light_radius() → float#

Calculate the half light radius.

Calculate the half light radius of the image by adding up the fluxes of pixels within increasing circular apertures.

Returns:

hlr – The half light radius in milli-arcseconds.

Return type:

float

Warning

Due to the implementation, the returned value’s accuracy is inherently limited by the model image pixelscale. Note also that the radius is calculated in the image plane, and thus depends on e.g. inclination of the RT model.

Notes

If you want only the half light radius excluding the central source, e.g. the model disk in an MCFOST model, one should exclude the central source when reading in the image file (e.g. using disk_only=True with read_image_fft_mcfost).

redden(ebminv: float, reddening_law: str = '/home/docs/checkouts/readthedocs.org/user_builds/distroi/checkouts/latest/utils/ISM_reddening/ISMreddening_law_Cardelli1989.dat') → None#

Redden the image.

Further reddens the model image according to the appropriate E(B-V) and a corresponding reddening law.

Parameters:

  • ebminv (float) – E(B-V) reddening factor to be applied.

  • reddening_law (str, optional) – Path to the reddening law to be used. Defaults to the ISM reddening law by Cardelli (1989) in DISTROI’s ‘utils/ISM_reddening folder’. See this file for the expected formatting of your own reddening laws.

Return type:

None

distroi.data.image.image_fft_comp_vis_interpolator(img_ffts: list[Image], normalised: bool = False, interp_method: str = 'linear') → RegularGridInterpolator#

Create a regular grid interpolator for model image complex FFTs.

Creates a scipy RegularGridInterpolator from model Image objects, which can be used to interpolate the complex visibility to different spatial frequencies than those returned by the FFT algorithm and, optionally, different wavelengths than those of the RT model images themselves.

Parameters:

  • img_ffts (list of Image) – List of Image objects to create an interpolator from. If the list has length one, i.e. a monochromatic model for the emission, the returned interpolator can only take the 2 spatial frequencies (units 1/Hz) as arguments. If the list contains multiple objects, i.e. a chromatic model for the emission, the interpolator will also be able to take wavelength (in micron) as an argument and will be able to interpolate along the wavelength dimension.

  • normalised (bool, optional) – Set to True if you want the returned interpolator to produce normalised, non-absolute complex visibilities (for calculating e.g. squared visibilities). By default normalised = False, meaning the interpolator returns absolute complex visibilities, i.e. complex correlated fluxes (in units Jy).

  • interp_method (str, optional) – Interpolation method used by the returned scipy RegularGridInterpolator. Can support ‘linear’, ‘nearest’, ‘slinear’, ‘cubic’, ‘quintic’ or ‘pchip’.

Returns:

interpolator – Interpolator for the model image FFTs. If len(img_ffts) == 1, only takes the uv spatial frequencies (units 1/rad) as arguments as follows: interpolator(v, u). If len(img_ffts) > 1, then it also can interpolate between wavelengths (units micron) as follows: interpolator(wavelength, v, u).

Return type:

scipy.interpolate.RegularGridInterpolator

Raises:

ValueError – If the length of img_ffts is less than 1.

Warning

The interpolators order of arguments for u and v is reversed compared to their normal order, and the interpolator should be called upon as interpolator(v, u). This is because the ‘first index’ of an array representing an image in the ordinary python convention represents the y-axis, not the x-axis.

The interpolator will throw errors if arguments outside their bounds are supplied! Expects, in case of multiple model images, that every image included has the same pixelscale and amount of pixels (in both x- and y-direction).

distroi.data.image.image_fft_ftot_interpolator(img_ffts: list[Image], interp_method: str = 'linear') → interp1d#

Create a regular grid interpolator for the total flux in model images.

Creates a scipy interp1d object from a list of model Image objects, allowing to interpolate the total flux (F_nu format in unit Jansky) along the wavelength dimension.

Parameters:

  • img_ffts (list of Image) – List of Image objects to create an interpolator from. Must have length longer than one.

  • interp_method (str, optional) – Interpolation method used by scipy’s interp1d method. Default is ‘linear’. Can support ‘linear’, ‘nearest’, ‘nearest-up’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, or ‘next’.

Returns:

interpolator – Interpolator for the total flux in F_nu format and units Jy. Takes the wavelength in micron as its only argument.

Return type:

scipy.interpolate.interp1d

Raises:

Exception – If the length of img_ffts is less than 2.

distroi.data.image.read_image_list(mod_dir: str, img_dir: str, read_method: Literal['mcfost'] = 'mcfost', padding: tuple[int, int] | None = None, ebminv: float = 0.0, reddening_law: str = '/home/docs/checkouts/readthedocs.org/user_builds/distroi/checkouts/latest/utils/ISM_reddening/ISMreddening_law_Cardelli1989.dat') → list[Image] | None#

Read in multiple model image files into a list of Image objects.

Function that takes the path to an model’s directory and a subdirectory containing image files, and returns a list of Image objects representing those model images. They should thus represent the same underlying physical model, but imaged at different wavelengths.

Parameters:

  • mod_dir (str) – Parent directory of the RT model of interest.

  • img_dir (str) – Subdirectory containing RT model images. All image files recursively found in the subdirectories of mod_dir+img_dir are read.

  • read_method ({'mcfost'}, optional) – Type of method used to read in RT model images when creating Image class instances. Currently supports ‘mcfost’, in which case all files ending on the suffix ‘RT.fits.gz’ are read in, and ‘organic’.

  • padding (tuple of int, optional) – Number of (x, y)-pixels to which an image should be 0-padded before performing the FFT. I.e. padding=(680, 540) will 0-pad an image to 680 and 540 pixels in the x and y dimensions, respectively. If smaller than the number of pixels already in the img array, no padding will be added in the respective dimension. These should both be even numbers!

  • ebminv (float, optional) – E(B-V) of additional reddening to be applied to the model images. Only useful if the visibilities need to be expressed in correlated flux at some point.

  • reddening_law (str, optional) – Path to the reddening law to be used. Defaults to the ISM reddening law by Cardelli (1989) in DISTROI’s ‘utils/ISM_reddening folder’. See this file for the expected formatting of your own reddening laws.

Returns:

img_ffts – List of Image objects representing all model image files found under mod_dir+img_dir. Sorted by wavelength.

Return type:

list of Image

Raises:

ValueError – If an invalid read_method is provided.

distroi.data.image.read_image_mcfost(img_path: str, padding: tuple[int, int] | None = None, disk_only: bool = False) → Image#

Read in MCFOST model image.

Retrieve image data from an MCFOST model image file and return it as an Image class instance.

Parameters:

  • img_path (str) – Path to an MCFOST output RT.fits.gz model image file.

  • padding (tuple of int, optional) – Number of (x, y)-pixels to which an image should be 0-padded before performing the FFT. I.e. padding=(680, 540) will 0-pad an image to 680 and 540 pixels in the x and y dimensions, respectively. If smaller than the number of pixels already in the img array, no padding will be added in the respective dimension. These should both be even numbers!

  • disk_only (bool, optional) – Set to True if you only want to read in the flux from the disk.

Returns:

image – Image instance containing the information on the MCFOST RT image.

Return type:

Image

Raises:

FileNotFoundError – If the specified img_path does not exist.

distroi.data.image.read_image_organic(img_path: str, padding: tuple[int, int] | None = None) → tuple[Image, list[GeomComp]]#

Read in image from the ORGANIC image reconstruction code.

Retrieve image data from an ORGANIC reconstructed image file and return it as a Image class instance and a list of geometric components (representing the SPARCO components in ORGANIC). Reads in the PCA filtered median image if present.

Parameters:

  • img_path (str) – Path to an MCFOST output RT.fits.gz model image file.

  • padding (tuple of int, optional) – Number of (x, y)-pixels to which an image should be 0-padded before performing the FFT. I.e. padding=(680, 540) will 0-pad an image to 680 and 540 pixels in the x and y dimensions, respectively. If smaller than the number of pixels already in the img array, no padding will be added in the respective dimension. These should both be even numbers!

Returns:

organic_model – Returns a tuple containing the ORGANIC image and a list of Geometric components representing the SPARCO components used in ORGANIC.

Return type:

tuple(Image, list(GeomComp))