astrophot.image package

Subpackages

• astrophot.image.func package
  • Submodules
  • astrophot.image.func.image module
    • cmos_pixel_center_meshgrid()
    • pixel_center_meshgrid()
    • pixel_corner_meshgrid()
    • pixel_quad_meshgrid()
    • pixel_simpsons_meshgrid()
    • rotate()
  • astrophot.image.func.wcs module
    • pixel_to_plane_linear()
    • plane_to_pixel_linear()
    • plane_to_world_gnomonic()
    • sip_backward_transform()
    • sip_coefs()
    • sip_delta()
    • sip_matrix()
    • world_to_plane_gnomonic()
  • Module contents
    • cmos_pixel_center_meshgrid()
    • pixel_center_meshgrid()
    • pixel_corner_meshgrid()
    • pixel_quad_meshgrid()
    • pixel_simpsons_meshgrid()
    • pixel_to_plane_linear()
    • plane_to_pixel_linear()
    • plane_to_world_gnomonic()
    • rotate()
    • sip_backward_transform()
    • sip_coefs()
    • sip_delta()
    • sip_matrix()
    • world_to_plane_gnomonic()
• astrophot.image.mixins package
  • Submodules
  • astrophot.image.mixins.cmos_mixin module
    • CMOSMixin
      • CMOSMixin.base_scale
      • CMOSMixin.copy()
      • CMOSMixin.fits_info()
      • CMOSMixin.load()
      • CMOSMixin.pixel_center_meshgrid()
      • CMOSMixin.pixel_collecting_area()
  • astrophot.image.mixins.data_mixin module
    • DataMixin
      • DataMixin.copy_kwargs()
      • DataMixin.fits_images()
      • DataMixin.get_window()
      • DataMixin.load()
      • DataMixin.mask
      • DataMixin.reduce()
      • DataMixin.std
      • DataMixin.to()
      • DataMixin.variance
      • DataMixin.weight
  • astrophot.image.mixins.sip_mixin module
    • SIPMixin
      • SIPMixin.A_ORDER
      • SIPMixin.B_ORDER
      • SIPMixin.compute_backward_sip_coefs()
      • SIPMixin.copy_kwargs()
      • SIPMixin.expect_ctype
      • SIPMixin.fits_info()
      • SIPMixin.get_window()
      • SIPMixin.load()
      • SIPMixin.pixel_area_map
      • SIPMixin.pixel_collecting_area()
      • SIPMixin.pixel_to_plane()
      • SIPMixin.plane_to_pixel()
      • SIPMixin.to()
      • SIPMixin.update_distortion_model()
  • Module contents
    • CMOSMixin
      • CMOSMixin.base_scale
      • CMOSMixin.copy()
      • CMOSMixin.fits_info()
      • CMOSMixin.load()
      • CMOSMixin.pixel_center_meshgrid()
      • CMOSMixin.pixel_collecting_area()
    • DataMixin
      • DataMixin.copy_kwargs()
      • DataMixin.fits_images()
      • DataMixin.get_window()
      • DataMixin.load()
      • DataMixin.mask
      • DataMixin.reduce()
      • DataMixin.std
      • DataMixin.to()
      • DataMixin.variance
      • DataMixin.weight
    • SIPMixin
      • SIPMixin.A_ORDER
      • SIPMixin.B_ORDER
      • SIPMixin.compute_backward_sip_coefs()
      • SIPMixin.copy_kwargs()
      • SIPMixin.expect_ctype
      • SIPMixin.fits_info()
      • SIPMixin.get_window()
      • SIPMixin.load()
      • SIPMixin.pixel_area_map
      • SIPMixin.pixel_collecting_area()
      • SIPMixin.pixel_to_plane()
      • SIPMixin.plane_to_pixel()
      • SIPMixin.to()
      • SIPMixin.update_distortion_model()

Submodules

astrophot.image.cmos_image module

class astrophot.image.cmos_image.CMOSModelImage(*args, subpixel_loc: Tuple[float, float] = (0, 0), subpixel_scale: float = 1.0, filename: str | None = None, **kwargs)

Bases: CMOSMixin, ModelImage

A ModelImage with CMOS-specific functionality.

CMOSMixin

A mixin class for CMOS image processing. This class can be used to add CMOS-specific functionality to image processing classes.

ModelImage

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.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

