astrophot.image package

Submodules

astrophot.image.image_header module

class astrophot.image.image_header.Image_Header(*, data_shape: Tensor | None = None, wcs: WCS | None = None, window: Window | None = None, filename: str | None = None, zeropoint: float | Tensor | None = None, metadata: dict | None = None, identity: str | None = None, state: dict | None = None, fits_state: dict | None = None, **kwargs: Any)

Bases: object

Store meta-information for images to be used in AstroPhot.

The Image_Header object stores all meta information which tells AstroPhot what is contained in an image array of pixels. This includes coordinate systems and how to transform between them (see Coordinates). The image header will also know the image zeropoint if that data is avaialble.

Parameters:

• window – Window or None, optional A Window object defining the area of the image in the coordinate systems. Default is None.

• filename – str or None, optional The name of a file containing the image data. Default is None.

• zeropoint – float or None, optional The image’s zeropoint, used for flux calibration. Default is None.

• metadata – dict or None, optional Any information the user wishes to associate with this image, stored in a python dictionary. Default is None.

property center: Tensor

Returns the center of the image window (arcsec).

Returns:

A 1D tensor of shape (2,) containing the (x, y) coordinates of the center.

Return type:

torch.Tensor

copy(**kwargs)

Produce a copy of this image with all of the same properties. This can be used when one wishes to make temporary modifications to an image and then will want the original again.

crop(pixels)

Reduce the size of an image by cropping some number of pixels off the borders. If pixels is a single value, that many pixels are cropped off all sides. If pixels is two values then a different crop is done in x vs y. If pixels is four values then crop on all sides are specified explicitly.

formatted as: [crop all sides] or [crop x, crop y] or [crop x low, crop y low, crop x high, crop y high]

get_coordinate_corner_meshgrid()

get_coordinate_meshgrid()

get_coordinate_simps_meshgrid()

get_fits_state()

get_state()

Returns a dictionary with necessary information to recreate the Image_Header object.

get_window(window, **kwargs)

Get a sub-region of the image as defined by a window on the sky.

load(filename)

load header from a FITS file.

north = 1.5707963267948966

property origin: Tensor

Returns the location of the origin (pixel coordinate -0.5, -0.5) of the image window in the tangent plane (arcsec).

Returns:

A 1D tensor of shape (2,) containing the (x, y) coordinates of the origin.

Return type:

torch.Tensor

property pixel_area

property pixel_length

pixel_shift(shift)

pixel_to_plane(*args, **kwargs)

pixel_to_plane_delta(*args, **kwargs)

pixel_to_world(*args, **kwargs)

property pixelscale

plane_to_pixel(*args, **kwargs)

plane_to_pixel_delta(*args, **kwargs)

plane_to_world(*args, **kwargs)

rescale_pixel(scale: int, **kwargs)

save(filename=None, overwrite=True)

Save header to a FITS file.

set_fits_state(state)

Updates the state of the Image_Header using information saved in a FITS header (more generally, a properly formatted dictionary will also work but not yet).

set_state(state)

property shape: Tensor

Returns the shape (size) of the image window (arcsec, arcsec).

Returns:

A 1D tensor of shape (2,) containing the (width, height) of the window in arcsec.

Return type:

torch.Tensor

shift(shift)

Adjust the position of the image described by the header. This will not adjust the data represented by the header, only the coordinate system that maps pixel coordinates to the plane coordinates.

to(dtype=None, device=None)

world_to_pixel(*args, **kwargs)

world_to_plane(*args, **kwargs)

property zeropoint

The photometric zeropoint of the image, used as a flux reference point.

astrophot.image.image_object module

class astrophot.image.image_object.Image(*, data: Tensor | None = None, header: Image_Header | None = None, wcs: WCS | None = None, pixelscale: float | Tensor | None = None, window: Window | None = None, filename: str | None = None, zeropoint: float | Tensor | None = None, metadata: dict | None = None, origin: Sequence | None = None, center: Sequence | None = None, identity: str | None = None, state: dict | None = None, fits_state: dict | None = None, **kwargs: Any)

Bases: object

Core class to represent images with pixel values, pixel scale,

and a window defining the spatial coordinates on the sky. It supports arithmetic operations with other image objects while preserving logical image boundaries. It also provides methods for determining the coordinate locations of pixels

Parameters:

• data – the matrix of pixel values for the image

• pixelscale – the length of one side of a pixel in arcsec/pixel

• window – an AstroPhot Window object which defines the spatial cooridnates on the sky

• filename – a filename from which to load the image.

• zeropoint – photometric zero point for converting from pixel flux to magnitude

