toasty view

The view command allows you view one or more FITS files using the WWT research app.

Example

View a FITS file:

toasty view myfile.fits

Detailed Usage

toasty view
   [--tunnel HOST, -t HOST]
   [--appurl URL]
   [--blankval NUMBER]
   [--browser BROWSER, -b BROWSER]
   [--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 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 Tunneled Image Viewing below.

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.

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 --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).

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

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.

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 TOAST, depending on the angular size subtended by the data. If any of the FITS image corners are separated by more than 20 degrees, the TOAST format will be used. Otherwise, Toasty will reproject the input data into a tangential (gnomonic) projection if necessary.

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

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 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.

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