Implement a --tiling-method argument for "toasty view"

docs/cli/view.rst

@@ -33,6 +33,7 @@ Detailed Usage
       [--hdu-index INDEX[,INDEX,...]]
       [--parallelism COUNT, -j COUNT]
       [--tile-only]
+      [--tiling-method METHOD]
       {FITS [FITS ...]}
 
 The ``FITS`` argument(s) give the path(s) of one or more input FITS files. These
@@ -67,6 +68,17 @@ 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 ``--tiling-method METHOD`` argument indicates the target projection to use
+when tiling the data. The default value, ``auto``, causes Toasty to use a
+heuristic to automatically determine the best method. Other valid values are
+``tan`` (to use a tangential/gnomonic projection, only valid for relatively
+small areas on the sky), ``toast`` (for `TOAST`_, best in WWT for large-area
+images), or ``hips`` (for `HiPS`_).
+
+.. _TOAST: https://docs.worldwidetelescope.org/data-guide/1/spherical-projections/toast-projection/
+
+.. _HiPS: https://www.ivoa.net/documents/HiPS/
+
 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.
@@ -109,7 +121,7 @@ The basic usage of this mode is
 
 .. code-block:: shell
 
-   toasty view -t HOST FITS1 [FITS2...]
+   toasty view -t HOST [other arguments...] FITS1 [FITS2...]
 
 where ``HOST`` is the hostname of the machine with the image(s), and the
 ``FITSn`` values are the paths of the images on the machine relative to the

toasty/cli.py

@@ -884,6 +884,12 @@ def view_getparser(parser):
         action="store_true",
         help="Tile the data but do not open for viewing",
     )
+    parser.add_argument(
+        "--tiling-method",
+        default="auto",
+        choices=["auto", "tan", "toast", "hips"],
+        help="The target projection when tiling: `auto`, `tan`, `toast`, or `hips`",
+    )
     parser.add_argument(
         "paths",
         metavar="PATHS",
@@ -895,15 +901,28 @@ def view_getparser(parser):
 
 def view_locally(settings):
     from wwt_data_formats.server import preview_wtml
+    from . import TilingMethod
     from .collection import CollectionLoader
     from .fits_tiler import FitsTiler
 
+    if settings.tiling_method == "auto":
+        tiling_method = TilingMethod.AUTO_DETECT
+    elif settings.tiling_method == "tan":
+        tiling_method = TilingMethod.TAN
+    elif settings.tiling_method == "toast":
+        tiling_method = TilingMethod.TOAST
+    elif settings.tiling_method == "hips":
+        tiling_method = TilingMethod.HIPS
+    else:
+        # This shouldn't happen since argparse should validate the input
+        die(f"unhandled tiling method `{settings.tiling_method}`")
+
     coll = CollectionLoader.create_from_args(settings).load_paths(settings.paths)
 
     # Ignore any astropy WCS/FITS warnings, which can spew a lot of annoying output.
     with warnings.catch_warnings():
         warnings.simplefilter("ignore")
-        tiler = FitsTiler(coll)
+        tiler = FitsTiler(coll, tiling_method=tiling_method)
         tiler.tile(cli_progress=True, parallel=settings.parallelism)
 
     rel_wtml_path = os.path.join(tiler.out_dir, "index_rel.wtml")
@@ -941,7 +960,8 @@ def view_tunneled(settings):
     # We give SSH `-T` to prevent warnings about not allocating pseudo-TTYs.
 
     ssh_argv = ["ssh", "-T", settings.tunnel]
-    toasty_argv = ["exec", "toasty", "view", "--tile-only"]
+    toasty_argv = ["exec", "toasty", "view", "--tile-only", f"--tiling-method={settings.tiling_method}"]
+
     if settings.parallelism:
         toasty_argv += ["--parallelism", str(settings.parallelism)]
     toasty_argv += [shlex.quote(p) for p in settings.paths]