• metadata – Any information the user wishes to associate with this image, stored in a python dictionary

• origin – The origin of the image in the coordinate system.

blank_copy(**kwargs)

Produces a blank copy of the image which has the same properties except that its data is now filled with zeros.

property center: Tensor

Returns the center of the image window.

Returns:

A 1D tensor of shape (2,) containing the (x, y) coordinates of the center.

Return type:

torch.Tensor

copy(**kwargs)

Produce a copy of this image with all of the same properties. This can be used when one wishes to make temporary modifications to an image and then will want the original again.

crop(pixels)

property data: Tensor

Returns the image data.

expand(padding: Tuple[float]) → None

Parameters:

tuple[float] (padding) – length 4 tuple with amounts to pad each dimension in physical units

flatten(attribute: str = 'data') → ndarray

get_coordinate_corner_meshgrid()

get_coordinate_meshgrid()

get_coordinate_simps_meshgrid()

get_fits_state()

get_state()

get_window(window, **kwargs)

Get a sub-region of the image as defined by a window on the sky.

property identity

load(filename)

property metadata

property north

property origin: Tensor

Returns the origin (bottom-left corner) of the image window.

Returns:

A 1D tensor of shape (2,) containing the (x, y) coordinates of the origin.

Return type:

torch.Tensor

property pixel_area

property pixel_length

pixel_to_plane(*args, **kwargs)

pixel_to_plane_delta(*args, **kwargs)

pixel_to_world(*args, **kwargs)

property pixelscale

plane_to_pixel(*args, **kwargs)

plane_to_pixel_delta(*args, **kwargs)

plane_to_world(*args, **kwargs)

reduce(scale: int, **kwargs)

This operation will downsample an image by the factor given. If scale = 2 then 2x2 blocks of pixels will be summed together to form individual larger pixels. A new image object will be returned with the appropriate pixelscale and data tensor. Note that the window does not change in this operation since the pixels are condensed, but the pixel size is increased correspondingly.

Parameters:

scale – factor by which to condense the image pixels. Each scale X scale region will be summed [int]

save(filename=None, overwrite=True)

set_data(data: Tensor | ndarray, require_shape: bool = True)

Set the image data.

Parameters:

• data (torch.Tensor or numpy.ndarray) – The image data.

• require_shape (bool) – Whether to check that the shape of the data is the same as the current data.

Raises:

SpecificationConflict – If require_shape is True and the shape of the data is different from the current data.

set_fits_state(states)

set_state(state)

property shape: Tensor

Returns the shape (size) of the image window.

Returns:

A 1D tensor of shape (2,) containing the (width, height) of the window in pixels.

Return type:

torch.Tensor

property size: Tensor

Returns the size of the image window, the number of pixels in the image.

Returns:

A 0D tensor containing the number of pixels.

Return type:

torch.Tensor

to(dtype=None, device=None)

property window

world_to_pixel(*args, **kwargs)

world_to_plane(*args, **kwargs)

property zeropoint

class astrophot.image.image_object.Image_List(image_list, window=None)

Bases: Image

blank_copy()

Produces a blank copy of the image which has the same properties except that its data is now filled with zeros.

check_wcs()

Ensure the WCS systems being used by all the windows in this list are consistent with each other. They should all project world coordinates onto the same tangent plane.

copy()

Produce a copy of this image with all of the same properties. This can be used when one wishes to make temporary modifications to an image and then will want the original again.

crop(*pixels)

property data

Returns the image data.

flatten(attribute='data')

get_coordinate_corner_meshgrid()

get_coordinate_meshgrid()

get_coordinate_simps_meshgrid()

get_window(window)

Get a sub-region of the image as defined by a window on the sky.

index(other)

load(filename)

property pixelscale

reduce(scale)

This operation will downsample an image by the factor given. If scale = 2 then 2x2 blocks of pixels will be summed together to form individual larger pixels. A new image object will be returned with the appropriate pixelscale and data tensor. Note that the window does not change in this operation since the pixels are condensed, but the pixel size is increased correspondingly.

Parameters:

scale – factor by which to condense the image pixels. Each scale X scale region will be summed [int]

save(filename=None, overwrite=True)

to(dtype=None, device=None)

property window

property zeropoint

astrophot.image.jacobian_image module

class astrophot.image.jacobian_image.Jacobian_Image(parameters: List[str], target_identity: str, **kwargs)

Bases: Image

Jacobian of a model evaluated in an image.

Image object which represents the evaluation of a jacobian on an image. It takes the form of a 3D (Image x Nparameters) tensor. This object can be added other other Jacobian images to build up a full jacobian for a complex model.

copy(**kwargs)

Produce a copy of this image with all of the same properties. This can be used when one wishes to make temporary modifications to an image and then will want the original again.

flatten(attribute: str = 'data')

get_fits_state()

get_state()

set_fits_state(states)

set_state(state)

class astrophot.image.jacobian_image.Jacobian_Image_List(image_list)

Bases: Image_List, Jacobian_Image

For joint modelling, represents Jacobians evaluated on a list of images.

Stores jacobians evaluated on a number of image objects. Since jacobian images are aware of the target images they were evaluated on, it is possible to combine this object with other Jacobian_Image_List objects or even Jacobian_Image objects and everything will be sorted into the proper locations of the list, and image.

flatten(attribute='data')

astrophot.image.model_image module

class astrophot.image.model_image.Model_Image(*args, **kwargs)

Bases: Image

Image object which represents the sampling of a model at the given coordinates of the image. Extra arithmetic operations are available which can update model values in the image. The whole model can be shifted by less than a pixel to account for sub-pixel accuracy.

clear_image()

get_fits_state()

get_state()

get_window(window: Window, **kwargs)

Get a sub-region of the image as defined by a window on the sky.

reduce(scale, **kwargs)

This operation will downsample an image by the factor given. If scale = 2 then 2x2 blocks of pixels will be summed together to form individual larger pixels. A new image object will be returned with the appropriate pixelscale and data tensor. Note that the window does not change in this operation since the pixels are condensed, but the pixel size is increased correspondingly.

Parameters:

scale – factor by which to condense the image pixels. Each scale X scale region will be summed [int]

replace(other, data=None)

set_fits_state(states)

set_state(state)

shift_origin(shift, is_prepadded=True)

class astrophot.image.model_image.Model_Image_List(*args, **kwargs)

Bases: Image_List, Model_Image

clear_image()

replace(other, data=None)

shift_origin(shift)

property target_identity

astrophot.image.psf_image module

class astrophot.image.psf_image.PSF_Image(*args, **kwargs)

Bases: Image

Image object which represents a model of PSF (Point Spread Function).

PSF_Image inherits from the base Image class and represents the model of a point spread function. The point spread function characterizes the response of an imaging system to a point source or point object.

The shape of the PSF data must be odd.

data

The image data of the PSF.

Type:

torch.Tensor

identity

The identity of the image. Default is None.

Type:

str

psf_border_int()

Calculates and returns the convolution border size of the PSF image in integer format.

psf_border()

Calculates and returns the convolution border size of the PSF image in the units of pixelscale.

_save_image_list()

Saves the image list to the PSF HDU header.

reduce()

Reduces the size of the image using a given scale factor.

expand(padding)

Parameters:

tuple[float] (padding) – length 4 tuple with amounts to pad each dimension in physical units

get_fits_state()

has_mask = False

has_variance = False

jacobian_image(parameters: List[str] | None = None, data: Tensor | None = None, **kwargs)

Construct a blank Jacobian_Image object formatted like this current PSF_Image object. Mostly used internally.

model_image(data: Tensor | None = None, **kwargs)

Construct a blank Model_Image object formatted like this current Target_Image object. Mostly used internally.

normalize()

Normalizes the PSF image to have a sum of 1.

property psf_border_int

Calculates and returns the border size of the PSF image in integer format. This is the border used for padding before convolution.

Returns:

The border size of the PSF image in integer format.

Return type:

torch.Tensor

set_data(data: Tensor | ndarray, require_shape: bool = True)

Set the image data.

Parameters:

• data (torch.Tensor or numpy.ndarray) – The image data.

• require_shape (bool) – Whether to check that the shape of the data is the same as the current data.

Raises:

SpecificationConflict – If require_shape is True and the shape of the data is different from the current data.

set_fits_state(states)

astrophot.image.target_image module

class astrophot.image.target_image.Target_Image(*args, **kwargs)

Bases: Image

Image object which represents the data to be fit by a model. It can include a variance image, mask, and PSF as anciliary data which describes the target image.

Target images are a basic unit of data in AstroPhot, they store the information collected from telescopes for which models are to be fit. There is minimial functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

import astrophot as ap

# Create target image
image = ap.image.Target_Image(
    data = <pixel data>,
    wcs = <astropy WCS object>,
    variance = <pixel uncertainties>,
    psf = <point spread function as PSF_Image object>,
    mask = <pixels to ignore>,
)

# Display the data
fig, ax = plt.subplots()
ap.plots.target_image(fig, ax, image)
plt.show()

# Save the image
image.save("mytarget.fits")

