toasty tile-allsky
¶
The tile-allsky
command takes a single image representing a full sphere and
samples it into a TOAST tiling.
Usage¶
toasty tile-allsky
[standard image-loading options]
[--placeholder-thumbnail]
[--outdir DIR]
[--name NAME]
[--projection TYPE]
[--parallelism FACTOR]
{IMAGE-PATH}
{TOAST-DEPTH}
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 usedplate-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.
Notes¶
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.