Merge pull request #69 from imbasimba/hipsgen

Hipsgen

docs/api.rst

@@ -18,6 +18,10 @@ Python API Reference
    :no-inheritance-diagram:
    :no-inherited-members:
 
+.. automodapi:: toasty.fits_tiler
+   :no-inheritance-diagram:
+   :no-inherited-members:
+
 .. automodapi:: toasty.image
    :no-inheritance-diagram:
    :no-inherited-members:

docs/api/toasty.collection.CollectionLoader.rst

@@ -0,0 +1,33 @@
+CollectionLoader
+================
+
+.. currentmodule:: toasty.collection
+
+.. autoclass:: CollectionLoader
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~CollectionLoader.blankval
+      ~CollectionLoader.hdu_index
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~CollectionLoader.add_arguments
+      ~CollectionLoader.create_from_args
+      ~CollectionLoader.load_paths
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: blankval
+   .. autoattribute:: hdu_index
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: add_arguments
+   .. automethod:: create_from_args
+   .. automethod:: load_paths

docs/api/toasty.collection.ImageCollection.rst

@@ -11,9 +11,11 @@ ImageCollection
    .. autosummary::
 
       ~ImageCollection.descriptions
+      ~ImageCollection.export_simple
       ~ImageCollection.images
 
    .. rubric:: Methods Documentation
 
    .. automethod:: descriptions
+   .. automethod:: export_simple
    .. automethod:: images

docs/api/toasty.collection.SimpleFitsCollection.rst

@@ -11,9 +11,11 @@ SimpleFitsCollection
    .. autosummary::
 
       ~SimpleFitsCollection.descriptions
+      ~SimpleFitsCollection.export_simple
       ~SimpleFitsCollection.images
 
    .. rubric:: Methods Documentation
 
    .. automethod:: descriptions
+   .. automethod:: export_simple
    .. automethod:: images

docs/api/toasty.collection.load.rst

@@ -0,0 +1,6 @@
+load
+====
+
+.. currentmodule:: toasty.collection
+
+.. autofunction:: load

docs/api/toasty.fits_tiler.FitsTiler.rst

@@ -0,0 +1,37 @@
+FitsTiler
+=========
+
+.. currentmodule:: toasty.fits_tiler
+
+.. autoclass:: FitsTiler
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~FitsTiler.builder
+      ~FitsTiler.coll
+      ~FitsTiler.force_hipsgen
+      ~FitsTiler.force_tan
+      ~FitsTiler.out_dir
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~FitsTiler.should_use_hipsgen
+      ~FitsTiler.tile
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: builder
+   .. autoattribute:: coll
+   .. autoattribute:: force_hipsgen
+   .. autoattribute:: force_tan
+   .. autoattribute:: out_dir
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: should_use_hipsgen
+   .. automethod:: tile

docs/cli.rst

@@ -19,3 +19,4 @@ CLI Reference
    cli/tile-study
    cli/tile-wwtl
    cli/transform-fx3-to-rgb
+   cli/view

docs/cli/tile-study.rst

@@ -65,3 +65,4 @@ See Also
 ========
 
 - :ref:`cli-check-avm`
+- :ref:`cli-view`

docs/cli/view.rst

@@ -0,0 +1,91 @@
+.. _cli-view:
+
+=======================
+``toasty view``
+=======================
+
+The ``view`` command allows you view one or more FITS files using the `WWT
+research app`_.
+
+.. _WWT research app: https://docs.worldwidetelescope.org/research-app/latest/
+
+
+Example
+=======
+
+View a FITS file:
+
+.. code-block:: shell
+
+   toasty view myfile.fits
+
+
+Detailed Usage
+==============
+
+.. code-block:: shell
+
+   toasty view
+      [--appurl URL]
+      [--blankval NUMBER]
+      [--browser BROWSER, -b BROWSER]
+      [--hdu-index INDEX[,INDEX,...]]
+      [--parallelism COUNT, -j COUNT]
+      {FITS [FITS ...]}
+
+The ``FITS`` argument(s) give the path(s) of one or more input FITS files. These
+will be automatically tiled if necessary, then made available on a local web
+server so that the WWT viewer can access the data.
+
+The ``-b`` or ``--browser`` option specifies which web browser to use, using an
+identifier as understood by the `Python "webbrowser" module`_. Typical choices
+might be ``firefox``, ``safari``, or ``google-chrome``. If unspecified, a
+sensible default will be used.
+
+.. _Python "webbrowser" module: https://docs.python.org/3/library/webbrowser.html
+
+The ``--hdu-index`` argument, if specified, fixes the index number of the FITS
+HDU to load from the input file(s). If one value is provided, that index will be
+used for every FITS file. If a comma-separated list is provided, the index
+corresponding to each index path will be used.
+
+The ``--blankval`` argument, if specified, gives a data value to be treated as
+undefined data when processing the FITS data.
+
+The ``--parallelism COUNT`` (or ``-j COUNT``) argument specifies the level of
+parallism to use in the tiling and downsampling process. On operating systems
+that support parallel processing, the default is to use all CPUs. To disable
+parallel processing, explicitly specify a factor of 1.
+
+The ``--appurl`` option can be used to override the base URL for the preview app
+that will be used. This can be helpful when developing new features in one of
+these apps.
+
+
+Details
+=======
+
+This command provides similar functionality as the ``wwtdatatool preview``
+command `provided by the wwt_data_formats package`_, but automatically tiles its
+inputs and generates the needed ``index_rel.wtml`` file.
+
+.. _provided by the wwt_data_formats package: https://wwt-data-formats.readthedocs.io/en/latest/cli/preview.html
+
+If tiling is required and the tile output directory already exists, the tool
+assumes that the image was already successfully tiled, and skips straight to
+launching the viewer without rerunning the tiling process.
+
+The FITS data will be tiled either onto a common tangential projection, or into
+a HiPS format using `hipsgen`_, depending on the angular size subtended by the
+data. If any of the FITS image corners are separated by more than 20 degrees and
+Java is available, `hipsgen`_ will be used. Otherwise, Toasty's internal
+processing will be used, reprojecting the input data into a tangential
+(gnomonic) projection if necessary.
+
+.. _hipsgen: https://aladin.u-strasbg.fr/hips/HipsIn10Steps.gml
+
+
+See Also
+========
+
+- :ref:`cli-tile-study`