# Load the image
image2 = ap.image.Target_Image(filename = "mytarget.fits")

# Make low resolution version
lowrez = image.reduce(2)

Some important information to keep in mind. First, providing an astropy WCS object is the best way to keep track of coordinates and pixel scale properties, especially when dealing with multi-band data. If images have relative positioning, rotation, pixel sizes, field of view this will all be handled automatically by taking advantage of WCS objects. Second, Providing accurate variance (or weight) maps is critical to getting a good fit to the data. This is a very common source of issues so it is worthwhile to review literature on how best to construct such a map. A good starting place is the FAQ for GALFIT: https://users.obs.carnegiescience.edu/peng/work/galfit/CHI2.html which is an excellent resource for all things image modeling. Just note that AstroPhot uses variance or weight maps, not sigma images. AstroPhot will not crete a variance map for the user, by default it will just assume uniform variance which is rarely accurate. Third, The PSF pixelscale must be a multiple of the image pixelscale. So if the image has a pixelscale of 1 then the PSF must have a pixelscale of 1, 1/2, 1/3, etc for anything to work out. Note that if the PSF pixelscale is finer than the image, then all modelling will be done at the higher resolution. This is recommended for accuracy though it can mean higher memory consumption.

and_mask(mask)

Combines the currently stored mask with a provided new mask using the boolean and operator.

blank_copy(**kwargs)

Produces a blank copy of the image which has the same properties except that its data is not filled with zeros.

copy(**kwargs)

Produce a copy of this image with all of the same properties. This can be used when one wishes to make temporary modifications to an image and then will want the original again.

expand(padding)

Target_Image doesn’t have expand yet.

get_fits_state()

get_state()

get_window(window, **kwargs)

Get a sub-region of the image as defined by a window on the sky.

property has_mask

Single boolean to indicate if a mask has been provided by the user.

property has_psf

property has_variance

Returns True when the image object has stored variance values. If this is False and the variance property is called then a tensor of ones will be returned.

property has_weight

Returns True when the image object has stored weight values. If this is False and the weight property is called then a tensor of ones will be returned.

image_count = 0

jacobian_image(parameters: List[str] | None = None, data: Tensor | None = None, **kwargs)

Construct a blank Jacobian_Image object formatted like this current Target_Image object. Mostly used internally.

property mask

The mask stores a tensor of boolean values which indicate any pixels to be ignored. These pixels will be skipped in likelihood evaluations and in parameter optimization. It is common practice to mask pixels with pathological values such as due to cosmic rays or satelites passing through the image.

In a mask, a True value indicates that the pixel is masked and should be ignored. False indicates a normal pixel which will inter into most calculaitons.

If no mask is provided, all pixels are assumed valid.

model_image(data: Tensor | None = None, **kwargs)

Construct a blank Model_Image object formatted like this current Target_Image object. Mostly used internally.

or_mask(mask)

Combines the currently stored mask with a provided new mask using the boolean or operator.

property psf

Stores the point-spread-function for this target. This should be a PSF_Image object which represents the scattering of a point source of light. It can also be an AstroPhot_Model object which will contribute its own parameters to an optimization problem.

The PSF stored for a Target_Image object is passed to all models applied to that target which have a psf_mode that is not none. This means they will all use the same PSF model. If one wishes to define a variable PSF across an image, then they should pass the PSF objects to the AstroPhot_Model’s directly instead of to a Target_Image.

Raises:

AttributeError – if this is called without a PSF defined

reduce(scale, **kwargs)

Returns a new Target_Image object with a reduced resolution compared to the current image. scale should be an integer indicating how much to reduce the resolution. If the Target_Image was originally (48,48) pixels across with a pixelscale of 1 and reduce(2) is called then the image will be (24,24) pixels and the pixelscale will be 2. If reduce(3) is called then the returned image will be (16,16) pixels across and the pixelscale will be 3.

set_fits_state(states)

set_mask(mask)

Set the boolean mask which will indicate which pixels to ignore. A mask value of True means the pixel will be ignored.

set_psf(psf, psf_upscale=1)

Provide a psf for the Target_Image. This is stored and passed to models which need to be convolved.

The PSF doesn’t need to have the same pixelscale as the image. It should be some multiple of the resolution of the Target_Image though. So if the image has a pixelscale of 1, the psf may have a pixelscale of 1, 1/2, 1/3, 1/4 and so on.

set_state(state)

set_variance(variance)

Provide a variance tensor for the image. Variance is equal to $sigma^2$. This should have the same shape as the data.

set_weight(weight)

