scopesim.optics.image_plane_utils module

scopesim.optics.image_plane_utils.add_imagehdu_to_imagehdu(image_hdu: ImageHDU, canvas_hdu: ImageHDU, spline_order: int = 1, wcs_suffix: str = '', conserve_flux: bool = True) → ImageHDU[source]

Re-project one fits.ImageHDU onto another fits.ImageHDU.

..assumption:: of equal grid coordinate lengths

Parameters:
image_hdufits.ImageHDU

The ImageHDU which will be reprojected onto canvas_hdu

canvas_hdufits.ImageHDU

The ImageHDU onto which the image_hdu should be projected. This must include a valid WCS

spline_orderint, optional

Default is 1. The order of the spline interpolator used by the scipy.ndimage functions

wcs_suffixstr or WCS

To determine which WCS to use. “” for sky HDUs and “D” for ImagePlane HDUs. Can also be astropy.wcs.WCS object.

conserve_fluxbool

Default is True. Used when zooming and rotating to keep flux constant.

Returns:
canvas_hdufits.ImageHDU
scopesim.optics.image_plane_utils.add_table_to_imagehdu(table: Table, canvas_hdu: ImageHDU, sub_pixel: bool = True, wcs_suffix: str = '') → ImageHDU[source]

Add files from an astropy.Table to the image of an fits.ImageHDU.

Parameters:
tableastropy.Table

Must contain the columns “x_mm”, “y_mm”, “flux” with the units in the column attribute .unit, or in the table.meta dictionary as “<colname>_unit”. Default units are mm and ph / s / pix

canvas_hdufits.ImageHDU

The ImageHDU onto which the table files should be projected. This must include a valid WCS

sub_pixelbool, optional

Default is True. If True, sub-pixel shifts of files will be taken into account when projecting onto the canvas pixel grid. This takes about 5x longer than ignoring the sub-pixel shifts

wcs_suffixstr, optional
Returns:
canvas_hdufits.ImageHDU
scopesim.optics.image_plane_utils.affine_map(input, matrix=None, rotation_angle: float = 0.0, shear_angle: float = 0.0, scale_factor=None, reshape: bool = True, spline_order: int = 3)[source]

Apply an affine transformation matrix to an image around its centre.

Similar functionality to scipy.ndimage.rotate but for the affine_transformation function

Either a 2x2 affine transformation matrix can be supplied, or the rotation, shear, and scaling values which are the basis of an affine transformation.

Parameters:
inputarray_like

The input array

matrixndarray, optional

A 2x2 affine transformation matrix

rotation_anglefloat, optional

[deg] If matrix==None, a rotation matrix is built from this angle

shear_anglefloat, optional

[deg] If matrix==None, a y-axis shear matrix is built from this angle

scale_factorlist, array

[mx, my] If matrix==None, a scaling matrix is built from this list

reshapebool, optional

If True, the array is re-sized to contain the whole transformed image

spline_orderint, optional

Default is 3. Spline interpolation order

Returns:
outputarray-like

The new mapping of the image

scopesim.optics.image_plane_utils.calc_footprint(header, wcs_suffix='', new_unit: str = None)[source]

Return the sky/detector positions [deg/mm] of the corners of a header WCS.

TODO: The rest of this docstring is outdated, please update!

The positions returned correspond to the corners of the header’s image array, in this order:

(ra, dec) = (0,0), (w, 0), (w, h), (0, h)
(x, y) = (0,0), (w, 0), (w, h), (0, h)

where w, h are equal to NAXIS1 and NAXIS2 from the header.

Parameters:
headerfits.Header
wcs_suffixstr

Letter suffix for the WCS keywords, e.g. CDELT1D for image-plane coords

Returns:
x, yarrays of floats

[deg or mm] x are the coordinates for pixels [0, w, w, 0] [deg or mm] y are the coordinates for pixels [0, 0, h, h]

scopesim.optics.image_plane_utils.calc_table_footprint(table: Table, x_name: str, y_name: str, tbl_unit: str, new_unit: str, padding=None) → ndarray[source]

Equivalent to calc_footprint(), but for tables instead of images.

Parameters:
tableastropy.table.Table

Table containing data.

x_namestr

Name of the column in table to use as x-coordinates.

y_namestr

Name of the column in table to use as y-coordinates.

tbl_unitstr

Default unit to use for x and y if no units are found in table.

new_unitstr

Unit to convert x and y to, can be identical to tbl_unit.

paddingastropy.units.Quantity, optional

Constant value to subtract from minima and add to maxima. If used, must be Quantity with same physical type as x and y. If None (default), no padding is added.

Returns:
extent(4, 2) array

Array containing corner points (clockwise from bottom left). Format and order are equivalent to the output of astropy.wcs.WCS.calc_footprint().

scopesim.optics.image_plane_utils.create_wcs_from_points(points: ndarray, pixel_scale: float, wcs_suffix: str = '') → tuple[astropy.wcs.wcs.WCS, numpy.ndarray][source]

Create astropy.wcs.WCS instance that fits all points inside.

Parameters:
corners(N, 2) array

2D array of N >= 2 points in the form of [x, y].

pixel_scalefloat

DESCRIPTION.

wcs_suffixstr, optional

DESCRIPTION. The default is “”.

Returns:
new_wcsTYPE

Newly created WCS instance.

naxisTYPE

Array of NAXIS needed to fit all points.

scopesim.optics.image_plane_utils.det_wcs_from_sky_wcs(sky_wcs: WCS, pixel_scale: float, plate_scale: float, naxis=None) → tuple[astropy.wcs.wcs.WCS, numpy.ndarray][source]

Create detector WCS from celestial WCS using pixel and plate scales.

