Release commit created with Cranko.

+++ cranko-release-info-v1
[[projects]]
qnames = ["toasty", "pypa"]
version = "0.17.0"
age = 0

+++

CHANGELOG.md

@@ -1,3 +1,16 @@
+# toasty 0.17.0 (2022-07-12)
+
+- Add an `--avm-from` option to `toasty tile-study`, which would have been
+  useful with the JWST imagery released yesterday (#82, @pkgw).
+- Support tiled FITS in `toasty tile-healpix` (#79, #80, @pkgw), and add a
+  `--force-galactic` option.
+- Avoid HEALPix HDUs without data (#79, @pkgw)
+- Add some diagnostics for spatial AVM information in `toasty check-avm` (#78,
+  @pkgw)
+- Update tests for new `wwt_data_formats` constellation support and other
+  changing dependencies.
+
+
 # toasty 0.16.1 (2022-01-27)
 
 - Toasty is now more forgiving with FITS and WCS shapes when tiling FITS data

docs/cli.rst

@@ -16,6 +16,7 @@ CLI Reference
    cli/pipeline-publish
    cli/pipeline-refresh
    cli/tile-allsky
+   cli/tile-healpix
    cli/tile-study
    cli/tile-wwtl
    cli/transform-fx3-to-rgb

docs/cli/check-avm.rst

@@ -28,14 +28,16 @@ successful.
 
 .. _WCS: https://fits.gsfc.nasa.gov/fits_wcs.html
 
-By default, only the presence of AVM data is reported. If the ``--print`` or
-``-p`` option is given, the AVM data will be dumped out.
+By default, the presence of AVM data is reported along with some information
+about the agreement between the AVM and the image shape. If the ``--print`` or
+``-p`` option is given, the actual AVM data will be dumped out.
 
 If the ``--exitcode`` option is given, the exit code of the command line tool
-will reflect whether AVM data were found. Zero (success) means that data were
-found, while nonzero (failure) indicates that no data were present, the data
-were corrupt, or that some other failure occurred. Without this option, the exit
-code will be zero if the image can be opened but contains no AVM data.
+will reflect whether spatial AVM data were found. Zero (success) means that
+spatial data were found, while nonzero (failure) indicates that no data were
+present, the data were corrupt, or that some other failure occurred. Without
+this option, the exit code will be zero if the image can be opened but contains
+no AVM data.
 
 
 Notes

docs/cli/tile-allsky.rst

@@ -105,3 +105,9 @@ because ``fork()``-based multiprocessing is required. MacOS should support this,
 but there is currently (as of Python 3.8) `a bug`_ preventing that.
 
 .. _a bug: https://bugs.python.org/issue33725
+
+
+See Also
+========
+
+- :ref:`cli-tile-healpix`

docs/cli/tile-healpix.rst

@@ -0,0 +1,82 @@
+.. _cli-tile-healpix:
+
+=======================
+``toasty tile-healpix``
+=======================
+
+The ``tile-healpix`` command transforms all-sky FITS images in the HEALPix_
+format into WWT’s FITS TOAST format.
+
+.. _HEALPix: https://healpix.jpl.nasa.gov/
+
+Usage
+=====
+
+.. code-block:: shell
+
+   toasty tile-healpix
+      [--galactic]
+      [--outdir DIR]
+      [--parallelism FACTOR] [-j FACTOR]
+      {FITS-PATH}
+      {TOAST-DEPTH}
+
+The ``FITS-PATH`` argument gives the filename of the input image, which should
+be a single FITS file storing data in the HEALPix_ format.
+
+The ``TOAST-DEPTH`` argument specifies the resolution level of the TOAST
+pixelization that will be generated. A depth of 0 means that the input will be
+sampled onto a single 256×256 tile, a depth of 1 means that the input will be
+sampled onto four tiles for a total resolution of 512×512, and so on. When
+converting from HEALPix, the appropriate TOAST depth can be derived from the
+HEALPix ``N_side`` parameter as approximately::
+
+  depth = log2(N_side) - 6.2
+
+One should typically round up to the next larger integer to err on the side of
+higher resolution, although the best policy will depend on the sampling of the
+input HEALPix map.
+
+The ``--outdir DIR`` option specifies where the output data should be written.
+If unspecified, the data root will be the current directory.
+
+The ``--galactic`` option forces the tiling to assume that the input map is in
+Galactic coordinates, even if the FITS headers do not specify that. This has
+been observed in some data sets in the wild.
+
+The ``--parallelism FACTOR`` argument (or ``-j FACTOR``) 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 requires that the healpy_ Python module is installed.
+
+.. _healpy: https://healpy.readthedocs.io/
+
+This command will create FITS files for the highest-resolution tile layer,
+corresponding to the ``DEPTH`` argument, and emit an ``index_rel.wtml`` file
+containing projection information and template metadata.
+
+The WWT rendering engine can also display datasets in the hierarchical HiPS_
+FITS format, which addresses about the same use case as TOAST. If a HiPS FITS
+dataset already exists, it is probably a wiser choice to use it rather than
+creating a new TOAST pyramid. However, TOAST provides noticeably better
+performance for the initial data display and avoiding positional shifts as the
+user zooms in.
+
+.. _HiPS: https://aladin.unistra.fr/hips/
+
+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.
+
+.. _a bug: https://bugs.python.org/issue33725
+
+
+See Also
+========
+
+- :ref:`cli-tile-allsky`

docs/cli/tile-study.rst

@@ -18,6 +18,7 @@ Usage
       [--outdir DIR]
       [--name NAME]
       [--avm]
+      [--avm-from PATH]
       [--fits-wcs PATH]
       IMAGE-PATH
 
@@ -49,6 +50,12 @@ requires the `pyavm`_ package to be installed on your system.
 
 .. _pyavm: https://astrofrog.github.io/pyavm/
 
+The ``--avm-from PATH`` argument is like ``--avm``, but loads the AVM
+information from a *different* image file. This can be useful if you have
+multiple files with different versions of the same image, and the one that you
+want to tile has broken or missing AVM. It is up to you to ensure that
+information contained in the AVM file corresponds to the main input image.
+
 If the ``--fits-wcs`` argument is given, Toasty will attempt to load
 world-coordinate information from the headers of the named `FITS`_ file. It is
 up to you to ensure that information contained in that file corresponds to the

docs/conf.py

@@ -1,78 +1,63 @@
 # -*- coding: utf-8 -*-
 
-project = 'toasty'
-author = 'Chris Beaumont and the AAS WorldWide Telescope Team'
-copyright = '2014-2020, ' + author
+project = "toasty"
+author = "Chris Beaumont and the AAS WorldWide Telescope Team"
+copyright = "2014-2020, " + author
 
-release = '0.dev0'  # cranko project-version
-version = '.'.join(release.split('.')[:2])
+release = "0.dev0"  # cranko project-version
+version = ".".join(release.split(".")[:2])
 
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinx_automodapi.automodapi',
-    'sphinx_automodapi.smart_resolver',
-    'numpydoc',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx_automodapi.automodapi",
+    "sphinx_automodapi.smart_resolver",
+    "numpydoc",
 ]
 
-templates_path = ['_templates']
-source_suffix = '.rst'
-master_doc = 'index'
-language = None
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-pygments_style = 'sphinx'
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+language = "en"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+pygments_style = "sphinx"
 todo_include_todos = False
 
-html_theme = 'bootstrap-astropy'
+html_theme = "bootstrap-astropy"
 html_theme_options = {
-    'logotext1': 'toasty',
-    'logotext2': '',
-    'logotext3': ':docs',
-    'astropy_project_menubar': False,
+    "logotext1": "toasty",
+    "logotext2": "",
+    "logotext3": ":docs",
+    "astropy_project_menubar": False,
 }
-html_static_path = ['_static']
-htmlhelp_basename = 'toastydoc'
+html_static_path = ["_static"]
+htmlhelp_basename = "toastydoc"
 
 intersphinx_mapping = {
-    'python': (
-        'https://docs.python.org/3/',
-        (None, 'http://data.astropy.org/intersphinx/python3.inv')
+    "python": (
+        "https://docs.python.org/3/",
+        (None, "http://data.astropy.org/intersphinx/python3.inv"),
     ),
-
-    'astropy': (
-        'https://docs.astropy.org/en/stable/',
-        None
-    ),
-
-    'numpy': (
-        'https://numpy.org/doc/stable/',
-        (None, 'http://data.astropy.org/intersphinx/numpy.inv')
-    ),
-
-    'PIL': (
-        'https://pillow.readthedocs.io/en/stable/',
-        None
-    ),
-
-    'wwt_data_formats': (
-        'https://wwt-data-formats.readthedocs.io/en/stable/',
-        None
+    "astropy": ("https://docs.astropy.org/en/stable/", None),
+    "numpy": (
+        "https://numpy.org/doc/stable/",
+        (None, "http://data.astropy.org/intersphinx/numpy.inv"),
     ),
+    "PIL": ("https://pillow.readthedocs.io/en/stable/", None),
+    "wwt_data_formats": ("https://wwt-data-formats.readthedocs.io/en/stable/", None),
 }
 
 numpydoc_show_class_members = False
 
 nitpicky = True
-nitpick_ignore = [
-    ('py:class', 'ipywidgets.widgets.domwidget.DOMWidget')
-]
+nitpick_ignore = [("py:class", "ipywidgets.widgets.domwidget.DOMWidget")]
 
-default_role = 'obj'
+default_role = "obj"
 
-html_logo = 'images/logo.png'
+html_logo = "images/logo.png"
 
 linkcheck_retries = 5
 linkcheck_timeout = 10

docs/toasting.rst

@@ -35,12 +35,12 @@ workflow in this case is as follows:
    which the curved surface of the sphere is mapped onto a 2D image. For
    full-sphere imagery, only a few choices are ever used: probably the main
    thing to check is whether your image is in equatorial (RA/Dec) or galactic
-   (l/b) coordinates. 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.
+   (l/b) coordinates. Consult the :ref:`cli-tile-allsky` documentation (or
+   :ref:`cli-tile-healpix`) 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.
+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
@@ -124,7 +124,7 @@ workflow in this case is as follows:
 
 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://myserver.org/datasetname/index.wtml``_ will yield the
+    ``http://myserver.org/datasetname/index.wtml`` will yield the
     ``index.wtml`` file created in the previous step.
 
 .. _file a request: https://github.com/WorldWideTelescope/toasty/issues/

setup.py

@@ -1,5 +1,5 @@
 # -*- mode: python; coding: utf-8 -*-
-# Copyright 2013-2020 Chris Beaumont and the AAS WorldWide Telescope team
+# Copyright 2013-2022 Chris Beaumont and the AAS WorldWide Telescope team
 # Licensed under the MIT License
 
 from __future__ import absolute_import, division, print_function
@@ -39,7 +39,7 @@ def get_long_desc():
 
 setup_args = dict(
     name="toasty",  # cranko project-name
-    version="0.16.1",  # cranko project-version
+    version="0.17.0",  # cranko project-version
     description="Generate TOAST image tile pyramids from existing image data",
     long_description=get_long_desc(),
     long_description_content_type="text/markdown",
@@ -78,7 +78,7 @@ def get_long_desc():
         "reproject",
         "shapely",
         "tqdm>=4.0",
-        "wwt_data_formats>=0.12",
+        "wwt_data_formats>=0.13",
     ],
     extras_require={
         "test": [