Release request commit created with Cranko.

+++ cranko-rc-info-v1
[[projects]]
qnames = ["toasty", "pypa"]
bump_spec = "minor bump"

+++

CHANGELOG.md

@@ -1,5 +1,16 @@
 # rc: minor bump
 
+- Fix up `toasty tile-study` to handle FITS files properly (@pkgw, #61). The
+ input must be in a tangential projection, and only some basic data layouts
+ within the FITS container are supported. The `--placeholder-thumbnail` option
+ also must be used.
+- Fix an off-by-one error in the computations used by `toasty tile-multi-tan`
+ (@pkgw, #61)
+- Improve some internal APIs for processing studies.
+
+
+# toasty 0.10.0 (2021-09-10)
+
 - Add `toasty check-avm`, which opens up an image file and reports whether it
  contains AVM (Astronomy Visualization Metadata) tags. This requires that the
  `pyavm` module is installed (#59, @pkgw).

README.md

@@ -15,8 +15,9 @@ maps can be viewed in software such as the [AAS] [WorldWide Telescope].
 [AAS]: https://aas.org/
 [WorldWide Telescope]: http://www.worldwidetelescope.org/
 
-[toasty] was originally written by [Chris Beaumont] and is currently maintained
-as part of the AAS [WorldWide Telescope] project.
+[toasty] was originally written by [Chris Beaumont], benefited from
+contributions by Clara Brasseur (Space Telescope Science Institute), and is
+currently maintained as part of the AAS [WorldWide Telescope] project.
 
 [Chris Beaumont]: https://chrisbeaumont.org/
 <!--pypi-end-->
@@ -75,11 +76,13 @@ and [PyPI](https://pypi.org/project/toasty/#history).
 - [healpy] if using [HEALPix] maps
 - [numpy]
 - [pillow]
+- [pyavm] if using [Astronomy Visualization Metadata] tags
 - [pytest] to run the test suite
 - [PyYAML]
 - [tqdm]
 - [wwt_data_formats] >= 0.7
 
+[Astronomy Visualization Metadata]: https://virtualastronomy.org/avm_metadata.php
 [astropy]: https://www.astropy.org/
 [azure-storage-blob]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/storage/azure-storage-blob
 [cython]: https://cython.org/
@@ -88,6 +91,7 @@ and [PyPI](https://pypi.org/project/toasty/#history).
 [HEALPix]: https://healpix.jpl.nasa.gov/
 [numpy]: https://numpy.org/
 [pillow]: https://pillow.readthedocs.io/
+[pyavm]: https://astrofrog.github.io/pyavm/
 [pytest]: https://docs.pytest.org/
 [PyYAML]: https://github.com/yaml/pyyaml
 [tqdm]: https://tqdm.github.io/

ci/azure-build-and-test.yml

@@ -104,6 +104,8 @@ jobs:
  pyavm \
  pytest-cov \
  pyyaml \
+ reproject \
+ shapely \
  tqdm
  pip install wwt_data_formats
  pip install -e .

docs/api/toasty.builder.Builder.rst

@@ -23,9 +23,11 @@ Builder
  ~Builder.cascade
  ~Builder.create_wtml_folder
  ~Builder.default_tiled_study_astrometry
+ ~Builder.execute_study_tiling
  ~Builder.load_from_wwtl
  ~Builder.make_placeholder_thumbnail
  ~Builder.make_thumbnail_from_other
+ ~Builder.prepare_study_tiling
  ~Builder.set_name
  ~Builder.tile_base_as_study
  ~Builder.toast_base
@@ -44,9 +46,11 @@ Builder
  .. automethod:: cascade
  .. automethod:: create_wtml_folder
  .. automethod:: default_tiled_study_astrometry
+ .. automethod:: execute_study_tiling
  .. automethod:: load_from_wwtl
  .. automethod:: make_placeholder_thumbnail
  .. automethod:: make_thumbnail_from_other
+ .. automethod:: prepare_study_tiling
  .. automethod:: set_name
  .. automethod:: tile_base_as_study
  .. automethod:: toast_base

setup.py

@@ -87,6 +87,7 @@ def get_long_desc():
  'pytest-cov',
  ],
  'docs': [
+ 'astropy',
  'astropy-sphinx-theme',
  'numpydoc',
  'sphinx',

toasty/builder.py

@@ -71,7 +71,74 @@ def _check_no_wcs_yet(self):
  raise Exception('order-of-operations error: you must apply WCS after applying tiling settings')
 
 
+ def prepare_study_tiling(self, image):
+ """
+ Set up to tile the specified image as a WWT "study".
+
+ Parameters
+ ----------
+ image : `toasty.image.Image`
+ The image that will be tiled
+
+ Returns
+ -------
+ tiling : `toasty.study.StudyTiling`
+ The prepared tiling information
+
+ Remarks
+ -------
+ After calling this method, you should set up the WCS for the tiled
+ imagery, using :meth:`default_tiled_study_astrometry` as a backstop if
+ no real information is available. Then use :meth:`execute_study_tiling`
+ to actually perform the tiling process.
+ """
+
+ from .study import StudyTiling
+
+ tiling = StudyTiling(image.width, image.height)
+ tiling.apply_to_imageset(self.imgset)
+ return tiling
+
+
+ def execute_study_tiling(self, image, tiling, **kwargs):
+ """
+ Tile the specified image as a WWT "study".
+
+ Parameters
+ ----------
+ image : `toasty.image.Image`
+ The image that will be tiled
+ tiling : `toasty.study.StudyTiling`
+ The prepared tiling information
+ **kwargs
+ Arguments relayed to :meth:`toasty.study.StudyTiling.tile_image`,
+ such as ``cli_progress``.
+
+ Returns
+ -------
+ *self*
+ """
+
+ tiling.tile_image(image, self.pio, **kwargs)
+ return self
+
+
  def tile_base_as_study(self, image, **kwargs):
+ """
+ Tile an image assuming that it is in the appropriate format for WWT's
+ "study" framework, namely that it uses a tangential (gnomonic)
+ projection on the sky.
+
+ Use of this method is somewhat discouraged since it both analyzes and
+ performs the tiling all at once, which means that you can only correctly
+ set (and validate) the WCS information *after* doing all the work of
+ tiling. (Which in turn is because the proper way to apply WCS
+ information to an imageset depends on the tiling parameters.) It is
+ generally better to use :meth:`prepare_study_tiling` and
+ :meth:`execute_study_tiling`, applying the WCS metadata in between, so
+ that WCS errors can be caught and reported before doing the I/O.
+ """
+
  from .study import tile_study_image
 
  self._check_no_wcs_yet()

toasty/cli.py

@@ -418,6 +418,13 @@ def tile_study_impl(settings):
  pio = PyramidIO(settings.outdir, default_format=img.default_format)
  builder = Builder(pio)
 
+ # First, prepare the tiling, because we can't correctly apply WCS until we
+ # know the details of the tiling parameters
+
+ tiling = builder.prepare_study_tiling(img)
+
+ # Now deal with the WCS
+
  if settings.avm:
  # We don't *always* check for AVM because pyavm prints out a lot of junk
  # and may not be installed.
@@ -433,22 +440,26 @@ def tile_study_impl(settings):
  except Exception:
  print(f'error: failed to read AVM tags of input `{settings.imgpath}`', file=sys.stderr)
  raise
+
+ builder.apply_avm_info(avm, img.width, img.height)
+ elif img.wcs is not None:
+ # Study images must have negative parity.
+ img.ensure_negative_parity()
+ builder.apply_wcs_info(img.wcs, img.width, img.height)
  else:
  builder.default_tiled_study_astrometry()
 
- # Do the thumbnail first since for large inputs it can be the memory high-water mark!
+ # Do the thumbnail before the main image since for large inputs it can be
+ # the memory high-water mark!
  if settings.placeholder_thumbnail:
  builder.make_placeholder_thumbnail()
  else:
  builder.make_thumbnail_from_other(img)
 
- builder.tile_base_as_study(img, cli_progress=True)
-
- if settings.avm:
- builder.apply_avm_info(avm, img.width, img.height)
- elif img.wcs is not None:
- builder.apply_wcs_info(img.wcs, img.width, img.height)
+ # Finally, actually tile the image
+ builder.execute_study_tiling(img, tiling, cli_progress=True)
 
+ # Final metadata
  builder.set_name(settings.name)
  builder.write_index_rel_wtml()
 

toasty/multi_tan.py

@@ -168,8 +168,8 @@ def compute_global_pixelization(self, builder):
  desc.sub_tiling = self._tiling.compute_for_subimage(
  desc.imin,
  desc.jmin,
- desc.imax - desc.imin,
- desc.jmax - desc.jmin,
+ desc.imax + 1 - desc.imin,
+ desc.jmax + 1 - desc.jmin,
  )
 
  self._n_todo += desc.sub_tiling.count_populated_positions()

toasty/study.py

@@ -320,6 +320,12 @@ def tile_image(self, image, pio, cli_progress=False):
  if image.width != self._width:
  raise ValueError('width of image to be sampled does not match tiling')
 
+ # For tiled FITS, the overall input image and tiling coordinate system
+ # need to have negative (JPEG-like) parity, but the individal tiles need
+ # to be saved with positive (FITS-like) parity. The upshot is that we
+ # have to vertically flip the data layout in our tile buffers.
+ invert_into_tiles = pio.get_default_vertical_parity_sign() == 1
+
  # TODO: ideally make_maskable_buffer should be a method
  # on the Image class which could then avoid having to
  # manually transfer _format.
@@ -328,10 +334,21 @@ def tile_image(self, image, pio, cli_progress=False):
 
  with tqdm(total=self.count_populated_positions(), disable=not cli_progress) as progress:
  for pos, width, height, image_x, image_y, tile_x, tile_y in self.generate_populated_positions():
+ if invert_into_tiles:
+ flip_tile_y1 = 255 - tile_y
+ flip_tile_y0 = flip_tile_y1 - height
+
+ if flip_tile_y0 == -1:
+ flip_tile_y0 = None # with a slice, -1 does the wrong thing
+
+ by_idx = slice(flip_tile_y1, flip_tile_y0, -1)
+ else:
+ by_idx = slice(tile_y, tile_y + height)
+
  iy_idx = slice(image_y, image_y + height)
  ix_idx = slice(image_x, image_x + width)
- by_idx = slice(tile_y, tile_y + height)
  bx_idx = slice(tile_x, tile_x + width)
+
  image.fill_into_maskable_buffer(buffer, iy_idx, ix_idx, by_idx, bx_idx)
  pio.write_image(pos, buffer)
  progress.update(1)