Python API Reference

toasty Package

toasty.builder Module

Building up WWT imagery data sets.

This gets a little complex since the generation of a tiled image involves several tasks that may or may not be implemented in several, swappable ways: generating the tiled pixel data; positioning the image on the sky; filling in metadata; and so on. We try to provide a framework that allows the implementations of different tasks to be swapped out without getting too airy and abstract.

Classes

Builder(pio)

State for some kind of imagery data set that’s being assembled.

toasty.cli Module

Entrypoint for the “toasty” command-line interface.

Functions

cascade_getparser(parser)
cascade_impl(settings)
die(msg)
entrypoint([args])	The entrypoint for the “toasty” command-line interface.
healpix_sample_data_tiles_getparser(parser)
healpix_sample_data_tiles_impl(settings)
make_thumbnail_getparser(parser)
make_thumbnail_impl(settings)
multi_tan_make_data_tiles_getparser(parser)
multi_tan_make_data_tiles_impl(settings)
pipeline_fetch_inputs_getparser(parser)
pipeline_fetch_inputs_impl(settings)
pipeline_process_todos_getparser(parser)
pipeline_process_todos_impl(settings)
pipeline_publish_todos_getparser(parser)
pipeline_publish_todos_impl(settings)
pipeline_reindex_getparser(parser)
pipeline_reindex_impl(settings)
tile_allsky_getparser(parser)
tile_allsky_impl(settings)
tile_study_getparser(parser)
tile_study_impl(settings)
tile_wwtl_getparser(parser)
tile_wwtl_impl(settings)
warn(msg)

toasty.image Module

Low-level loading and handling of images.

Here, images are defined as 2D data buffers stored in memory. Images might be small, if dealing with an individual tile, or extremely large, if loading up a large study for tiling.

Classes

Image()	A 2D data array stored in memory.
ImageLoader()	A class defining how to load an image.
ImageMode(value)	Allowed image “modes”, describing their pixel data formats.

toasty.merge Module

General tools for merging and downsampling tiles

The Merger Protocol

A “merger” is a callable that takes four input tiles and downsamples them into a smaller tile. Its prototype is merger(big) -> small, where big is a Numpy array of at least 2 dimensions whose first two axes are both 512 elements in size. The return value small should have the same number of dimensions as the input, two initial axes of size 256, and remaining axes the same size as the input.

To efficiently vectorize two-by-two downsampling, a useful trick is to reshape the (512, 512) input tile into a shape (256, 2, 256, 2). You can then use functions like np.mean() with an argument axes=(1, 3) to vectorize the operation over sets of four adjacent pixels.

Functions

averaging_merger(data)	A merger function that averages quartets of pixels.
cascade_images(pio, mode, start, merger[, …])	Downsample image tiles all the way to the top of the pyramid.

toasty.multi_tan Module

Generate tiles from a collection of images on a common TAN projection.

TODO: shuld be migrated to wwt_data_formats.

Classes

MultiTanDataSource(paths[, hdu_index])

Generate tiles from a collection of images on a common TAN projection.

toasty.openexr Module

Loading OpenEXR files.

This is very primitive support. Implemented for:

https://svs.gsfc.nasa.gov/4851

Functions

load_openexr(path)

Load an OpenEXR file

toasty.pipeline Module

A framework for automating the ingest of source images into the formats used by AAS WorldWide Telescope.

Classes

AstroPixImageSource()	An ImageSource that obtains its inputs from a query to the AstroPix service.
AstroPixInputImage(unique_id, cachedir, …)	An InputImage obtained from an AstroPix query result.
AstroPixCandidateInput(json_dict)	A CandidateInput obtained from an AstroPix query.
AzureBlobPipelineIo(connection_string, …)	I/O for pipeline processing that uses Microsoft Azure Blob Storage.
BitmapInputImage(unique_id, cachedir)	An abstract base class for an input image whose data are stored as an RGB bitmap that we will read into memory all at once using the PIL module.
CandidateInput()	An abstract base class representing an image from one of our sources.
ImageSource()	An abstract base class representing a source of images to be processed in the image-processing pipeline.
InputImage(unique_id, cachedir)	An abstract base class representing an image to be processed by the pipeline.
LocalPipelineIo(path_prefix)	I/O for pipeline processing using the local disk.
NotActionableError	Raised when an image is provided to the pipeline but for some reason we’re not going to be able to get it into a WWT-compatible form.
PipelineIo()	An abstract base class for I/O relating to pipeline processing.

toasty.pyramid Module

General tools for working with tile pyramids.

Toasty and the AAS WorldWide Telescope support two kinds of tile pyramid formats: the all-sky TOAST projection, and “studies” which are tile pyramids rooted in a subset of the sky using a tangential projection. Both kinds of tile pyramids have much in common, and this module implements their overlapping functionality.

Functions

depth2tiles(depth)	Return the total number of tiles in a WWT tile pyramid of depth depth.
generate_pos(depth)	Generate a pyramid of tile positions.
is_subtile(deeper_pos, shallower_pos)	Determine if one tile is a child of another.
next_highest_power_of_2(n)	Ugh, this implementation is so dumb.
pos_children(pos)	Return the children of a tile position.
pos_parent(pos)	Return a tile position’s parent.
tiles_at_depth(depth)	Return the number of tiles in the WWT tile pyramid layer at depth depth.

Classes

Pos(n, x, y)
PyramidIO(base_dir[, scheme])	Manage I/O on a tile pyramid.

toasty.samplers Module

“Sampler” functions that fetch image data as a function of sky coordinates.

The Sampler Protocol

A sampler is a callable object that obeys the following signature: func(lon, lat) -> data, where lon and lat are 2D numpy arrays of spherical coordinates measured in radians, and the returned data array is a numpy array of at least two dimensions whose first two axes have the same shape as lon and lat. The data array gives the map values sampled at the corresponding coordinates. Its additional dimensions can be used to encode color information: one standard is for data to have a dtype of np.uint8 and a shape of (ny, nx, 3), where the final axis samples RGB colors.

Functions

plate_carree_sampler(data)	Create a sampler function for all-sky data in a “plate carrée” projection.
plate_carree_galactic_sampler(data)	Create a sampler function for all-sky data in a “plate carrée” projection using Galactic coordinates.
plate_carree_planet_sampler(data)	Create a sampler function for planetary data in a “plate carrée” projection.
healpix_fits_file_sampler(path[, extension, …])	Create a sampler for HEALPix data read from a FITS file.
healpix_sampler(data[, nest, coord, …])	Create a sampler for HEALPix image data.

toasty.study Module

Common routines for tiling images anchored to the sky in a gnomonic (tangential) projection.

Functions

tile_study_image(image, pio[, cli_progress])

Tile an image as a study, loading the whole thing into memory.

Classes

StudyTiling(width, height)

Information about how a WWT “study” image is broken into tiles.

toasty.toast Module

Computations for the TOAST projection scheme and tile pyramid format.

TODO this all needs to be ported to modern Toasty infrastructure and wwt_data_formats.

Functions

generate_tiles(depth[, bottom_only])	Generate a pyramid of TOAST tiles in deepest-first order.
sample_layer(pio, mode, sampler, depth[, …])	Generate a layer of the TOAST tile pyramid through direct sampling.
toast_tile_area(tile)	Calculate the area of a TOAST tile in steradians.

Classes

Tile(pos, corners, increasing)