class astrophot.image.cmos_image.CMOSTargetImage(*args, subpixel_loc: Tuple[float, float] = (0, 0), subpixel_scale: float = 1.0, filename: str | None = None, **kwargs)

Bases: CMOSMixin, TargetImage

A TargetImage with CMOS-specific functionality. This class is used to represent a target image with CMOS-specific features. It inherits from TargetImage and CMOSMixin.

CMOSMixin

A mixin class for CMOS image processing. This class can be used to add CMOS-specific functionality to image processing classes.

TargetImage

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 minimal functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

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.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

model_image(window: Window, **kwargs) → CMOSModelImage

Model the image with CMOS-specific features.

astrophot.image.image_object module

class astrophot.image.image_object.Image(*, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, CD: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, zeropoint: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), pixelscale: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = 1.0, wcs: WCS | None = None, filename: str | None = None, hduext: int = 0, identity: str = None, name: str | None = None, _data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None)

Bases: Module

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

base_scale = 1.0

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

coordinate_center_meshgrid() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, centered on the pixel grid.

coordinate_corner_meshgrid() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, with corners at the pixel grid.

coordinate_quad_meshgrid(order=3) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, with quadrature sampling.

coordinate_simpsons_meshgrid() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, with Simpson’s rule sampling.

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.

copy_kwargs(**kwargs) → dict

corners() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

crop(pixels: int | Tuple[int, int] | Tuple[int, int, int, int], **kwargs)

Crop the image by the number of pixels given. This will crop the image in all four directions by the number of pixels given.

given data shape (N, M) the new shape will be:

crop - int: crop the same number of pixels on all sides. new shape (N - 2*crop, M - 2*crop) crop - (int, int): crop each dimension by the number of pixels given. new shape (N - 2*crop[1], M - 2*crop[0]) crop - (int, int, int, int): crop each side by the number of pixels given assuming (x low, x high, y low, y high). new shape (N - crop[2] - crop[3], M - crop[0] - crop[1])

property crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates.

property data

The image data, which is a Array of pixel values.

expect_ctype = (('RA---TAN',), ('DEC--TAN',))

fits_images()

fits_info() → dict

flatten(attribute: str = 'data') → Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

property flip_ra_axis

get_astropywcs(**kwargs)

get_indices(other: Window)

get_other_indices(other: Window)

get_window(other: Window | Image, indices=None, **kwargs)

Get a new image object which is a window of this image corresponding to the other image’s window. This will return a new image object with the same properties as this one, but with the data cropped to the other image’s window.

property identity

load(filename: str | HDUList, hduext: int = 0)

Load an image from a FITS file. This will load the primary HDU and set the data, CD, crpix, crval, and crtan attributes accordingly. If the WCS is not tangent plane, it will warn the user.

property pixel_area

The area inside a pixel in arcsec^2

pixel_center_meshgrid(window=None, pad=0, upsample=1) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, centered on the pixel grid.

pixel_collecting_area(I_, J_, upsample, CD)

The area of the sky that each pixel collects light from, in arcsec^2. This is just the pixel area, but can be overridden for certain types of images (e.g. SIP images) where the pixel collecting area is not the same as the pixel area.

pixel_corner_meshgrid(window=None, pad=0, upsample=1) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with corners at the pixel grid.

pixel_quad_meshgrid(window=None, pad=0, upsample=1, order=3) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with quadrature sampling.

pixel_simpsons_meshgrid(window=None, pad=0, upsample=1) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with Simpson’s rule sampling.

pixel_to_plane(i: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], j: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], CD: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], _crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

pixel_to_world(i: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], j: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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

property pixelscale

The approximate side 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 pixelscale is not used for exact calculations and instead sets a size scale within an image.

plane_to_pixel(x: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], y: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], CD: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], _crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

plane_to_world(x: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], y: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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 Array. Note that the window does not change in this operation since the pixels are condensed, but the pixel size is increased correspondingly.

Parameters:

scale (int) – The scale factor by which to reduce the image.

save(filename: str)

to(dtype=None, device=None)

Moves and/or casts the values of the Node to a particular device and/or dtype.

Parameters

device: (Optional[torch.device], optional)

The device to move the values to. Defaults to None.

dtype: (Optional[torch.dtype], optional)

The desired data type. Defaults to None.

property window: Window

world_to_pixel(ra: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], dec: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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

world_to_plane(ra: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], dec: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

property zeropoint: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