Provide a weight tensor for the image. Weight is equal to $frac{1}{sigma^2}$. This should have the same shape as the data.

property standard_deviation

Stores the standard deviation of the image pixels. This represents the uncertainty in each pixel value. It should always have the same shape as the image data. In the case where the standard deviation is not known, a tensor of ones will be created to stand in as the standard deviation values.

The standard deviation is not stored directly, instead it is computed as \(\sqrt{1/W}\) where \(W\) is the weights.

to(dtype=None, device=None)

Converts the stored Target_Image data, variance, psf, etc to a given data type and device.

property variance

Stores the variance of the image pixels. This represents the uncertainty in each pixel value. It should always have the same shape as the image data. In the case where the variance is not known, a tensor of ones will be created to stand in as the variance values.

The variance is not stored directly, instead it is computed as \(\frac{1}{W}\) where \(W\) is the weights.

property weight

Stores the weight of the image pixels. This represents the uncertainty in each pixel value. It should always have the same shape as the image data. In the case where the weight is not known, a tensor of ones will be created to stand in as the weight values.

The weights are used to proprtionately scale residuals in the likelihood. Most commonly this shows up as a \(\chi^2\) like:

\[\chi^2 = (\vec{y} - \vec{f(\theta)})^TW(\vec{y} - \vec{f(\theta)})\]

which can be optimized to find parameter values. Using the Jacobian, which in this case is the derivative of every pixel wrt every parameter, the weight matrix also appears in the gradient:

\[\vec{g} = J^TW(\vec{y} - \vec{f(\theta)})\]

and the hessian approximation used in Levenberg-Marquardt:

\[H \approx J^TWJ\]

class astrophot.image.target_image.Target_Image_List(*args, **kwargs)

Bases: Image_List, Target_Image

and_mask(mask)

Combines the currently stored mask with a provided new mask using the boolean and operator.

property has_mask

Single boolean to indicate if a mask has been provided by the user.

property has_psf

property has_variance

Returns True when the image object has stored variance values. If this is False and the variance property is called then a tensor of ones will be returned.

property has_weight

Returns True when the image object has stored weight values. If this is False and the weight property is called then a tensor of ones will be returned.

jacobian_image(parameters: List[str], data: List[Tensor] | None = None)

Construct a blank Jacobian_Image object formatted like this current Target_Image object. Mostly used internally.

property mask

The mask stores a tensor of boolean values which indicate any pixels to be ignored. These pixels will be skipped in likelihood evaluations and in parameter optimization. It is common practice to mask pixels with pathological values such as due to cosmic rays or satelites passing through the image.

In a mask, a True value indicates that the pixel is masked and should be ignored. False indicates a normal pixel which will inter into most calculaitons.

If no mask is provided, all pixels are assumed valid.

match_indices(other)

model_image(data: List[Tensor] | None = None)

Construct a blank Model_Image object formatted like this current Target_Image object. Mostly used internally.

or_mask(mask)

Combines the currently stored mask with a provided new mask using the boolean or operator.

property psf

Stores the point-spread-function for this target. This should be a PSF_Image object which represents the scattering of a point source of light. It can also be an AstroPhot_Model object which will contribute its own parameters to an optimization problem.

The PSF stored for a Target_Image object is passed to all models applied to that target which have a psf_mode that is not none. This means they will all use the same PSF model. If one wishes to define a variable PSF across an image, then they should pass the PSF objects to the AstroPhot_Model’s directly instead of to a Target_Image.

Raises:

AttributeError – if this is called without a PSF defined

property psf_border

property psf_border_int

set_mask(mask, img)

Set the boolean mask which will indicate which pixels to ignore. A mask value of True means the pixel will be ignored.

set_psf(psf, img)

Provide a psf for the Target_Image. This is stored and passed to models which need to be convolved.

The PSF doesn’t need to have the same pixelscale as the image. It should be some multiple of the resolution of the Target_Image though. So if the image has a pixelscale of 1, the psf may have a pixelscale of 1, 1/2, 1/3, 1/4 and so on.

set_variance(variance, img)

Provide a variance tensor for the image. Variance is equal to $sigma^2$. This should have the same shape as the data.

property variance

Stores the variance of the image pixels. This represents the uncertainty in each pixel value. It should always have the same shape as the image data. In the case where the variance is not known, a tensor of ones will be created to stand in as the variance values.

The variance is not stored directly, instead it is computed as \(\frac{1}{W}\) where \(W\) is the weights.

property weight

Stores the weight of the image pixels. This represents the uncertainty in each pixel value. It should always have the same shape as the image data. In the case where the weight is not known, a tensor of ones will be created to stand in as the weight values.