toasty/__init__.py

@@ -5,24 +5,53 @@
 from __future__ import absolute_import, division, print_function
 
 
-def tile_fits(fits, out_dir=None, cli_progress=False, **kwargs):
+__all__ = [
+    "tile_fits",
+]
+
+
+def tile_fits(
+    fits,
+    out_dir=None,
+    hdu_index=None,
+    override=False,
+    cli_progress=False,
+    force_hipsgen=False,
+    force_tan=False,
+    blankval=None,
+    **kwargs
+):
     """
-    Process a file or a list of FITS files into a tile pyramid with
-    a common tangential projection.
+    Process a file or a list of FITS files into a tile pyramid using either a common tangential projection or HiPSgen.
 
     Parameters
     ----------
     fits : str or list of str
         A single path or a list of paths to FITS files to be processed.
-    out_dir : optional str
-        A path to the output directory where all the tiled fits will be
-        located. If not set, the output directory will be at the location of
-        the first FITS file.
-    cli_progress : optional boolean, defaults False
-        If true, a progress bar will be printed to the terminal using tqdm.
+    out_dir : optional str, defaults to None
+        A path to the output directory where all the tiled fits will be located. If not set, the output directory will
+        be at the location of the first FITS file.
+    hdu_index : optional int or list of int, defaults to None
+        Use this parameter to specify which HDU to tile. If the *fits* input is a list of FITS, you can specify the
+        hdu_index of each FITS by using a list of integers like this: [0, 2, 1]. If hdu_index is not set, toasty will
+        use the first HDU with tilable content in each FITS.
+    override : optional boolean, defaults to False
+        If there is already a tiled FITS in *out_dir*, the tiling process is skipped and the content in *out_dir* is
+        served. To override the content in *out_dir*, set *override* to True.
+    cli_progress : optional boolean, defaults to False
+        If true, progress messages will be printed as the FITS files are being processed.
+    force_hipsgen : optional boolean, defaults to False
+        Force usage of HiPSgen tiling over tangential projection. If this and *force_tan* are set to False, this method
+        will figure out when to use the different projections. Tangential projection for smaller angular areas and
+        HiPSgen larger regions of the sky.
+    force_tan : optional boolean, defaults to False
+        Force usage of tangential projection tiling over HiPSgen. If this and *force_hipsgen* are set to False, this
+        method will figure out when to use the different projections. Tangential projection for smaller angular areas
+        and HiPSgen larger regions of the sky.
+    blankval : optional number, default None
+        An image value to treat as undefined in all FITS inputs.
     kwargs
-        Settings for the `toasty` tiling process. Common
-        settings include 'hdu_index' and 'blankval'.
+        Settings for the tiling process. For example, ``blankval``.
 
     Returns
     -------
@@ -31,39 +60,15 @@ def tile_fits(fits, out_dir=None, cli_progress=False, **kwargs):
     bld : :class:`~toasty.builder.Builder`
         State for the imagery data set that's been assembled.
     """
+    # Importing here to keep toasty namespace clean:
+    from toasty import collection, fits_tiler
 
-    from toasty import builder, collection, pyramid, multi_tan, multi_wcs
-    import reproject
-
-    if isinstance(fits, str):
-        fits = [fits]
-
-    fits = list(fits)
-
-    if out_dir is None:
-        first_file_name = fits[0].split('.gz')[0]
-        out_dir = first_file_name[:first_file_name.rfind('.')] + '_tiled'
-
-    pio = pyramid.PyramidIO(out_dir, default_format='fits')
-    bld = builder.Builder(pio)
-    coll = collection.SimpleFitsCollection(fits, **kwargs)
-    if cli_progress:
-        print('Tiling base layer (Step 1 of 2)')
-    if coll._is_multi_tan():
-        tile_processor = multi_tan.MultiTanProcessor(coll)
-        tile_processor.compute_global_pixelization(bld)
-        tile_processor.tile(pio, cli_progress=cli_progress, **kwargs)
-    else:
-        tile_processor = multi_wcs.MultiWcsProcessor(coll)
-        tile_processor.compute_global_pixelization(bld)
-        tile_processor.tile(pio, reproject.reproject_interp, cli_progress=cli_progress, **kwargs)
-
-    if cli_progress:
-        print('Downsampling (Step 2 of 2)')
-    bld.cascade(cli_progress=cli_progress, **kwargs)
-
-    # Using the file name of the first FITS file as the image collection name
-    bld.set_name(out_dir.split('/')[-1])
-    bld.write_index_rel_wtml()
-
-    return out_dir, bld
+    coll = collection.load(fits, hdu_index=hdu_index, blankval=blankval)
+    tiler = fits_tiler.FitsTiler(
+        coll,
+        out_dir=out_dir,
+        force_hipsgen=force_hipsgen,
+        force_tan=force_tan,
+    )
+    tiler.tile(cli_progress=cli_progress, override=override, **kwargs)
+    return tiler.out_dir, tiler.builder