The zeropoint of the image, which is used to convert from pixel flux to magnitude.

class astrophot.image.image_object.ImageList(images: list[Image], **kwargs)

Bases: Module

A class to represent a list of images.

This is useful for operations that involve multiple images, mostly for joint modelling. The ImageList class provides methods for matching images based on their identity, and for applying operations to all images in the list while preserving their individual properties. For certain applications (the flatten method) you can use ImageList and Image objects interchangably/agnostically.

blank_copy()

copy()

property data

flatten(attribute: str = 'data') → Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

get_window(other: ImageList)

index(other: Image)

match_indices(other: ImageList)

Match the indices of the images in this list with those in another ImageList.

to(dtype=None, device=None)

Moves and/or casts the values of the Node to a particular device and/or dtype.

Parameters

device: (Optional[torch.device], optional)

The device to move the values to. Defaults to None.

dtype: (Optional[torch.dtype], optional)

The desired data type. Defaults to None.

property window

astrophot.image.jacobian_image module

class astrophot.image.jacobian_image.JacobianImage(parameters: List[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) Array. This object can be added other other Jacobian images to build up a full jacobian for a complex model.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

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')

match_parameters(other: JacobianImage | JacobianImageList | List)

plane_to_world(x, y)

world_to_plane(ra, dec)

class astrophot.image.jacobian_image.JacobianImageList(*args, **kwargs)

Bases: ImageList

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: str = 'data')

match_parameters(other: JacobianImage | JacobianImageList | List[str])

property parameters: List[str]

List of parameters for the jacobian images in this list.

astrophot.image.model_image module

class astrophot.image.model_image.ModelImage(*, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, CD: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, zeropoint: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), pixelscale: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = 1.0, wcs: WCS | None = None, filename: str | None = None, hduext: int = 0, identity: str = None, name: str | None = None, _data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None)

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.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

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

Bases: ImageList

A list of ModelImage objects.

ImageList

A class to represent a list of images.

This is useful for operations that involve multiple images, mostly for joint modelling. The ImageList class provides methods for matching images based on their identity, and for applying operations to all images in the list while preserving their individual properties. For certain applications (the flatten method) you can use ImageList and Image objects interchangably/agnostically.

astrophot.image.psf_image module

class astrophot.image.psf_image.PSFImage(*, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, upsample: int = 1, crpix: tuple[int, int] | None = None, filename: str | None = None, hduext: int = 0, identity: str = None, _data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, **kwargs)

Bases: DataMixin

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

PSFImage 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 should be odd (for your sanity) but this is not enforced.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Parameters:

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

base_scale = 1.0

coordinate_center_meshgrid() → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

coordinate_corner_meshgrid() → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

coordinate_quad_meshgrid(order=3) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

coordinate_simpsons_meshgrid() → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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.

copy_kwargs(**kwargs) → dict

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.

property crpix

property data

The image data, which is a Array of pixel values.

fits_info() → dict

flatten(attribute: str = 'data') → Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

property flip_ra_axis

get_indices(other: Window)

get_window(other: Window | Image, indices=None, **kwargs)

Get a new image object which is a window of this image corresponding to the other image’s window. This will return a new image object with the same properties as this one, but with the data cropped to the other image’s window.

property identity

jacobian_image(parameters: List[str] | None = None, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, **kwargs) → JacobianImage

Construct a blank JacobianImage object formatted like this current PSFImage object. Mostly used internally.

model_image(window=None, **kwargs) → PSFImage

Construct a blank ModelImage object formatted like this current TargetImage object. Mostly used internally.

mypixel_to_targpixel(i, j)

Convert between coordinate spaces. “targpixel” refers to the pixel coordinates of the target of this PSF, which have the origin at the center of the PSF and a step of 1 corresponds to one target pixel length. “mypixel” refers to the pixel coordinates of this PSF image, which have an origin at the center of the [0,0] pixel and a step of 1 corresponds to one PSF pixel length (which is 1/upsample of a target pixel length).

normalize()

Normalizes the PSF image to have a sum of 1.

property pad: int

property pixel_area

pixel_center_meshgrid(window=None, pad=0, upsample=1) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, centered on the pixel grid.

pixel_collecting_area(*args, **kwargs)

pixel_corner_meshgrid(window=None, pad=0, upsample=1) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with corners at the pixel grid.

pixel_quad_meshgrid(window=None, pad=0, upsample=1, order=3) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with quadrature sampling.