The weights are used to proprtionately scale residuals in the likelihood. Most commonly this shows up as a \(\chi^2\) like:

\[\chi^2 = (\vec{y} - \vec{f(\theta)})^TW(\vec{y} - \vec{f(\theta)})\]

which can be optimized to find parameter values. Using the Jacobian, which in this case is the derivative of every pixel wrt every parameter, the weight matrix also appears in the gradient:

\[\vec{g} = J^TW(\vec{y} - \vec{f(\theta)})\]

and the hessian approximation used in Levenberg-Marquardt:

\[H \approx J^TWJ\]

astrophot.image.wcs module

class astrophot.image.wcs.PPCS(*, wcs=None, pixelscale=None, **kwargs)

Bases: object

plane to pixel coordinate system

Args:

pixelscalefloat or None, optional

The physical scale of the pixels in the image, this is represented as a matrix which projects pixel units into sky units: \(pixelscale @ pixel_vec = sky_vec\). The pixel scale matrix can be thought of in four components: :math:`

ec{s} @ F @ R @ S` where :math:` ec{s}` is the side

length of the pixels, \(F\) is a diagonal matrix of {1,-1} which flips the axes orientation, \(R\) is a rotation matrix, and \(S\) is a shear matrix which turns rectangular pixels into parallelograms. Default is None.

reference_imageijSequence or None, optional

The pixel coordinate at which the image is fixed to the tangent plane. By default this is (-0.5, -0.5) or the bottom corner of the [0,0] indexed pixel.

reference_imagexySequence or None, optional

The tangent plane coordinate at which the image is fixed, corresponding to the reference_imageij coordinate. These two reference points ar pinned together, any rotations would occur about this point. By default this is (0., 0.).

copy(**kwargs)

Create a copy of the PPCS object with the same projection paramaters.

default_pixelscale = 1

default_reference_imageij = (-0.5, -0.5)

default_reference_imagexy = (0, 0)

get_fits_state()

Similar to get_state, except specifically tailored to be stored in a FITS format.

get_state()

property pixel_area

The area inside a pixel in arcsec^2

property pixel_length

The approximate length of a pixel, which is just sqrt(pixel_area). For square pixels this is the actual pixel length, for rectangular pixels it is a kind of average.

The pixel_length is typically not used for exact calculations and instead sets a size scale within an image.

pixel_to_plane(pixel_i, pixel_j=None)

Take in a coordinate on the regular pixel grid, where 0,0 is the

center of the [0,0] indexed pixel. This coordinate is transformed into the tangent plane coordinate system (arcsec) based on the pixel scale and reference positions. If the pixel scale matrix is \(P\), the reference pixel is :math:`

ec{r}_{pix}`, the reference tangent plane point is

:math:`

ec{r}_{tan}`, and the coordinate to transform is

:math:`

ec{c}_{pix}` then the coordinate in the tangent plane

is:

\[\]

ec{c}_{tan} = [P( ec{c}_{pix} - ec{r}_{pix})] + ec{r}_{tan}

pixel_to_plane_delta(pixel_delta_i, pixel_delta_j=None)

Take a translation in pixel space and determine the cooresponding translation in the tangent plane (arcsec). Essentially this performs the pixel scale matrix multiplication without any reference coordinates applied.

property pixelscale

Matrix defining the shape of pixels in the tangent plane, these can be any parallelogram defined by the matrix.

plane_to_pixel(plane_x, plane_y=None)

Take a coordinate on the tangent plane (arcsec) and transform it to

the cooresponding pixel grid coordinate (pixel units where (0,0) is the [0,0] indexed pixel). Transformation is done based on the pixel scale and reference positions. If the pixel scale matrix is \(P\), the reference pixel is :math:`

ec{r}_{pix}`, the reference tangent plane point is

:math:`

ec{r}_{tan}`, and the coordinate to transform is

:math:`

ec{c}_{tan}` then the coordinate in the pixel grid

is:

\[\]

ec{c}_{pix} = [P^{-1}( ec{c}_{tan} - ec{r}_{tan})] + ec{r}_{pix}

plane_to_pixel_delta(plane_delta_x, plane_delta_y=None)

Take a translation in tangent plane space (arcsec) and determine the cooresponding translation in pixel space. Essentially this performs the pixel scale matrix multiplication without any reference coordinates applied.

property reference_imageij

pixel coordinates where the pixel grid is fixed to the tangent plane. These should be in pixel units where (0,0) is the center of the [0,0] indexed pixel. However, it is still in xy format, meaning that the first index gives translations in the x-axis (horizontal-axis) of the image.

