The Image Object

The imtools.image.Image object forms the basis of most operations in imtools. It includes a number of member functions representing both in-place operations and operations which return a new & modified form of the image.

Images consist of numpy arrays corresponding to at least the measured cgs intensity (Stokes I), and potentially measurements of the linear and circular polarization (specifically in the form of the other Stokes parameters Q, U, V). As auxiliary variables they can potentially also include the optical depth and total Faraday rotation angle. It is rare to need to construct an Image object directly, usually they are returned by functions which read existing image files.

Several common operations are supported either in-place on an image or as a new return value; these include blurring, integer downsampling, and most mathematical operations and comparison functions, vs other images or constants. In addition, several per-pixel and integrated statistics such as linear and circular polarization fractions, EVPA, and plotting hint operations can be queried.

class imtools.image.Image(properties, array1, array2=None, array3=None, array4=None, tau=None, tauF=None, unpol=None, init_type='one_array_forward')

Images are intended for polarized theory “truth” data in the image plane only, represented as Stokes parameters and with square pixels (i.e. FOVx/FOVy == nx/ny).

Itot()

Total Stokes I flux in Jy

Qtot()

Total Stokes Q flux in Jy

Utot()

Total Stokes U flux in Jy

Vtot()

Total Stokes V flux in Jy

__add__(other)

Add image values or a constant factor.

__iadd__(other)

Add image values or a constant factor.

__imul__(other)

Multiply images (why?) or rescale by factor.

__init__(properties, array1, array2=None, array3=None, array4=None, tau=None, tauF=None, unpol=None, init_type='one_array_forward')

Initialize an Image object from data.

Parameters

  • properties – dict of image properties. This has no standard format on account of there’s no standard image format. Generally this library expects the ipole metadata to be present here, see ipole image format doc on Illinois docs wiki

  • array{1-4} –

    Stokes parameters in CGS. Contents interpreted based on init_type.

    • ”one_array_forward”: array of Stokes in index-first form i,j,S.

    • ”one_array_backward”: array in Stokes-first form S,i,j.

    • ”multi_arrays_stokes”: four arrays size i,j representing I,Q,U,V.

    • ”multi_arrays_rl”: NOT IMPLEMENTED – initialize from right- and left-circular components

    In all cases, i, j, should be ordered such that when plotted wiht meshgrid or imshow(origin=’lower’), the resulting image “looks correct” with North pointing in the +y direction

  • init_type – see above

  • tau – if not none, set optical depth member tau to this array

  • tauF – if not none, set Faraday depth member tauF to this array

  • unpol – if not none, add a version of stokes I computed with unpolarized transport. Note that unpolarized images are better off setting just stokes I – this member is for comparisons and sanity checks

__isub__(other)

Difference images or subtract a constant.

__itruediv__(other)

Elementwise division or divide by factor.

__mul__(other)

Multiply images (why?) or rescale by factor.

__sub__(other)

Difference images or subtract a constant.

__truediv__(other)

Elementwise division or divide by factor.

__weakref__

list of weak references to the object (if defined)

blurred(fwhm=20)

Return a version of this image blurred by a circular gaussian of width ‘fwhm’ micro-arcseconds.

cpfrac(mask_zero=False)

Return the per-pixel fractional circular polarization

cpfrac_int()

Integrated (zero-baseline) circular polarization fraction. NOT percentage.

downsampled(skip=2)

Return a version of this image downsampled by skipping every ‘skip’ pixels.

dssim(var1, var2)

Structural dissimilarity DSSIM is 1/SSIM - 1

dssims(other)

DSSIM for each variable with another image

evpa(evpa_conv='EofN', mask_zero=False)

Return the per-pixel EVPA in degrees, in EAST OF NORTH (EofN) convention by default.

Parameters

evpa_conv – convention for returning EVPA, “EofN” or “NofW”

evpa_int()

Integrated (zero-baseline) EVPA, East of North convention

extent(fov_units)

Window corresponding to full image.

Parameters

fov_units – Units to use. “muas” for micro-arcsecond, “M” for \(r_g\)