pixel_simpsons_meshgrid(window=None, pad=0, upsample=1) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with Simpson’s rule sampling.

property pixelscale

reduce(scale: int)

Returns a new TargetImage object with a reduced resolution compared to the current image. scale should be an integer indicating how much to reduce the resolution. If the TargetImage 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.

targpixel_to_mypixel(I_, J_)

Convert between coordinate spaces. “targpixel” refers to the pixel coordinates of the target of this PSF, which have the origin at the center of the PSF and a step of 1 corresponds to one target pixel length. “mypixel” refers to the pixel coordinates of this PSF image, which have an origin at the center of the [0,0] pixel and a step of 1 corresponds to one PSF pixel length (which is 1/upsample of a target pixel length).

property upsample: int

property window: Window

property zeropoint

astrophot.image.sip_image module

class astrophot.image.sip_image.SIPModelImage(*args, sipA: dict[Tuple[int, int], float] = {}, sipB: dict[Tuple[int, int], float] = {}, sipAP: dict[Tuple[int, int], float] = {}, sipBP: dict[Tuple[int, int], float] = {}, pixel_area_map: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_ij: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_IJ: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, filename: str | None = None, **kwargs)

Bases: SIPMixin, ModelImage

A ModelImage with SIP distortion coefficients.

SIPMixin

A mixin class for SIP (Simple Image Polynomial) distortion model.

ModelImage

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.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

crop(pixels: int | Tuple[int, int] | Tuple[int, int, int, int], **kwargs)

Crop the image by the number of pixels given. This will crop the image in all four directions by the number of pixels given.

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 Array. 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]

class astrophot.image.sip_image.SIPTargetImage(*args, sipA: dict[Tuple[int, int], float] = {}, sipB: dict[Tuple[int, int], float] = {}, sipAP: dict[Tuple[int, int], float] = {}, sipBP: dict[Tuple[int, int], float] = {}, pixel_area_map: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_ij: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_IJ: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, filename: str | None = None, **kwargs)

Bases: SIPMixin, TargetImage

A TargetImage with SIP distortion coefficients. This class is used to represent a target image with SIP distortion coefficients. It inherits from TargetImage and SIPMixin.

SIPMixin

A mixin class for SIP (Simple Image Polynomial) distortion model.

TargetImage

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 minimal functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

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.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

model_image(upsample: int = 1, pad: int = 0, **kwargs) → SIPModelImage

Construct a blank ModelImage object formatted like this current TargetImage object. Mostly used internally.

astrophot.image.target_image module

class astrophot.image.target_image.TargetImage(*args, psf=None, **kwargs)

Bases: DataMixin, 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 minimal functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

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.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

copy_kwargs(**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.

fits_images()

property has_psf: bool

Returns True when the target image object has a PSF model.

jacobian_image(parameters: List[str], data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, **kwargs) → JacobianImage

Construct a blank JacobianImage object formatted like this current TargetImage object. Mostly used internally.

load(filename: str, hduext: int = 0)

Load the image from a FITS file. This will load the data, WCS, and any ancillary data such as variance, mask, and PSF.

model_image(window: Window = None, **kwargs) → ModelImage

Construct a blank ModelImage object formatted like this current TargetImage object. Mostly used internally.

property psf

psf_image(data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], upsample: int = 1, **kwargs) → PSFImage

reduce(scale: int, **kwargs) → TargetImage

Returns a new TargetImage object with a reduced resolution compared to the current image. scale should be an integer indicating how much to reduce the resolution. If the TargetImage 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.

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

Bases: ImageBatchMixin, TargetImageList

