Merge pull request #87 from pkgw/remote-view

Add tunneled "view" capability

README.md

@@ -80,7 +80,7 @@ and [PyPI](https://pypi.org/project/toasty/#history).
 - [pytest] to run the test suite
 - [PyYAML]
 - [tqdm]
-- [wwt_data_formats] >= 0.10.2
+- [wwt_data_formats] >= 0.15
 
 [Astronomy Visualization Metadata]: https://virtualastronomy.org/avm_metadata.php
 [astropy]: https://www.astropy.org/

docs/cli/view.rst

@@ -26,17 +26,27 @@ Detailed Usage
 .. code-block:: shell
 
    toasty view
+      [--tunnel HOST, -t HOST]
       [--appurl URL]
       [--blankval NUMBER]
       [--browser BROWSER, -b BROWSER]
       [--hdu-index INDEX[,INDEX,...]]
       [--parallelism COUNT, -j COUNT]
+      [--tile-only]
       {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 ``-t HOST`` or ``--tunnel HOST`` option can be used to view an image stored
+on the remote machine named ``HOST``, using `SSH`_. In order for this work, SSH
+`connection sharing`_ must be enabled, and Toasty must be installed on the
+destination machine. See more in :ref:`cli-view-tunneled` below.
+
+.. _SSH: https://en.wikipedia.org/wiki/Secure_Shell
+.. _connection sharing: https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing
+
 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
@@ -61,6 +71,9 @@ 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.
 
+If the ``--tile-only`` option is specified, the data are tiled but no web
+browser is launched. This can be useful when automating Toasty workflows.
+
 
 Details
 =======
@@ -83,6 +96,60 @@ be used. Otherwise, Toasty will reproject the input data into a tangential
 
 
 
+.. _cli-view-tunneled:
+
+Tunneled Image Viewing
+======================
+
+The “tunneled” mode of this command allows you to view images that live on
+another machine.
+
+The basic usage of this mode is
+
+
+.. code-block:: shell
+
+   toasty view -t HOST 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
+destination user's home directory. Or, absolute paths are also OK.
+
+Here, ``HOST`` is any hostname that will be accepted by your ``ssh`` program.
+This means that it can be a “virtual” host alias set up in your ``.ssh/config``
+file, for instance.
+
+In order for this functionality to work, it is necessary that the SSH commands
+will not need to prompt you interactively in order to log in. This requires that
+either you have key-based SSH authentication set up, with passphrase-less keys
+or a key agent running, *or* that SSH connection reuse is activated for the
+target host, and you have an existing SSH connection to the host open. The
+program `stund`_ can be helpful for setting up long-lived connections to avoid
+password prompts.
+
+.. _stund: https://github.com/pkgw/stund
+
+The target host must also have Toasty installed, such that if you log in to a
+terminal over SSH, the command ``toasty`` is available.
+
+In tunneled mode, the following sequence of events happens:
+
+1. SSH is used to run a ``toasty view`` command on the target host to tile the
+   requested data sets. Relevant flags such as ``-j`` / ``--parallelism`` are
+   forwarded to the remote host.
+2. SSH is used to run a ``wwtdatatool serve`` command on the target host,
+   starting an HTTP-based data server.
+3. A local SSH port forward is created so that the HTTP server can be accessed
+   from the local machine.
+4. A local web browser is launched with the proper setup to view the data via
+   the port forward.
+5. When the local command is stopped, the remote HTTP server is shut down, and
+   the port forward is cancelled.
+
+The remote HTTP server is set up in a way where it should shut down
+automatically if the SSH connection is dropped for any reason.
+
+
 See Also
 ========
 

setup.py

@@ -2,11 +2,8 @@
 # Copyright 2013-2022 Chris Beaumont and the AAS WorldWide Telescope team
 # Licensed under the MIT License
 
-from __future__ import absolute_import, division, print_function
-
 from Cython.Distutils import build_ext  # in pyproject.toml
 import numpy as np  # in pyproject.toml
-import os
 from setuptools import setup, Extension
 
 
@@ -52,10 +49,10 @@ def get_long_desc():
         "Intended Audience :: Science/Research",
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
-        "Programming Language :: Python :: 2.7",
-        "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
         "Topic :: Scientific/Engineering :: Astronomy",
         "Topic :: Scientific/Engineering :: Visualization",
     ],
@@ -78,7 +75,7 @@ def get_long_desc():
         "reproject",
         "shapely",
         "tqdm>=4.0",
-        "wwt_data_formats>=0.13",
+        "wwt_data_formats>=0.15",
     ],
     extras_require={
         "test": [