Parameters:
sky_wcsastropy.wcs.WCS

Celestial WCS.

pixel_scalefloat

Quantity or float (assumed to be arcsec / pixel).

plate_scalefloat

Quantity or float (assumed to be arcsec / mm).

naxis(int, int), optional

Shape of the image, usually NAXIS1 and NAXIS2. If the input WCS holds this information, the default None will use that. Otherwise not providing naxis will raise and error.

Returns:
det_wcsastropy.wcs.WCS

Detector WCS.

det_naxis(int, int)

Shape of the image (NAXIS1, NAXIS2).

scopesim.optics.image_plane_utils.get_canvas_header(hdu_or_table_list, pixel_scale=<Quantity 1. arcsec>)[source]

Generate a fits.Header with a WCS that covers everything in the FOV.

Parameters:
hdu_or_table_listlist

A list of Tables and/or ImageHDU py_objects

pixel_scaleastropy.Quantity

[arcsec] The pixel scale of the projection. Default in 1 arcsec

Returns:
headerfits.Header

A Header containing a WCS and NAXISn values to build an ImageHDU

scopesim.optics.image_plane_utils.header_from_list_of_xy(x, y, pixel_scale, wcs_suffix='', arcsec=False)[source]

Make a header large enough to contain all x,y on-sky coordinates.

Parameters:
x, ylist of floats

[deg, mm] List of sky coordinates to be bounded by the NAXISn keys

pixel_scalefloat

[deg, mm]

Returns:
hdrfits.Header
scopesim.optics.image_plane_utils.overlay_image(small_im, big_im, coords, mask=None, sub_pixel=False)[source]

Overlay small_im on top of big_im at the position specified by coords.

small_im will be centred at coords

Adapted from: https://stackoverflow.com/questions/14063070/overlay-a-smaller-image-on-a-larger-image-python-opencv

scopesim.optics.image_plane_utils.pix2val(header, x, y, wcs_suffix='')[source]

Return the real coordinates [deg, mm] for coordinates from a Header WCS.

Parameters:
headerfits.Header
x, yfloat, list, array
wcs_suffixstr
Returns:
a, bfloat, array

[deg, mm] Real coordinates as given by the Header WCS

scopesim.optics.image_plane_utils.reorient_imagehdu(imagehdu: ImageHDU, wcs_suffix: str = '', conserve_flux: bool = True, spline_order: int = 1) → ImageHDU[source]

Apply an affine transformation to the image, as given in its header.

Parameters:
imagehdufits.ImageHDU
wcs_suffixstr
conserve_fluxbool
spline_orderint

[1..5] Order of the spline interpolation used by scipy.ndimage.rotate

Returns:
imagehdufits.ImageHDU
scopesim.optics.image_plane_utils.rescale_imagehdu(imagehdu: ImageHDU, pixel_scale: float, wcs_suffix: str = '', conserve_flux: bool = True, spline_order: int = 1) → ImageHDU[source]

Scale the .data array by the ratio of pixel_scale [deg] and CDELTn.

pixel_scale should NOT be passed as a Quantity!

Parameters:
imagehdufits.ImageHDU
pixel_scalefloat

[deg] NOT to be passed as a Quantity

wcs_suffixstr
conserve_fluxbool
spline_orderint

[1..5] Order of the spline interpolation used by scipy.ndimage.rotate

Returns:
imagehdufits.ImageHDU
scopesim.optics.image_plane_utils.sky_wcs_from_det_wcs(det_wcs: WCS, pixel_scale: float, plate_scale: float, naxis=None) → tuple[astropy.wcs.wcs.WCS, numpy.ndarray][source]

Create celestial WCS from detector WCS using pixel and plate scales.

Parameters:
det_wcsastropy.wcs.WCS

Detector WCS.

pixel_scalefloat

Quantity or float (assumed to be arcsec / pixel).

plate_scalefloat

Quantity or float (assumed to be arcsec / mm).

naxis(int, int), optional

Shape of the image, usually NAXIS1 and NAXIS2. If the input WCS holds this information, the default None will use that. Otherwise not providing naxis will raise and error.

Returns:
sky_wcsastropy.wcs.WCS

Celestial WCS.

sky_naxis(int, int)

Shape of the image (NAXIS1, NAXIS2).

scopesim.optics.image_plane_utils.split_header(hdr, chunk_size, wcs_suffix='')[source]

Split a header into many smaller parts of the chunk_size.

Parameters:
hdr
chunk_size
wcs_suffix
Returns:
hdr_list
scopesim.optics.image_plane_utils.sub_pixel_fractions(x, y)[source]

Make a list of pixel coordinates and weights to reflect sub-pixel shifts.

A point source which isn’t centred on a pixel can be modelled by a centred PSF convolved with a shifted delta function. A fraction of the delta function in moved into each of the adjoining pixels. For example, a star at (x,y)=(0.2, 0.2) would be represented by a following pixel weights:

---------------
| 0.16 | 0.04 |
---------------
| 0.64 | 0.16 |
---------------

where (0,0) is the centre of the bottom-left pixel

Given (x,y) pixel coordinates, this function returns the fractions of flux that should go into the surrounding pixels, as well as the coordinates of those neighbouring pixels.

Parameters:
x, yfloat
Returns:
x_pix, y_pix, fracslist of (int, int, float)

The x and y pixel coordinates and their corresponding flux fraction

scopesim.optics.image_plane_utils.val2pix(header, a, b, wcs_suffix='')[source]

Return the pixel coordinates for real coordinates [deg, mm] from a WCS.

Parameters:
headerfits.Header
a, bfloat, list, array

[deg, mm]

Returns:
x, yfloat, array

[pixel] Pixel coordinates as given by the Header WCS