jacobian_image(parameters: List[str], data: List[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']] | None = None) → JacobianImageBatch

property mask

model_image(window=None) → ModelImageBatch

property psf_stack

property variance

property weight

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

Bases: ImageList

ImageList

A class to represent a list of images.

This is useful for operations that involve multiple images, mostly for joint modelling. The ImageList class provides methods for matching images based on their identity, and for applying operations to all images in the list while preserving their individual properties. For certain applications (the flatten method) you can use ImageList and Image objects interchangably/agnostically.

property has_psf: bool

jacobian_image(parameters: List[str], data: List[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']] | None = None) → JacobianImageList

property mask

model_image(window=None) → ModelImageList

property psf

property variance

property weight

astrophot.image.window module

class astrophot.image.window.Window(window: Tuple[int, int, int, int] | Tuple[Tuple[int, int], Tuple[int, int]], image: Image)

Bases: object

chunk(chunk_size: int) → List[Window]

copy()

property crpix

property extent

property identity

pad(pad: int)

property shape

class astrophot.image.window.WindowBatch(windows: list[Window])

Bases: WindowList

origin_shifter(other: Window) → ndarray

Returns the shift in origin between this window batch and another window.

class astrophot.image.window.WindowList(windows: list[Window])

Bases: object

index(other: Window) → int

Module contents

class astrophot.image.CMOSModelImage(*args, subpixel_loc: Tuple[float, float] = (0, 0), subpixel_scale: float = 1.0, filename: str | None = None, **kwargs)

Bases: CMOSMixin, ModelImage

A ModelImage with CMOS-specific functionality.

CMOSMixin

A mixin class for CMOS image processing. This class can be used to add CMOS-specific functionality to image processing classes.

ModelImage

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.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

class astrophot.image.CMOSTargetImage(*args, subpixel_loc: Tuple[float, float] = (0, 0), subpixel_scale: float = 1.0, filename: str | None = None, **kwargs)

Bases: CMOSMixin, TargetImage

A TargetImage with CMOS-specific functionality. This class is used to represent a target image with CMOS-specific features. It inherits from TargetImage and CMOSMixin.

CMOSMixin

A mixin class for CMOS image processing. This class can be used to add CMOS-specific functionality to image processing classes.

TargetImage

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 minimal functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

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.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

model_image(window: Window, **kwargs) → CMOSModelImage

Model the image with CMOS-specific features.

class astrophot.image.Image(*, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, CD: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, zeropoint: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), pixelscale: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = 1.0, wcs: WCS | None = None, filename: str | None = None, hduext: int = 0, identity: str = None, name: str | None = None, _data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None)

Bases: Module

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

base_scale = 1.0

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

coordinate_center_meshgrid() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, centered on the pixel grid.

coordinate_corner_meshgrid() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, with corners at the pixel grid.

coordinate_quad_meshgrid(order=3) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, with quadrature sampling.

coordinate_simpsons_meshgrid() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of coordinate locations in the image, with Simpson’s rule sampling.

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.

copy_kwargs(**kwargs) → dict

corners() → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

crop(pixels: int | Tuple[int, int] | Tuple[int, int, int, int], **kwargs)

Crop the image by the number of pixels given. This will crop the image in all four directions by the number of pixels given.

given data shape (N, M) the new shape will be:

crop - int: crop the same number of pixels on all sides. new shape (N - 2*crop, M - 2*crop) crop - (int, int): crop each dimension by the number of pixels given. new shape (N - 2*crop[1], M - 2*crop[0]) crop - (int, int, int, int): crop each side by the number of pixels given assuming (x low, x high, y low, y high). new shape (N - crop[2] - crop[3], M - crop[0] - crop[1])

property crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates.

property data

The image data, which is a Array of pixel values.

expect_ctype = (('RA---TAN',), ('DEC--TAN',))

fits_images()

fits_info() → dict

flatten(attribute: str = 'data') → Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

property flip_ra_axis

get_astropywcs(**kwargs)

get_indices(other: Window)

get_other_indices(other: Window)

get_window(other: Window | Image, indices=None, **kwargs)

Get a new image object which is a window of this image corresponding to the other image’s window. This will return a new image object with the same properties as this one, but with the data cropped to the other image’s window.

property identity

load(filename: str | HDUList, hduext: int = 0)

Load an image from a FITS file. This will load the primary HDU and set the data, CD, crpix, crval, and crtan attributes accordingly. If the WCS is not tangent plane, it will warn the user.

property pixel_area

The area inside a pixel in arcsec^2

pixel_center_meshgrid(window=None, pad=0, upsample=1) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, centered on the pixel grid.

pixel_collecting_area(I_, J_, upsample, CD)

The area of the sky that each pixel collects light from, in arcsec^2. This is just the pixel area, but can be overridden for certain types of images (e.g. SIP images) where the pixel collecting area is not the same as the pixel area.

pixel_corner_meshgrid(window=None, pad=0, upsample=1) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with corners at the pixel grid.

pixel_quad_meshgrid(window=None, pad=0, upsample=1, order=3) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with quadrature sampling.

pixel_simpsons_meshgrid(window=None, pad=0, upsample=1) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with Simpson’s rule sampling.

pixel_to_plane(i: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], j: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], CD: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], _crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

pixel_to_world(i: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], j: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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

property pixelscale

The approximate side 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 pixelscale is not used for exact calculations and instead sets a size scale within an image.

plane_to_pixel(x: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], y: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], CD: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], _crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