property reference_imagexy

plane coordinates where the image grid is fixed to the tangent plane. These should be in arcsec.

set_fits_state(state)

Reads and applies the state from the get_fits_state function.

set_state(state)

to(dtype=None, device=None)

Convert all stored tensors to a new device and data type

class astrophot.image.wcs.WCS(*args, wcs=None, **kwargs)

Bases: WPCS, PPCS

Full world coordinate system defines mappings from world to tangent plane to pixel grid and all other variations.

copy(**kwargs)

Create a copy of the WPCS object with the same projection paramaters.

get_fits_state()

Similar to get_state, except specifically tailored to be stored in a FITS format.

get_state()

Returns a dictionary with the information needed to recreate the WPCS object.

pixel_to_world(pixel_i, pixel_j=None)

A wrapper which applies pixel_to_plane() then plane_to_world(), see those methods for further information.

set_fits_state(state)

Reads and applies the state from the get_fits_state function.

set_state(state)

Takes a state dictionary and re-creates the state of the WPCS object.

to(dtype=None, device=None)

Convert all stored tensors to a new device and data type

world_to_pixel(world_RA, world_DEC=None)

A wrapper which applies world_to_plane() then plane_to_pixel(), see those methods for further information.

class astrophot.image.wcs.WPCS(**kwargs)

Bases: object

World to Plane Coordinate System in AstroPhot.

AstroPhot performs its operations on a tangent plane to the celestial sphere, this class handles projections between the sphere and the tangent plane. It holds variables for the reference (RA,DEC) where the tangent plane contacts the sphere, and the type of projection being performed. Note that (RA,DEC) coordinates should always be in degrees while the tangent plane is in arcsecs.

reference_radec

The reference (RA,DEC) coordinates in degrees where the tangent plane contacts the sphere.

reference_planexy

The reference tangent plane coordinates in arcsec where the tangent plane contacts the sphere.

projection

The projection system used to convert from (RA,DEC) onto the tangent plane. Should be one of: gnomonic (default), orthographic, steriographic

copy(**kwargs)

Create a copy of the WPCS object with the same projection paramaters.

default_projection = 'gnomonic'

default_reference_planexy = (0, 0)

default_reference_radec = (0, 0)

get_fits_state()

Similar to get_state, except specifically tailored to be stored in a FITS format.

get_state()

Returns a dictionary with the information needed to recreate the WPCS object.

plane_to_world(plane_x, plane_y=None)

Take a coordinate on the tangent plane (arcsec), and transform it to the cooresponding world coordinate (RA, DEC in degrees). Transformation is done based on the chosen projection (default gnomonic) and reference positions. See the Coordinates documentation for more details on how the transformation is performed.

property projection

The mathematical projection formula which described how world coordinates are mapped to the tangent plane.

property reference_planexy

x y tangent plane coordinates where the tangent plane meets the celestial sphere. These should be in arcsec.

property reference_radec

RA DEC (world) coordinates where the tangent plane meets the celestial sphere. These should be in degrees.

set_fits_state(state)

Reads and applies the state from the get_fits_state function.

set_state(state)

Takes a state dictionary and re-creates the state of the WPCS object.

softening = 0.001

to(dtype=None, device=None)

Convert all stored tensors to a new device and data type

world_to_plane(world_RA, world_DEC=None)

Take a coordinate on the world coordinate system, also called the celesial sphere, (RA, DEC in degrees) and transform it to the cooresponding tangent plane coordinate (arcsec). Transformation is done based on the chosen projection (default gnomonic) and reference positions. See the Coordinates documentation for more details on how the transformation is performed.

astrophot.image.window_object module

class astrophot.image.window_object.Window(*, pixel_shape=None, origin=None, origin_radec=None, center=None, center_radec=None, state=None, fits_state=None, wcs=None, **kwargs)

Bases: WCS

class to define a window on the sky in coordinate space. These windows can undergo arithmetic and preserve logical behavior. Image objects can also be indexed using windows and will return an appropriate subsection of their data.

There are several ways to tell a Window object where to place itself. The simplest method is to pass an Astropy WCS object such as:

H = ap.image.Window(wcs = wcs)

