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.



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

toasty.cli Module

Entrypoint for the “toasty” command-line interface.




The entrypoint for the “toasty” command-line interface.


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.



A 2D data array stored in memory.


A class defining how to load an image.


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.



A merger function that averages quartets of pixels.

cascade_images(pio, 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.


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:



Load an OpenEXR file

toasty.par_util Module

Utilities for parallel processing



Decide what level of parallelism to use.

toasty.pipeline Package

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



An abstract base class representing an image from one of our sources.


An abstract base class representing a source of images to be processed in the image-processing pipeline.


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.


An abstract base class for I/O relating to pipeline processing.

toasty.pipeline.astropix Module

Support for loading images from an AstroPix feed.

TODO: update metadata tomfoolery to match the new things that I’ve learned. Cf. the wwtdatatool wtml report utility and the djangoplicity implementation.



An ImageSource that obtains its inputs from a query to the AstroPix service.


A CandidateInput obtained from an AstroPix query.

toasty.pipeline.azure_io Module

Azure Blob Storage I/O backend for the pipeline framework.

This module requires that the Python module be available. If it is not, this module will still be importable, but it won’t work. Check the ENABLED boolean variable or call assert_enabled() to raise an exception offering guidance if the needed support is missing.




AzureBlobPipelineIo(connection_string, …)

I/O for pipeline processing that uses Microsoft Azure Blob Storage.

toasty.pipeline.cli Module

Entrypoints for the “toasty pipeline” command-line tools.




toasty.pipeline.djangoplicity Module

Support for loading images from a Djangoplicity database.



An ImageSource that obtains its inputs from a query to a Djangoplicity website.


A CandidateInput obtained from an AstroPix query.

toasty.pipeline.local_io Module

Pipeline I/O using the local filesystem as a storage backend.

Note that pipeline processing always uses the local filesystem for intermediate steps. This module is for scenarios where the final long-term storage of processed data should also involve the local filesystem.



I/O for pipeline processing using the local disk.

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.



Return the total number of tiles in a WWT tile pyramid of depth depth.


Generate a pyramid of tile positions.

is_subtile(deeper_pos, shallower_pos)

Determine if one tile is a child of another.


Ugh, this implementation is so dumb.


Return the children of a tile position.


Return a tile position’s parent.


Return the number of tiles in the WWT tile pyramid layer at depth depth.


Pos(n, x, y)

PyramidIO(base_dir[, scheme, default_format])

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.



Create a sampler function for all-sky data in a “plate carrée” projection.


Create a sampler function for all-sky data in a “plate carrée” projection using Galactic coordinates.


Create a sampler function for all-sky data in a “plate carrée” projection using ecliptic coordinates.


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

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


tile_study_image(image, pio[, cli_progress])

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


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.


generate_tiles(depth[, bottom_only])

Generate a pyramid of TOAST tiles in deepest-first order.

sample_layer(pio, sampler, depth[, …])

Generate a layer of the TOAST tile pyramid through direct sampling.

toast_pixel_for_point(depth, lat, lon)

Identify the pixel within a TOAST tile at a given depth that contains the given point.


Calculate the area of a TOAST tile in steradians.

toast_tile_for_point(depth, lat, lon)

Identify the TOAST tile at a given depth that contains the given point.


Tile(pos, corners, increasing)