Image

class toasty.image.Image

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

default_format
dtype
height
mode
shape
wcs
width

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_negative_parity()	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.
flip_parity()	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_parity_sign()	Get this image's parity, based on its WCS.
has_wcs()	Return whether this image has attached WCS information.
make_thumbnail_bitmap()	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()

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, where planes 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.

aspil()

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), where planes is 3 or 4, and a dtype of

uint8.

clear()

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

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)

Fill a maskable buffer with a rectangle of data from this image.

Parameters:

bufferImage

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.

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

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)

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

wcsWCS, 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.

Notes

The array will be converted to be at least two-dimensional.

classmethod from_pil(pil_img, wcs=None, default_format=None)

Create a new Image from a PIL image.

Parameters:

pil_imgPIL.Image.Image

The source image.

wcsWCS, 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.

Returns:

A new Image wrapping the PIL image.

get_parity_sign()

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

Return whether this image has attached WCS information.

Returns:

True if this image has WCS, False otherwise.

make_thumbnail_bitmap()

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.

save(path_or_stream, format=None, mode=None, min_value=None, max_value=None)

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.

formatstr or None (the default)

The format name; one of SUPPORTED_FORMATS

modetoasty.image.ImageMode or None (the default)

The image data mode to use if format is a PIL_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)

Update a maskable buffer with data from this image.

Parameters:

bufferImage

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.

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.