flux()

Total Stokes I flux in Jy

flux_unpol()

Total flux in Jy of unpolarized image

get_name()

Return image name. All get_ functions exist mostly for parallel calls, which cannot take lambdas/members and thus must take class functions e.g. Image.get_name()

get_raw()

Array [s,i,j] of all Stokes parameters

get_stokes(n)

Get image [i,j] of Stokes parameter #n where 0==I

lpfrac(mask_zero=False)

Return the per-pixel fractional linear polarization.

Parameters

mask_zero – mask off low-emission elements by setting them to NaN. Useful if the result will inform an overlaid quiver plot.

lpfrac_av(blur=20, mask_zero=False)

Average linear polarization fraction per-pixel across the image. Heavily blur dependent!

Parameters

blur – gaussian FWHM blur to apply before calculating the value. Set to 0 if image is already blurred.

lpfrac_int()

Integrated (zero-baseline) linear polarization fraction. NOT percentage.

mse(var1, var2)

MSE of one var vs another. Follows the usual convention of dividing by the sum(var) of this image

mses(other)

MSE for each variable with another image

ncc(var1, var2)

Image Normalized Cross-Correlation: ZNCC without subtracting the mean

nccs(other)

NCC for each variable with another image

parse_properties(properties)

Set some member variables based on a general ‘properties’ dictionary. Generally supports only dictionaries in the format read from ipole image files using e.g. hdf5_to_dict.

rel_diff(other, clip=None)

Return the image representing pixel-wise relative difference between this image and another. That is, (im2-im1)/im1 for each pixel. Optionally clipped

ring_mask(var=None, cut=1.0, add_std=False)

Get a mask of just the ring, i.e. zones with I greater than some portion of mean(I), Or optionally mean(I) + stddev

rot90(rot)

Rotate this image in-place 90 degrees counter-clockwise ‘rot’ times

rotated90(rot)

Return an image rotated by 90 degrees counter-clockwise ‘rot’ times.

scale_flux(units)

Return the scale factor to use on image contents, based on desired units.

Parameters

units – “cgs” for intensity in cgs units, “Jy/px” or “Jy” for total flux in Jy through each pixel.

ssim(var1, var2)

Structural similarity SSIM as defined in Gold et al eq 10-ish

ssims(other)

SSIM for each variable with another image

tauF_av()

Average full Faraday rotation angle across the image.

tau_av()

Average optical depth across the image

visibilities(pad_x=10)

Get the complex visibilities corresponding to the image.

Parameters

pad_x – Number of times by which to pad FFT with zeros, to preserve resolution in desired area. Image will be padded out to a total of N1*pad_x by N2*pad_x pixels.

Returns

“Image” with complex visibilities of each Stokes parameter. Note most functions will not behave correctly in this version.

visibility_amplitudes(pad_x=10, crop_x=10)

Get the visibility amplitudes corresponding to the image.

Parameters

  • pad_x – Number of times by which to pad FFT to preserve resolution in desired area. Image will be padded with zeros to a total of N1*pad_x by N2*pad_x pixels.

  • re_crop – Crop image back to N1xN2 pixels in the center of the FFT’d version

Returns

“Image” object with visibility amplitudes of each Stokes parameter. Note most functions will not behave correctly in this version.

visibility_phases(pad_x=4, crop_x=10)

Get the complex visibility phases corresponding to the image.

Parameters

  • pad_x – Number of times by which to pad FFT to preserve resolution in desired area. Image will be padded with zeros to a total of N1*pad_x by N2*pad_x pixels.

  • re_crop – Crop image back to N1xN2 pixels in the center of the FFT’d version.

Returns

“Image” with complex visibilities of each Stokes parameter. Note most functions will not behave correctly in this version.

zero_mask()

Get a mask of just the zones where I is vanishingly small compared to the main image. Set them to nan to avoid printing BS lpfrac/cpfrac when dividing by ~<=0

zncc(var1, var2)

Image Zero-Normalized Cross-Correlation

znccs(other)

ZNCC for each variable with another image