plane_to_world(x: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], y: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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 Array. Note that the window does not change in this operation since the pixels are condensed, but the pixel size is increased correspondingly.

Parameters:

scale (int) – The scale factor by which to reduce the image.

save(filename: str)

to(dtype=None, device=None)

Moves and/or casts the values of the Node to a particular device and/or dtype.

Parameters

device: (Optional[torch.device], optional)

The device to move the values to. Defaults to None.

dtype: (Optional[torch.dtype], optional)

The desired data type. Defaults to None.

property window: Window

world_to_pixel(ra: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], dec: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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

world_to_plane(ra: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], dec: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']) → Tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

property zeropoint: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

The zeropoint of the image, which is used to convert from pixel flux to magnitude.

class astrophot.image.ImageBatchMixin(*args, **kwargs)

Bases: object

Specialized ImageList type where the images are all the same size.

An ImageBatch has restrictions on the shape of the images it can hold, but in exchange it allows vectorized operations over a batch of images.

Some notes to keep in mind: - All the images must be the regular image type (i.e. not SIP or CMOS images yet). - All the images must have the same shape, otherwise the batch operations will not work. - The ImageBatch does not itself accelerate any operations, it facilitates the BatchSceneModel. - Otherwise the ImageBatch behaves like a regular ImageList.

property CD

property crpix

property crtan

property crval

property data

property window

class astrophot.image.ImageList(images: list[Image], **kwargs)

Bases: Module

A class to represent a list of images.

This is useful for operations that involve multiple images, mostly for joint modelling. The ImageList class provides methods for matching images based on their identity, and for applying operations to all images in the list while preserving their individual properties. For certain applications (the flatten method) you can use ImageList and Image objects interchangably/agnostically.

blank_copy()

copy()

property data

flatten(attribute: str = 'data') → Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

get_window(other: ImageList)

index(other: Image)

match_indices(other: ImageList)

Match the indices of the images in this list with those in another ImageList.

to(dtype=None, device=None)

Moves and/or casts the values of the Node to a particular device and/or dtype.

Parameters

device: (Optional[torch.device], optional)

The device to move the values to. Defaults to None.

dtype: (Optional[torch.dtype], optional)

The desired data type. Defaults to None.

property window

class astrophot.image.JacobianImage(parameters: List[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) Array. This object can be added other other Jacobian images to build up a full jacobian for a complex model.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

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')

match_parameters(other: JacobianImage | JacobianImageList | List)

plane_to_world(x, y)

world_to_plane(ra, dec)

class astrophot.image.JacobianImageBatch(*args, **kwargs)

Bases: ImageBatchMixin, JacobianImageList

class astrophot.image.JacobianImageList(*args, **kwargs)

Bases: ImageList

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: str = 'data')

match_parameters(other: JacobianImage | JacobianImageList | List[str])

property parameters: List[str]

List of parameters for the jacobian images in this list.

class astrophot.image.ModelImage(*, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, CD: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, zeropoint: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, crpix: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crtan: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), crval: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | tuple = (0.0, 0.0), pixelscale: float | Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = 1.0, wcs: WCS | None = None, filename: str | None = None, hduext: int = 0, identity: str = None, name: str | None = None, _data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None)

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.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

class astrophot.image.ModelImageBatch(*args, **kwargs)

Bases: ImageBatchMixin, ModelImageList

ImageBatchMixin

Specialized ImageList type where the images are all the same size.

An ImageBatch has restrictions on the shape of the images it can hold, but in exchange it allows vectorized operations over a batch of images.

Some notes to keep in mind: - All the images must be the regular image type (i.e. not SIP or CMOS images yet). - All the images must have the same shape, otherwise the batch operations will not work. - The ImageBatch does not itself accelerate any operations, it facilitates the BatchSceneModel. - Otherwise the ImageBatch behaves like a regular ImageList.

ModelImageList

A list of ModelImage objects.

ImageList

A class to represent a list of images.

