toasty tile-allsky

The tile-allsky command takes a single image representing a full sphere and samples it into a TOAST tiling.


toasty tile-allsky
   [standard image-loading options]
   [--outdir DIR]
   [--name NAME]
   [--projection TYPE]
   [--parallelism FACTOR]

See the Standard image-loading options section for documentation on those options.

The IMAGE-PATH argument gives the filename of the input image. Its projection onto the sphere should be specified with the --projection option.

The TOAST-DEPTH argument specifies the resolution level of the TOAST pixelization that will be generated. A depth of 0 means that the image will be sampled onto a single 256×256 tile, each pixel in the tile having an angular size of about 0.6 deg². A depth of 1 means that the image will be sampled onto four tiles, for a total resolution of 512×512 and an average pixel area of 0.16 deg². A depth of 8 means that there will be 65,536 tiles and 4.3 billion pixels, with an average pixel area of about (11 arcsec)². The appropriate choice of the depth depends on your application.

The --outdir DIR option specifies where the output data should be written. If unspecified, the data root will be the current directory.

The --name NAME option specifies the descriptive name for the imagery to be embedded inside the output WTML file. It defaults to “Toasty”.

The --projection TYPE option specifies how the surface of the sphere is mapped on to the image. Allowed types are:

  • plate-carree (the default) — the image uses a “plate carrée”, AKA equirectangular or geographic, projection. The image will typically be about twice as wide as it is tall. Interpreted as a sky image, the north celestial pole is at the top of the image, RA = Dec = 0 is at the image center, and RA increases to the left.

  • plate-carree-galactic — like the above, but the image is in Galactic coordinates rather than (celestial) equatorial. This is often the case for all-sky astronomical press release images.

  • plate-carree-ecliptic — like the above, but the image is in barycentric true ecliptic coordinates rather than (celestial) equatorial.

  • plate-carree-planet — like the above, but the image is that of a planet and so the sense of the longitude/RA axis is inverted. The line of zero longitude is in the middle of the image, but longitude increases to the right. The zero-longitude line in the output TOAST map is rotated 180 degrees from the sky-like case as well. This is the format in which planetary maps are typically represented. If you use this option when you should have used plate-carree, or vice versa, your map come out flipped horizontally.

  • plate-carree-planet-zeroleft — like the above, but the line of zero longitude in the input image is at the left edge, rather than the middle. Longitude still increases to the right.

  • plate-carree-planet-zeroright — like the above, but longitudes increase to the left rather than to the right. (So you can think of this as having the line of zero longitude on the right edge of the image, but that’s also true for the above case as well, since 0 = 360 here.) The output map will still be in the TOAST planetary format even though the input data are in a format more typically used for sky data.

  • plate-carree-panorama — like the default “plate carrée” projection, but the image is interpreted as a 360 degree panoramic image

If the --placeholder-thumbnail argument is given, an all-black placeholder thumbnail will be created. Otherwise, the thumbnail will be created by downsampling the input image. This operation can actually be the most memory-intensive part of the process, and can yield poor results with mostly-empty images. You can avoid this by using this argument and then invoking toasty make-thumbnail with a better-suited input image.

The --parallelism FACTOR argument specifies the level of parallism to use. On operating systems that support parallel processing, the default is to use all CPUs. To disable parallel processing, explicitly specify a factor of 1.


This command will create the highest-resolution tile layer, corresponding to the DEPTH argument, and emit an index_rel.wtml file containing projection information and template metadata.

Currently, parallel processing is only supported on the Linux operating system, because fork()-based multiprocessing is required. MacOS should support this, but there is currently (as of Python 3.8) a bug preventing that.

See Also