this will automatically place your image at the correct RA, DEC and assign the correct pixel scale, etc. WARNING, it will default to setting the reference RA DEC at the reference RA DEC of the wcs object; if you have multiple images you should force them all to have the same reference world coordinate by passing reference_radec = (ra, dec). See the Coordinates documentation for more details. There are several other ways to initialize a window. If you provide origin_radec then it will place the image origin at the requested RA DEC coordinates. If you provide center_radec then it will place the image center at the requested RA DEC coordiantes. Note that in these cases the fixed point between the pixel grid and image plane is different (pixel origin and center respectively); so if you have rotated pixels in your pixel scale matrix then everything will be rotated about different points (pixel origin and center respectively). If you provide origin or center then those are coordiantes in the tangent plane (arcsec) and they will correspondingly become fixed points. For arbitrary control over the pixel positioning, use reference_imageij and reference_imagexy to fix the pixel and tangent plane coordinates respectively to each other, any rotation or shear will happen about that fixed point.

Parameters:

• origin – Sequence or None, optional The origin of the image in the tangent plane coordinate system (arcsec), as a 1D array of length 2. Default is None.

• origin_radec – Sequence or None, optional The origin of the image in the world coordinate system (RA, DEC in degrees), as a 1D array of length 2. Default is None.

• center – Sequence or None, optional The center of the image in the tangent plane coordinate system (arcsec), as a 1D array of length 2. Default is None.

• center_radec – Sequence or None, optional The center of the image in the world coordinate system (RA, DEC in degrees), as a 1D array of length 2. Default is None.

• wcs – An astropy.wcs.WCS object which gives information about the origin and orientation of the window.

• reference_radec – world coordinates on the celestial sphere (RA, DEC in degrees) where the tangent plane makes contact. This should be the same for every image in multi-image analysis.

• reference_planexy – tangent plane coordinates (arcsec) where it makes contact with the celesial sphere. This should typically be (0,0) though that is not stricktly enforced (it is assumed if not given). This reference coordinate should be the same for all images in multi-image analysis.

• reference_imageij – pixel coordinates about which the image is defined. For example in an Astropy WCS object the wcs.wcs.crpix array gives the pixel coordinate reference point for which the world coordinate mapping (wcs.wcs.crval) is defined. One may think of the referenced pixel location as being “pinned” to the tangent plane. This may be different for each image in multi-image analysis..

• reference_imagexy – tangent plane coordinates (arcsec) about which the image is defined. This is the pivot point about which the pixelscale matrix operates, therefore if the pixelscale matrix defines a rotation then this is the coordinate about which the rotation will be performed. This may be different for each image in multi-image analysis.

property center

copy(**kwargs)

Create a copy of the WPCS object with the same projection paramaters.

crop_pixel(pixels)

[crop all sides] or [crop x, crop y] or [crop x low, crop y low, crop x high, crop y high]

crop_to_pixel(pixels)

format: [[xmin, xmax],[ymin,ymax]]

property end

get_astropywcs(**kwargs)

get_coordinate_corner_meshgrid()

Returns a meshgrid with tangent plane coordinates for the corners of every pixel.

get_coordinate_meshgrid()

Returns a meshgrid with tangent plane coordinates for the center of every pixel.

get_coordinate_simps_meshgrid()

Returns a meshgrid with tangent plane coordinates for performing simpsons method pixel integration (all corners, centers, and middle of each edge). This is approximately 4 times more points than the standard get_coordinate_meshgrid().

get_fits_state()

Similar to get_state, except specifically tailored to be stored in a FITS format.

get_other_indices(obj)

Return an index slicing tuple for obj corresponding to this window

get_self_indices(obj)

Return an index slicing tuple for obj corresponding to this window

get_state()

Returns a dictionary with the information needed to recreate the WPCS object.

property origin

overlap_frac(other)

pad_pixel(pixels)

[pad all sides] or [pad x, pad y] or [pad x low, pad y low, pad x high, pad y high]

property pixel_shape

pixel_shift(shift)

Shift the location of the window by a specified amount in pixel grid coordinates

rescale_pixel(scale, **kwargs)

set_fits_state(state)

Reads and applies the state from the get_fits_state function.

set_state(state)

Takes a state dictionary and re-creates the state of the WPCS object.

property shape

shift(shift)

Shift the location of the window by a specified amount in tangent plane coordinates

property size

The number of pixels in the window

to(dtype=None, device=None)

Convert all stored tensors to a new device and data type

class astrophot.image.window_object.Window_List(window_list=None, state=None)

Bases: Window

property center

check_wcs()

Ensure the WCS systems being used by all the windows in this list are consistent with each other. They should all project world coordinates onto the same tangent plane.

copy()

Create a copy of the WPCS object with the same projection paramaters.

get_state()

Returns a dictionary with the information needed to recreate the WPCS object.

property origin

set_state(state)

Takes a state dictionary and re-creates the state of the WPCS object.

property shape

shift_origin(shift)

to(dtype=None, device=None)

Convert all stored tensors to a new device and data type

Module contents