This is useful for operations that involve multiple images, mostly for joint modelling. The ImageList class provides methods for matching images based on their identity, and for applying operations to all images in the list while preserving their individual properties. For certain applications (the flatten method) you can use ImageList and Image objects interchangably/agnostically.

class astrophot.image.ModelImageList(*args, **kwargs)

Bases: ImageList

A list of ModelImage objects.

ImageList

A class to represent a list of images.

This is useful for operations that involve multiple images, mostly for joint modelling. The ImageList class provides methods for matching images based on their identity, and for applying operations to all images in the list while preserving their individual properties. For certain applications (the flatten method) you can use ImageList and Image objects interchangably/agnostically.

class astrophot.image.PSFImage(*, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, upsample: int = 1, crpix: tuple[int, int] | None = None, filename: str | None = None, hduext: int = 0, identity: str = None, _data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, **kwargs)

Bases: DataMixin

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

PSFImage 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 should be odd (for your sanity) but this is not enforced.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Parameters:

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

base_scale = 1.0

coordinate_center_meshgrid() → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

coordinate_corner_meshgrid() → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

coordinate_quad_meshgrid(order=3) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

coordinate_simpsons_meshgrid() → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

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.

copy_kwargs(**kwargs) → dict

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.

property crpix

property data

The image data, which is a Array of pixel values.

fits_info() → dict

flatten(attribute: str = 'data') → Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']

property flip_ra_axis

get_indices(other: Window)

get_window(other: Window | Image, indices=None, **kwargs)

Get a new image object which is a window of this image corresponding to the other image’s window. This will return a new image object with the same properties as this one, but with the data cropped to the other image’s window.

property identity

jacobian_image(parameters: List[str] | None = None, data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, **kwargs) → JacobianImage

Construct a blank JacobianImage object formatted like this current PSFImage object. Mostly used internally.

model_image(window=None, **kwargs) → PSFImage

Construct a blank ModelImage object formatted like this current TargetImage object. Mostly used internally.

mypixel_to_targpixel(i, j)

Convert between coordinate spaces. “targpixel” refers to the pixel coordinates of the target of this PSF, which have the origin at the center of the PSF and a step of 1 corresponds to one target pixel length. “mypixel” refers to the pixel coordinates of this PSF image, which have an origin at the center of the [0,0] pixel and a step of 1 corresponds to one PSF pixel length (which is 1/upsample of a target pixel length).

normalize()

Normalizes the PSF image to have a sum of 1.

property pad: int

property pixel_area

pixel_center_meshgrid(window=None, pad=0, upsample=1) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, centered on the pixel grid.

pixel_collecting_area(*args, **kwargs)

pixel_corner_meshgrid(window=None, pad=0, upsample=1) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with corners at the pixel grid.

pixel_quad_meshgrid(window=None, pad=0, upsample=1, order=3) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with quadrature sampling.

pixel_simpsons_meshgrid(window=None, pad=0, upsample=1) → tuple[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']]

Get a meshgrid of pixel coordinates in the image, with Simpson’s rule sampling.

property pixelscale

reduce(scale: int)

Returns a new TargetImage object with a reduced resolution compared to the current image. scale should be an integer indicating how much to reduce the resolution. If the TargetImage 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.

targpixel_to_mypixel(I_, J_)

Convert between coordinate spaces. “targpixel” refers to the pixel coordinates of the target of this PSF, which have the origin at the center of the PSF and a step of 1 corresponds to one target pixel length. “mypixel” refers to the pixel coordinates of this PSF image, which have an origin at the center of the [0,0] pixel and a step of 1 corresponds to one PSF pixel length (which is 1/upsample of a target pixel length).

property upsample: int

property window: Window

property zeropoint

class astrophot.image.SIPModelImage(*args, sipA: dict[Tuple[int, int], float] = {}, sipB: dict[Tuple[int, int], float] = {}, sipAP: dict[Tuple[int, int], float] = {}, sipBP: dict[Tuple[int, int], float] = {}, pixel_area_map: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_ij: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_IJ: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, filename: str | None = None, **kwargs)

Bases: SIPMixin, ModelImage

A ModelImage with SIP distortion coefficients.

SIPMixin

A mixin class for SIP (Simple Image Polynomial) distortion model.

ModelImage

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.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

crop(pixels: int | Tuple[int, int] | Tuple[int, int, int, int], **kwargs)

Crop the image by the number of pixels given. This will crop the image in all four directions by the number of pixels given.

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 Array. 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]

