Peter Williams
GitHub
Коммит
bd0f8426b1
|
|
@ -1,6 +1,7 @@
|
|||
# 0.1.0.dev0 (unreleased)
|
||||
# 0.1.0 (2020 Sep 15)
|
||||
|
||||
- No changes yet
|
||||
- Massive rebuild of just about everything about the package.
|
||||
- New CLI tool, `toasty`.
|
||||
|
||||
# 0.0.3 (2019 Aug 3)
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ include .coveragerc
|
|||
include *.md
|
||||
include *.yml
|
||||
|
||||
recursive-include toasty *.fits *.png *.wwtxml
|
||||
recursive-include toasty *.fits *.fits.gz *.jpg *.png *.wwtxml *.yaml
|
||||
|
||||
graft docs
|
||||
prune docs/_build
|
||||
|
|
|
|||
|
|
@ -1,6 +0,0 @@
|
|||
image_sample_tiles_getparser
|
||||
============================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: image_sample_tiles_getparser
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
image_sample_tiles_impl
|
||||
=======================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: image_sample_tiles_impl
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
study_sample_image_tiles_getparser
|
||||
==================================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: study_sample_image_tiles_getparser
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
study_sample_image_tiles_impl
|
||||
=============================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: study_sample_image_tiles_impl
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
tile_allsky_getparser
|
||||
=====================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: tile_allsky_getparser
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
tile_allsky_impl
|
||||
================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: tile_allsky_impl
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
tile_study_getparser
|
||||
====================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: tile_study_getparser
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
tile_study_impl
|
||||
===============
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: tile_study_impl
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
tile_wwtl_getparser
|
||||
===================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: tile_wwtl_getparser
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
tile_wwtl_impl
|
||||
==============
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: tile_wwtl_impl
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
wwtl_sample_image_tiles_getparser
|
||||
=================================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: wwtl_sample_image_tiles_getparser
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
wwtl_sample_image_tiles_impl
|
||||
============================
|
||||
|
||||
.. currentmodule:: toasty.cli
|
||||
|
||||
.. autofunction:: wwtl_sample_image_tiles_impl
|
||||
|
|
@ -6,5 +6,6 @@ CLI Reference
|
|||
|
||||
cli/std-image-options
|
||||
cli/cascade
|
||||
cli/study-sample-image-tiles
|
||||
cli/wwtl-sample-image-tiles
|
||||
cli/tile-allsky
|
||||
cli/tile-study
|
||||
cli/tile-wwtl
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Usage
|
|||
toasty cascade {--start DEPTH} PYRAMID-DIR
|
||||
|
||||
The ``PYRAMID-DIR`` argument gives the location of a directory containing tile
|
||||
pyramid data files. The ``--start DEPTH`` argument gives the depth at which the
|
||||
downsampling process should start. For instance, with ``--start 5``, the pyramid
|
||||
should contain level-6 tiles, and the cascade will fill in tiles between levels
|
||||
5 and 0, inclusive.
|
||||
pyramid data files. The ``--start DEPTH`` argument gives the depth at which
|
||||
tiles *already exist*. For instance, with ``--start 5``, the pyramid should
|
||||
contain level-5 tiles, and the cascade will fill in tiles between levels 4 and
|
||||
0, inclusive.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,63 @@
|
|||
.. _cli-tile-allsky:
|
||||
|
||||
======================
|
||||
``toasty tile-allsky``
|
||||
======================
|
||||
|
||||
The ``tile-allsky`` command takes a single image representing a full sphere and
|
||||
samples it into a TOAST tiling.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
toasty tile-allsky
|
||||
[standard image-loading options]
|
||||
[--outdir DIR]
|
||||
[--projection TYPE]
|
||||
{IMAGE-PATH}
|
||||
{TOAST-DEPTH}
|
||||
|
||||
See the :ref:`cli-std-image-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 ``--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-planet`` — like the above, but the image is that of a planet
|
||||
and so the sense of the longitude/RA axis is inverted. Longitude increases to
|
||||
the right. 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.
|
||||
|
||||
.. _equirectangular: https://en.wikipedia.org/wiki/Equirectangular_projection
|
||||
|
||||
|
||||
Details
|
||||
=======
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -1,18 +1,18 @@
|
|||
.. _cli-study-sample-image-tiles:
|
||||
.. _cli-tile-study:
|
||||
|
||||
===================================
|
||||
``toasty study-sample-image-tiles``
|
||||
===================================
|
||||
=====================
|
||||
``toasty tile-study``
|
||||
=====================
|
||||
|
||||
The ``study-sample-image-tiles`` command takes a single large :ref:`study
|
||||
<studies>` image and samples it into a high-resolution layer of tiles.
|
||||
The ``tile-study`` command takes a single large :ref:`study <studies>` image and
|
||||
breaks it into a high-resolution layer of tiles.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
toasty study-sample-image-tiles
|
||||
toasty tile-study
|
||||
[standard image-loading options]
|
||||
[--outdir DIR]
|
||||
IMAGE-PATH
|
||||
|
|
@ -29,6 +29,10 @@ If unspecified, the data root will be the current directory.
|
|||
Notes
|
||||
=====
|
||||
|
||||
For correct results the source image must be in a tangential (gnomonic)
|
||||
projection on the sky. For images that are small in an angular sense, you might
|
||||
be able to get away with fudging the projection type.
|
||||
|
||||
If the input image does not contain any useful astrometric information, the
|
||||
emited ``index_rel.wtml`` file will contain generic information that makes the
|
||||
image 1° wide and places it at RA = Dec = 0.
|
||||
|
|
@ -1,23 +1,23 @@
|
|||
.. _cli-wwtl-sample-image-tiles:
|
||||
.. _cli-tile-wwtl:
|
||||
|
||||
==================================
|
||||
``toasty wwtl-sample-image-tiles``
|
||||
``toasty tile-wwtl``
|
||||
==================================
|
||||
|
||||
The ``wwtl-sample-image-tiles`` command is like
|
||||
:ref:`cli-study-sample-image-tiles`, but loads up ``.wwtl`` WWT “layers” files,
|
||||
from which it can load preexisting astrometric information and convert it to the
|
||||
format needed for its tiled output. The purpose of this specialized command is
|
||||
to enable an easy workflow where you can interactively position a large image
|
||||
file on the sky in the AAS WorldWide Telescope Windows application, then tile it
|
||||
for web viewing while preserving the astrometric alignment.
|
||||
The ``tile-wwtl`` command is like :ref:`cli-tile-study`, but loads
|
||||
up ``.wwtl`` WWT “layers” files, from which it can load preexisting astrometric
|
||||
information and convert it to the format needed for its tiled output. The
|
||||
purpose of this specialized command is to enable an easy workflow where you can
|
||||
interactively position a large image file on the sky in the AAS WorldWide
|
||||
Telescope Windows application, then tile it for web viewing while preserving the
|
||||
astrometric alignment.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
toasty wwtl-sample-image-tiles
|
||||
toasty tile-wwtl
|
||||
[standard image-loading options]
|
||||
[--outdir DIR]
|
||||
WWTL-PATH
|
||||
|
|
@ -29,7 +29,8 @@ command.
|
|||
|
||||
The ``WWTL-PATH`` argument gives the filename of the input WWTL file. This file
|
||||
should contain one layer, which should be an image-set layer. The WWTL file will
|
||||
include the contents of the associated image as well.
|
||||
include the contents of the associated image as well. The source image should be
|
||||
in a tangential (gnomonic) projection on the sky.
|
||||
|
||||
The ``--outdir DIR`` option specifies where the output data should be written.
|
||||
If unspecified, the data root will be the current directory.
|
||||
|
|
@ -4,8 +4,8 @@ project = 'toasty'
|
|||
author = 'Chris Beaumont and the AAS WorldWide Telescope Team'
|
||||
copyright = '2014-2020, ' + author
|
||||
|
||||
release = '0.1.0.dev0' # the full version string; also update ../setup.py
|
||||
version = '0.1.0.dev0' # the "short" version
|
||||
release = '0.2.0.dev0' # the full version string; also update ../setup.py
|
||||
version = '0.2.0.dev0' # the "short" version
|
||||
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
|
|
|
|||
|
|
@ -1,146 +0,0 @@
|
|||
======================================
|
||||
OUTDATED Examples of How to Use Toasty
|
||||
======================================
|
||||
|
||||
.. warning:: These docs are out of date
|
||||
These are all superseded by the command-line interface!
|
||||
|
||||
Here we’ll summarize some of the ways that you can use toasty_.
|
||||
|
||||
.. _toasty: https://toasty.readthedocs.io/
|
||||
|
||||
*NOTE*: these examples need to be updated as we refine the toasty_ API!
|
||||
|
||||
|
||||
Toasting a plate-carrée, all-sky PNG image
|
||||
==========================================
|
||||
|
||||
This script processes an existing all-sky PNG image that uses a `plate carrée
|
||||
<https://en.wikipedia.org/wiki/Equirectangular_projection>`_ projection, using
|
||||
scikit-image_ to load the data::
|
||||
|
||||
from toasty.toast import toast
|
||||
from toasty.samplers import plate_carree_sampler
|
||||
from skimage.io import imread
|
||||
|
||||
data = imread('allsky.png')
|
||||
sampler = plate_carree_sampler(data)
|
||||
output_directory = 'toast'
|
||||
depth = 8 # approximately 0.165"/pixel at highest resolution
|
||||
|
||||
# Make the full toast tile set for the entire sky:
|
||||
toast(sampler, depth, output_directory)
|
||||
|
||||
.. _scikit-image: https://scikit-image.org/
|
||||
|
||||
|
||||
Toasting subsets of the sky
|
||||
===========================
|
||||
|
||||
You don’t have to build the full pyramid for the full sky all at once::
|
||||
|
||||
# Toast a specific region of the sky defined by RA/Dec bounds
|
||||
from toasty.toast import minmax_tile_filter
|
||||
ra_range = [0.17, 0.19], # radians
|
||||
dec_range = [1.22, 1.24], # radians
|
||||
filter = minmax_tile_filter(ra_range, dec_range)
|
||||
toast(sampler, depth, output_directory, tile_filter=filter)
|
||||
|
||||
# Toast a specific region of the sky defined by a higher-level TOAST tile
|
||||
from toasty.toast import nxy_tile_filter
|
||||
filter = nxy_tile_filter(4, 5, 9) # depth=4, ix=5, iy=9
|
||||
toast(sampler, depth, output_directory, tile_filter=filter)
|
||||
|
||||
# Create only the bottom layer of toast tiles
|
||||
toast(sampler, depth, output_directory,
|
||||
base_level_only = True,
|
||||
)
|
||||
|
||||
# Merge from a previously created toast layer up to a specified layer
|
||||
toast(sampler, depth, output_directory,
|
||||
top_layer = 4,
|
||||
)
|
||||
|
||||
|
||||
Controlling how data are turned into RGB
|
||||
========================================
|
||||
|
||||
Here we apply a log-stretch to an all sky FITS image::
|
||||
|
||||
from toasty.toast import toast
|
||||
from toasty.sampler import plate_carree_sampler, normalizer
|
||||
from astropy.io import fits
|
||||
|
||||
data = fits.open('allsky.fits')[0].data
|
||||
|
||||
vmin, vmax = 100, 65535
|
||||
scaling = 'log'
|
||||
contrast = 1
|
||||
sampler = normalizer(
|
||||
plate_carree_sampler(data),
|
||||
vmin, vmax
|
||||
scaling, bias, contrast
|
||||
)
|
||||
|
||||
output_directory = 'toast'
|
||||
depth = 8
|
||||
toast(sampler, depth, output_directory)
|
||||
|
||||
|
||||
Arbitrary coordinate transformations
|
||||
====================================
|
||||
|
||||
A custom “sampler” can be used to tell toasty_ what image values
|
||||
correspond to what locations on the sky::
|
||||
|
||||
from toasty.toast import toast
|
||||
|
||||
def sampler(x, y):
|
||||
"""
|
||||
x and y are arrays, giving the RA/Dec centers
|
||||
(in radians) for each pixel to extract
|
||||
"""
|
||||
... code to produce pixel values goes here ...
|
||||
|
||||
output_directory = 'toast'
|
||||
depth = 8
|
||||
toast(sampler, depth, output_directory)
|
||||
|
||||
See :meth:`toasty.toast.toast` for documentation on sampler functions.
|
||||
|
||||
|
||||
Previewing toasts with AAS WorldWide Telescope
|
||||
==============================================
|
||||
|
||||
To quickly preview a toast directory named ``mytoast``, run the command::
|
||||
|
||||
python -m toasty.viewer mytoast
|
||||
|
||||
This will start a web server, probably at ``http://0.0.0.0:8000``. (Check the
|
||||
program’s output for the actual address). Open this URL in a browser to get a
|
||||
quick look at the data.
|
||||
|
||||
|
||||
Example toasty outputs: ADS All-Sky Survey
|
||||
==========================================
|
||||
|
||||
For an example of tiles generated with Toasty, see `the ADS All Sky Survey
|
||||
<http://adsass.org/wwt>`_. The code used to generate these images is in `the
|
||||
file toast.py`_ in the `adsass/wwt-frontend`_ repository on GitHub. This tile
|
||||
pyramid was created by Chris Beaumont.
|
||||
|
||||
.. _the file toast.py: https://github.com/adsass/wwt-frontend/blob/master/toast/toast.py
|
||||
.. _adsass/wwt-frontend: https://github.com/adsass/wwt-frontend/
|
||||
|
||||
|
||||
Example toasty outputs: PanSTARRS in STScI AstroView
|
||||
====================================================
|
||||
|
||||
Another example is a toasting of the “3π” survey of the PanSTARRS_ project,
|
||||
viewable `here in STScI’s AstroView`_ interface. The code used to generate
|
||||
these images is in the GitHub repository `ceb8/toastPanstarrs`_. This tile
|
||||
pyramid was created by Clara Brasseur.
|
||||
|
||||
.. _PanSTARRS: https://panstarrs.stsci.edu/
|
||||
.. _here in STScI’s AstroView: https://mast.stsci.edu/portal/Mashup/Clients/AstroView/AstroView.html?debug&avSurveyType=PANSTARRS
|
||||
.. _ceb8/toastPanstarrs: https://github.com/ceb8/toastPanstarrs
|
||||
|
|
@ -11,20 +11,12 @@ maps can be viewed in software such as the AAS_ `WorldWide Telescope`_.
|
|||
.. _AAS: https://aas.org/
|
||||
.. _WorldWide Telescope: http://www.worldwidetelescope.org/home
|
||||
|
||||
|
||||
User guide
|
||||
==========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
installation
|
||||
studies
|
||||
pipeline
|
||||
manual
|
||||
cli
|
||||
api
|
||||
examples
|
||||
|
||||
|
||||
Getting help
|
||||
|
|
|
|||
|
|
@ -0,0 +1,11 @@
|
|||
=================
|
||||
The toasty Manual
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
|
||||
overview
|
||||
installation
|
||||
studies
|
||||
toasting
|
||||
pipeline
|
||||
136
docs/studies.rst
136
docs/studies.rst
|
|
@ -9,8 +9,8 @@ images projected on the sky in a tangential (`gnomonic`_) projection. Due to the
|
|||
properties of this projection, the “study” format is best suited for images that
|
||||
are large in terms of pixels, but not necessarily large in terms of angular
|
||||
area. Examples of this kind of imagery include nearly all astrophotography
|
||||
images and typical scientific observations. Mosaics that cover extremely large
|
||||
sections of the sky (multiple steradians) are better represented in the all-sky
|
||||
images and typical scientific observations. Mosaics that cover *extremely* large
|
||||
regions of the sky (multiple steradians) are better represented in the all-sky
|
||||
TOAST format.
|
||||
|
||||
.. _AAS WorldWide Telescope: http://worldwidetelescope.org/
|
||||
|
|
@ -24,9 +24,131 @@ demonstrate this way of using the software.
|
|||
Astrometry
|
||||
==========
|
||||
|
||||
Tiling study images should, in general, be easy if not completely automatic. If
|
||||
there’s one part of the process most likely to cause problems, it is generating
|
||||
the “astrometric” information that specifies where the image should be placed on
|
||||
the sky.
|
||||
Tiling study images should generally be easy, and in many circumstances the
|
||||
process can be completely automatic. If there’s one part of the process most
|
||||
likely to cause problems, it is generating the “astrometric” information that
|
||||
specifies where the image should be placed on the sky.
|
||||
|
||||
More here ...
|
||||
When creating a new WWT study dataset, you need to determine how or where the
|
||||
necessary astrometric information will come from. Your options are:
|
||||
|
||||
- `AVM`_ tags in the source image. **Except we haven’t wired this up for basic
|
||||
study processing! Fix this!!!**
|
||||
|
||||
- Pre-positioning in the WWT Windows client and exporting as a WWTL file. If you
|
||||
have a large image that you can load in the WWT Windows client, you can use its
|
||||
interactive placement feature to set its position, and then save the image with
|
||||
that placement as an “image layer” in a WWTL “layers file”, then can load the
|
||||
image and its astrometry using the :ref:`cli-tile-wwtl` command.
|
||||
|
||||
- If all else fails, the :ref:`cli-tile-study` command will insert
|
||||
default astrometric information and place your image at RA = Dec = 0 and make
|
||||
it 1° across. You can then manually edit the WTML to properly place the image
|
||||
against a reference. This can be less horrible than it sounds, but it’s
|
||||
definitely not good.
|
||||
|
||||
.. _AVM: https://www.virtualastronomy.org/avm_metadata.php
|
||||
|
||||
|
||||
Standard workflow 1: manual positioning in the Windows client
|
||||
=============================================================
|
||||
|
||||
In the typical study workflow, you have a single source image, potentially very
|
||||
large, that needs to be broken into tiles and described in a `WTML`_ file. If
|
||||
you have access to the Windows client and can position the image manually, the
|
||||
standard workflow proceeds as follows:
|
||||
|
||||
.. _WTML: https://docs.worldwidetelescope.org/data-guide/1/data-file-formats/collections/
|
||||
|
||||
1. Choose and/or create a directory on your computer in which you’ll be working.
|
||||
|
||||
2. Download the source image to your work directory. For concreteness, we’ll
|
||||
call it ``fullsize.tif`` here, but multiple image formats are supported.
|
||||
|
||||
3. Open the image in the WWT Windows client, position it interactively, and
|
||||
export the positioned image layer as a WWTL layer file. We’ll call that
|
||||
``fullsize.wwtl``.
|
||||
|
||||
4. Do the initial tiling and astrometry extraction with:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ toasty tile-wwtl --outdir=tiled fullsize.wwtl
|
||||
|
||||
Here it might make sense to use some of the :ref:`cli-std-image-options` to
|
||||
control how the source image is processed. Along with the tiles, this command
|
||||
will generate a file ``tiled/index_rel.wtml`` that describes the image data,
|
||||
including their astrometry.
|
||||
|
||||
5. Generate the higher-level tiles with:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ toasty cascade --start=5 tiled
|
||||
|
||||
where the number passed to the ``--start`` argument will change depending on
|
||||
the characteristics of your image. The ``tile-wwtl`` command will tell you
|
||||
what value to use.
|
||||
|
||||
6. Examine the image ``tiled/0/0/0_0.png`` to see if it looks like a reasonable
|
||||
reduction of your large source image.
|
||||
|
||||
7. Review the appearance of your image in WWT. Use the ``wwtdatatool`` command
|
||||
provided by the `wwt_data_formats`_ Python package to start up an HTTP server
|
||||
that will make your WTML and tile data accessible to WWT (either Windows or
|
||||
web clients):
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ wwtdatatool serve tiled
|
||||
|
||||
This command will print a URL to a synthetic ``index.wtml`` file that you can
|
||||
open up in WWT to view your tiled image. Hopefully everything will be fine,
|
||||
but at this point you can tune and/or fix the tiling procedure if something
|
||||
isn’t right.
|
||||
|
||||
8. Fill in proper metadata in the ``index_rel.wtml`` file. Items to consider are:
|
||||
|
||||
- The ``<Credits>`` XML element with proper credit text.
|
||||
|
||||
- The ``<CreditsUrl>`` XML element with a link to the image source and/or
|
||||
more information about it.
|
||||
|
||||
- The ``<Description>`` XML element with text describing the image. If editing
|
||||
the XML manually, make sure to properly escape the magic XML characters
|
||||
``&`` (to ``&``), ``<`` (to ``<``) and ``>`` (to ``>``).
|
||||
|
||||
- The ``Name`` attributes of the ``<ImageSet>``, ``<Place>``, and ``<Folder>``
|
||||
elements. These should generally all be the same.
|
||||
|
||||
- The ``ZoomLevel`` attribute of the ``<Place>`` element, specifying the zoom
|
||||
level that the client should seek to when viewing the image. It can be a bit
|
||||
subjective as to what zoom level is best, and the numbers are measured oddly
|
||||
so choosing the right value is generally a matter of trial and error.
|
||||
|
||||
- Other metadata like the ``Classification``, ``Constellation``, etc.
|
||||
|
||||
9. When the ``index_rel.wtml`` file is all finalized, it needs to be transformed
|
||||
to have absolute rather than relative URLs. To do this transformation, you need
|
||||
to know the URL from which users will be accessing your data. When you know that
|
||||
base URL, the command to use is of this form:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ wwtdatatool wtml rewrite-urls \
|
||||
tiled/index_rel.wtml \
|
||||
http://data1.wwtassets.org/packages/2020/07_phat_m31/ \
|
||||
tiled/index.wtml
|
||||
|
||||
(Here, the backslashes are used because the command spans multiple lines of
|
||||
the shell prompt. If you type it all on one line, no backslashes should be
|
||||
used.)
|
||||
|
||||
10. Finally, upload the complete contents of your ``tiled`` subdirectory to your
|
||||
web server. In this case, the upload location should be such that the url
|
||||
`<http://data1.wwtassets.org/packages/2020/07_phat_m31/index.wtml>`_ will
|
||||
yield the ``index.wtml`` file created in the previous step.
|
||||
|
||||
.. _wwt_data_formats: https://wwt-data-formats.readthedocs.io/
|
||||
|
||||
And that’s it, your image has been tiled and published!
|
||||
|
|
|
|||
|
|
@ -0,0 +1,129 @@
|
|||
.. toasting:
|
||||
|
||||
===============================
|
||||
“TOASTing”: Tiling full spheres
|
||||
===============================
|
||||
|
||||
To view full-sphere data in `AAS WorldWide Telescope`_ — either all-sky maps or
|
||||
all-planet maps — the input imagery needs to be tiled into the special TOAST
|
||||
projection. It is not necessary to use this projection for images that may
|
||||
contain many pixels but do not cover a substantial fraction of the sphere. In
|
||||
those cases, you should prepare a :ref:`study <studies>` instead.
|
||||
|
||||
.. _AAS WorldWide Telescope: http://worldwidetelescope.org/
|
||||
|
||||
The intent of the toasty package is to make it so that most tiling workflows can
|
||||
be executed on the command line using the ``toasty`` program. This section will
|
||||
demonstrate this way of using the software.
|
||||
|
||||
|
||||
Toasting a single full-sphere image
|
||||
===================================
|
||||
|
||||
Sometimes, you already have a large image mapping the entire sphere — it just
|
||||
needs to be reprojected, broken into tiles, and described in a `WTML`_ file. The
|
||||
workflow in this case is as follows:
|
||||
|
||||
.. _WTML: https://docs.worldwidetelescope.org/data-guide/1/data-file-formats/collections/
|
||||
|
||||
1. Choose and/or create a directory on your computer in which you’ll be working.
|
||||
|
||||
2. Download the source image to your work directory. For concreteness, we’ll
|
||||
call it ``fullsize.tif`` here, but multiple image formats are supported.
|
||||
|
||||
3. Determine the *projection* used by the source image. This is the mechanism by
|
||||
which the curved surface of the sphere is mapped onto a 2D image. For
|
||||
full-sphere imagery, only a few choices are ever used. Consult the
|
||||
:ref:`cli-tile-allsky` documentation for the supported choices. If your image
|
||||
uses an unsupported projection, please `file a request`_ with the developers.
|
||||
|
||||
4. Determine the *tiling depth* appropriate for your use case. The depth is a number
|
||||
that specifies the highest resolution that your final map will attain.
|
||||
Consult the :ref:`cli-tile-allsky` documentation for the quantitative
|
||||
definition. The best choice will depend on your individual circumstances. But
|
||||
as a general guideline, you should probably choose the depth that yields a
|
||||
number of pixels equal to, or just greater than, the number of pixels in your
|
||||
source image.
|
||||
|
||||
5. Do the initial tiling with:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ toasty tile-allsky --projection={PROJECTION} \
|
||||
--outdir=tiled fullsize.tif {DEPTH}
|
||||
|
||||
where ``{PROJECTION}`` and ``{DEPTH}`` should be replaced by the values you
|
||||
determined in the previous steps. (Here, the backslashes are used because the
|
||||
command spans multiple lines of the shell prompt. If you type it all on one
|
||||
line, no backslashes should be used.)
|
||||
|
||||
It might make sense to use some of the :ref:`cli-std-image-options` to
|
||||
control how the source image is processed. Along with the tiles, this command
|
||||
will generate a file ``tiled/index_rel.wtml`` that describes the imagery.
|
||||
|
||||
6. Generate the higher-level tiles with:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ toasty cascade --start={DEPTH} tiled
|
||||
|
||||
where ``{DEPTH}`` is the same value as used in the previous command.
|
||||
|
||||
7. Examine the image ``tiled/0/0/0_0.png`` to see if it looks like a reasonable
|
||||
TOAST-ification of your source image. The equator of your map will be
|
||||
translated to a diamond touching the midpoints of the edges of the square
|
||||
tile.
|
||||
|
||||
8. Review the appearance of your image in WWT. Use the ``wwtdatatool`` command
|
||||
provided by the `wwt_data_formats`_ Python package to start up an HTTP server
|
||||
that will make your WTML and tile data accessible to WWT (either Windows or
|
||||
web clients):
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ wwtdatatool serve tiled
|
||||
|
||||
This command will print a URL to a synthetic ``index.wtml`` file that you can
|
||||
open up in WWT to view your tiled image. Hopefully everything will be fine,
|
||||
but at this point you can tune and/or fix the tiling procedure if something
|
||||
isn’t right.
|
||||
|
||||
9. Fill in proper metadata in the ``index_rel.wtml`` file. Items to consider are:
|
||||
|
||||
- The ``<Credits>`` XML element with proper credit text.
|
||||
|
||||
- The ``<CreditsUrl>`` XML element with a link to the image source and/or
|
||||
more information about it.
|
||||
|
||||
- The ``<Description>`` XML element with text describing the image. If editing
|
||||
the XML manually, make sure to properly escape the magic XML characters
|
||||
``&`` (to ``&``), ``<`` (to ``<``) and ``>`` (to ``>``).
|
||||
|
||||
- The ``Name`` attributes of the ``<ImageSet>``, ``<Place>``, and ``<Folder>``
|
||||
elements. These should generally all be the same.
|
||||
|
||||
- Other metadata like the ``Bandpass``, etc.
|
||||
|
||||
10. When the ``index_rel.wtml`` file is all finalized, it needs to be transformed
|
||||
to have absolute rather than relative URLs. To do this transformation, you need
|
||||
to know the URL from which users will be accessing your data. When you know that
|
||||
base URL, the command to use is of this form:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ wwtdatatool wtml rewrite-urls \
|
||||
tiled/index_rel.wtml \
|
||||
http://data1.wwtassets.org/packages/2020/07_phat_m31/ \
|
||||
tiled/index.wtml
|
||||
|
||||
(Here, the backslashes are used because the command spans multiple lines of
|
||||
the shell prompt. If you type it all on one line, no backslashes should be
|
||||
used.)
|
||||
|
||||
11. Finally, upload the complete contents of your ``tiled`` subdirectory to your
|
||||
web server. In this case, the upload location should be such that the url
|
||||
`<http://data1.wwtassets.org/packages/2020/07_phat_m31/index.wtml>`_ will
|
||||
yield the ``index.wtml`` file created in the previous step.
|
||||
|
||||
.. _file a request: https://github.com/WorldWideTelescope/toasty/issues/
|
||||
.. _wwt_data_formats: https://wwt-data-formats.readthedocs.io/
|
||||
2
setup.py
2
setup.py
|
|
@ -34,7 +34,7 @@ project homepage].
|
|||
|
||||
setup_args = dict(
|
||||
name = 'toasty',
|
||||
version = '0.1.0.dev0', # also update docs/conf.py
|
||||
version = '0.2.0.dev0', # also update docs/conf.py
|
||||
description = 'Generate TOAST image tile pyramids from existing image data',
|
||||
long_description = get_long_desc(),
|
||||
long_description_content_type = 'text/markdown',
|
||||
|
|
|
|||
|
|
@ -112,9 +112,9 @@ def healpix_sample_data_tiles_impl(settings):
|
|||
ds.sample_layer(pio, settings.depth)
|
||||
|
||||
|
||||
# "image_sample_tiles" subcommand
|
||||
# "tile_allsky" subcommand
|
||||
|
||||
def image_sample_tiles_getparser(parser):
|
||||
def tile_allsky_getparser(parser):
|
||||
from .image import ImageLoader
|
||||
ImageLoader.add_arguments(parser)
|
||||
|
||||
|
|
@ -143,7 +143,7 @@ def image_sample_tiles_getparser(parser):
|
|||
)
|
||||
|
||||
|
||||
def image_sample_tiles_impl(settings):
|
||||
def tile_allsky_impl(settings):
|
||||
from .image import ImageLoader
|
||||
from .pyramid import PyramidIO
|
||||
from .toast import SamplingToastDataSource
|
||||
|
|
@ -334,9 +334,9 @@ def pipeline_reindex_impl(settings):
|
|||
mgr.reindex()
|
||||
|
||||
|
||||
# "study_sample_image_tiles" subcommand
|
||||
# "tile_study" subcommand
|
||||
|
||||
def study_sample_image_tiles_getparser(parser):
|
||||
def tile_study_getparser(parser):
|
||||
from .image import ImageLoader
|
||||
ImageLoader.add_arguments(parser)
|
||||
|
||||
|
|
@ -353,7 +353,7 @@ def study_sample_image_tiles_getparser(parser):
|
|||
)
|
||||
|
||||
|
||||
def study_sample_image_tiles_impl(settings):
|
||||
def tile_study_impl(settings):
|
||||
from .builder import Builder
|
||||
from .image import ImageLoader
|
||||
from .pyramid import PyramidIO
|
||||
|
|
@ -372,9 +372,9 @@ def study_sample_image_tiles_impl(settings):
|
|||
print(f' toasty cascade --start {builder.imgset.tile_levels} {settings.outdir}')
|
||||
|
||||
|
||||
# "wwtl_sample_image_tiles" subcommand
|
||||
# "tile_wwtl" subcommand
|
||||
|
||||
def wwtl_sample_image_tiles_getparser(parser):
|
||||
def tile_wwtl_getparser(parser):
|
||||
from .image import ImageLoader
|
||||
ImageLoader.add_arguments(parser)
|
||||
|
||||
|
|
@ -391,7 +391,7 @@ def wwtl_sample_image_tiles_getparser(parser):
|
|||
)
|
||||
|
||||
|
||||
def wwtl_sample_image_tiles_impl(settings):
|
||||
def tile_wwtl_impl(settings):
|
||||
from .builder import Builder
|
||||
from .image import ImageLoader
|
||||
from .pyramid import PyramidIO
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ class TestCascade(object):
|
|||
|
||||
"""
|
||||
args = [
|
||||
'image-sample-tiles',
|
||||
'tile-allsky',
|
||||
'--outdir', self.work_path('basic_cli'),
|
||||
test_path('Equirectangular_projection_SW-tweaked.jpg'),
|
||||
'1',
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ class TestStudy(object):
|
|||
expected = etree.fromstring(self.WTML)
|
||||
|
||||
args = [
|
||||
'study-sample-image-tiles',
|
||||
'tile-study',
|
||||
'--outdir', self.work_path(),
|
||||
test_path('NGC253ALMA.jpg')
|
||||
]
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ class TestStudy(object):
|
|||
# Now run it through the CLI.
|
||||
|
||||
args = [
|
||||
'wwtl-sample-image-tiles',
|
||||
'tile-wwtl',
|
||||
'--outdir', self.work_path('tiles'),
|
||||
self.work_path('image.wwtl')
|
||||
]
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче