Image¶
- class toasty.image.Image[source]¶
Bases:
object
A 2D data array stored in memory, potential with spatial positioning information.
This class primarily exists to help us abstract between the cases where we have “bitmap” RGB(A) images and “science” floating-point images.
Attributes Summary
Methods Summary
asarray
()Obtain the image data as a Numpy array.
aspil
()Obtain the image data as
PIL.Image.Image
.clear
()Fill the image with whatever "empty" value is most appropriate for its mode.
Ensure that this image has negative parity.
fill_into_maskable_buffer
(buffer, iy_idx, ...)Fill a maskable buffer with a rectangle of data from this image.
Invert the parity of this image without changing its appearance.
from_array
(array[, wcs, default_format, ...])Create a new Image from an array-like data variable.
from_pil
(pil_img[, wcs, default_format])Create a new Image from a PIL image.
Get this image's parity, based on its WCS.
has_wcs
()Return whether this image has attached WCS information.
Create a thumbnail bitmap from the image.
save
(path_or_stream[, format, mode, ...])Save this image to a filesystem path or stream
update_into_maskable_buffer
(buffer, iy_idx, ...)Update a maskable buffer with data from this image.
Attributes Documentation
- default_format¶
- dtype¶
- height¶
- mode¶
- shape¶
- wcs¶
- width¶
Methods Documentation
- asarray()[source]¶
Obtain the image data as a Numpy array.
- Returns:
- If the image is an RGB(A) bitmap, the array will have shape
(height, width, planes)
- and a dtype of
uint8
, whereplanes
is either 3 - or 4 depending on whether the image has an alpha channel. If the image
- is science data, it will have shape
(height, width)
and have a - floating-point dtype.
- If the image is an RGB(A) bitmap, the array will have shape
- aspil()[source]¶
Obtain the image data as
PIL.Image.Image
.- Returns:
- If the image was loaded as a PIL image, the underlying object will be
- returned. Otherwise the data array will be converted into a PIL image,
- which requires that the array have an RGB(A) format with a shape of
(height, width, planes)
, whereplanes
is 3 or 4, and a dtype ofuint8
.
- clear()[source]¶
Fill the image with whatever “empty” value is most appropriate for its mode.
Notes
The image is assumed to be writable, which will not be the case for images constructed from PIL. If the mode is RGB or RGBA, the buffer is filled with zeros. If the mode is floating-point, the buffer is filled with NaNs.
- ensure_negative_parity()[source]¶
Ensure that this image has negative parity.
- Returns:
- self, for chaining convenience.
Notes
See
get_parity_sign()
for an introduction to image parity. This method ensures that the current image has negative (JPEG-like, top-down) parity, flipping it from positive parity if needed. Only images with negative parity may be tiled in WWT.This operation requires the image to have WCS information. If none is available,
ValueError
will be raised.
- fill_into_maskable_buffer(buffer, iy_idx, ix_idx, by_idx, bx_idx)[source]¶
Fill a maskable buffer with a rectangle of data from this image.
- Parameters:
- buffer
Image
The destination buffer image, created with
ImageMode.make_maskable_buffer()
.- iy_idxslice or other indexer
The indexer into the Y axis of the source image (self).
- ix_idxslice or other indexer
The indexer into the X axis of the source image (self).
- by_idxslice or other indexer
The indexer into the Y axis of the destination buffer.
- bx_idxslice or other indexer
The indexer into the X axis of the destination buffer.
- buffer
Notes
This highly specialized function is used to tile images efficiently. No bounds checking is performed. The rectangles defined by the indexers in the source and destination are assumed to agree in size. The regions of the buffer not filled by source data are masked, namely: either filled with alpha=0 or with NaN, depending on the image mode.
- flip_parity()[source]¶
Invert the parity of this image without changing its appearance.
- Returns:
- self, for chaining convenience.
Notes
See
get_parity_sign()
for an introduction to image parity. This method flips the parity of the current image by vertically flipping both its pixel data and its WCS, so that the image’s appearance on the sky will remain the same. If the image has no WCS,ValueError
will be raised.
- classmethod from_array(array, wcs=None, default_format=None, min_value=None, max_value=None)[source]¶
Create a new Image from an array-like data variable.
- Parameters:
- arrayarray-like object
The source data. This should either be a 2-d floating point array a 3-d floating-point or uint8 array with shape (3, ny, nx), or a 3-d uint8 array with shape (4, ny, nx).
- wcs
WCS
, optional The WCS coordinate system for the image.
- default_formatstr, optional
The default format to use when writing the image if none is specified explicitly. If not specified, this is automatically chosen at write time based on the array type.
- min_valuenumber or
None
(the default) An optional number only used for FITS images. The value represents to the lowest data value in this image and its children.
- max_valuenumber or
None
(the default) An optional number only used for FITS images. The value represents to the highest data value in this image and its children.
- Returns:
- A new
Image
wrapping the data.
- A new
Notes
The array will be converted to be at least two-dimensional.
- classmethod from_pil(pil_img, wcs=None, default_format=None)[source]¶
Create a new Image from a PIL image.
- Parameters:
- pil_img
PIL.Image.Image
The source image.
- wcs
WCS
, optional The WCS coordinate system for the image.
- default_formatstr, optional
The default format to use when writing the image if none is specified explicitly.
- pil_img
- Returns:
- A new
Image
wrapping the PIL image.
- A new
- get_parity_sign()[source]¶
Get this image’s parity, based on its WCS.
- Returns:
- Either +1 or -1, depending on the image parity as defined below.
Notes
Images of the sky can have one of two “parities”. An image’s parity relates its pixel buffer coordinate system to the sky coordinate system.
If you point a digital camera at the sky, take a picture, and save it as a JPEG, the resulting image will have negative parity: if the image is not rotated, an increasing pixel X value will mean a decreasing RA (longitudinal) coordinate (because RA increases to the left), and an increasing pixel Y value will mean a decreasing declination (latitudinal) coordinate as well. Negative parity is also called “top-down” in WWT, or “JPEG-like”, and is associated with a positive determinant of the FITS “CD” matrix. If this image’s WCS coordinates indicate negative parity, this method returns -1.
FITS images of the sky are flipped in comparison: when no rotation is in effect, an increasing pixel X value still means a decreasing RA, but an increasing pixel Y value mean an increasing declination. No rotation operation can convert FITS parity to JPEG parity. This is called positive parity, AKA “bottoms-up”, and is associated with a negative determinant of the FITS CD matrix. If this image’s WCS coordinates indicate positive parity, this method returns +1.
If the image has no WCS,
ValueError
will be raised.This is all relevant because in WWT, images must be tiled in a coordinate system that has negative parity.
- has_wcs()[source]¶
Return whether this image has attached WCS information.
- Returns:
- True if this image has WCS, False otherwise.
- make_thumbnail_bitmap()[source]¶
Create a thumbnail bitmap from the image.
- Returns:
- An RGB
PIL.Image.Image
representing a thumbnail of the input - image. WWT thumbnails are 96 pixels wide and 45 pixels tall and should
- be saved in JPEG format.
- An RGB
- save(path_or_stream, format=None, mode=None, min_value=None, max_value=None)[source]¶
Save this image to a filesystem path or stream
- Parameters:
- path_or_streampath-like object or file-like object
The destination into which the data should be written. If file-like, the stream should accept bytes.
- format
str
orNone
(the default) The format name; one of
SUPPORTED_FORMATS
- mode
toasty.image.ImageMode
orNone
(the default) The image data mode to use if
format
is aPIL_FORMATS
- min_valuenumber or
None
(the default) An optional number only used for FITS images. The value represents to the lowest data value in this image and its children. If not set, the minimum value will be extracted from this image.
- max_valuenumber or
None
(the default) An optional number only used for FITS images. The value represents to the highest data value in this image and its children. If not set, the maximum value will be extracted from this image.
- update_into_maskable_buffer(buffer, iy_idx, ix_idx, by_idx, bx_idx)[source]¶
Update a maskable buffer with data from this image.
- Parameters:
- buffer
Image
The destination buffer image, created with
ImageMode.make_maskable_buffer()
.- iy_idxslice or other indexer
The indexer into the Y axis of the source image (self).
- ix_idxslice or other indexer
The indexer into the X axis of the source image (self).
- by_idxslice or other indexer
The indexer into the Y axis of the destination buffer.
- bx_idxslice or other indexer
The indexer into the X axis of the destination buffer.
- buffer
Notes
Unlike
fill_into_maskable_buffer()
, this function does not clear the entire buffer. It only overwrites the portion of the buffer covered by non-NaN-like values of the input image.