class astrophot.image.SIPTargetImage(*args, sipA: dict[Tuple[int, int], float] = {}, sipB: dict[Tuple[int, int], float] = {}, sipAP: dict[Tuple[int, int], float] = {}, sipBP: dict[Tuple[int, int], float] = {}, pixel_area_map: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_ij: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, distortion_IJ: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, filename: str | None = None, **kwargs)

Bases: SIPMixin, TargetImage

A TargetImage with SIP distortion coefficients. This class is used to represent a target image with SIP distortion coefficients. It inherits from TargetImage and SIPMixin.

SIPMixin

A mixin class for SIP (Simple Image Polynomial) distortion model.

TargetImage

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 minimal functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

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.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

model_image(upsample: int = 1, pad: int = 0, **kwargs) → SIPModelImage

Construct a blank ModelImage object formatted like this current TargetImage object. Mostly used internally.

class astrophot.image.TargetImage(*args, psf=None, **kwargs)

Bases: DataMixin, 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 minimal functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

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.

DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Image

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:

• crval – The reference coordinate of the image in degrees [RA, DEC]. [model param]

• crtan – The tangent plane coordinate of the image in arcseconds [x, y]. [model param]

• CD – The coordinate transformation matrix in arcseconds/pixel. [model param]

• crpix – The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates. This is not a model param and is fixed for a given image.

• data – The image data as a Array of pixel values. If not provided, a Array of zeros will be created.

• zeropoint – The zeropoint of the image, which is used to convert from pixel flux to magnitude.

• pixelscale – The side length of a pixel, used to create a simple diagonal CD matrix.

• wcs – An optional Astropy WCS object to initialize the image.

• filename – The filename to load the image from. If provided, the image will be loaded from the file.

• hduext – The HDU extension to load from the FITS file specified in filename.

• identity – An optional identity string for the image (mostly used internally).

• mask – A boolean mask indicating which pixels to ignore.

• std – Standard deviation of the image pixels.

• variance – Variance of the image pixels.

• weight – Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

copy_kwargs(**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.

fits_images()

property has_psf: bool

Returns True when the target image object has a PSF model.

jacobian_image(parameters: List[str], data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'] | None = None, **kwargs) → JacobianImage

Construct a blank JacobianImage object formatted like this current TargetImage object. Mostly used internally.

load(filename: str, hduext: int = 0)

Load the image from a FITS file. This will load the data, WCS, and any ancillary data such as variance, mask, and PSF.

model_image(window: Window = None, **kwargs) → ModelImage

Construct a blank ModelImage object formatted like this current TargetImage object. Mostly used internally.

property psf

psf_image(data: Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.'], upsample: int = 1, **kwargs) → PSFImage

reduce(scale: int, **kwargs) → TargetImage

Returns a new TargetImage object with a reduced resolution compared to the current image. scale should be an integer indicating how much to reduce the resolution. If the TargetImage 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.

class astrophot.image.TargetImageBatch(*args, **kwargs)

Bases: ImageBatchMixin, TargetImageList

jacobian_image(parameters: List[str], data: List[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']] | None = None) → JacobianImageBatch

property mask

model_image(window=None) → ModelImageBatch

property psf_stack

property variance

property weight

class astrophot.image.TargetImageList(*args, **kwargs)

Bases: ImageList

ImageList

A class to represent a list of images.

This is useful for operations that involve multiple images, mostly for joint modelling. The ImageList class provides methods for matching images based on their identity, and for applying operations to all images in the list while preserving their individual properties. For certain applications (the flatten method) you can use ImageList and Image objects interchangably/agnostically.

property has_psf: bool

jacobian_image(parameters: List[str], data: List[Annotated[Tensor, 'One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.']] | None = None) → JacobianImageList

property mask

model_image(window=None) → ModelImageList

property psf

property variance

property weight

class astrophot.image.Window(window: Tuple[int, int, int, int] | Tuple[Tuple[int, int], Tuple[int, int]], image: Image)

Bases: object

chunk(chunk_size: int) → List[Window]

copy()

property crpix

property extent

property identity

pad(pad: int)

property shape

class astrophot.image.WindowBatch(windows: list[Window])

Bases: WindowList

origin_shifter(other: Window) → ndarray

Returns the shift in origin between this window batch and another window.

class astrophot.image.WindowList(windows: list[Window])

Bases: object

index(other: Window) → int