Generating a representation file from an X-ray binary table for download is one solution to the large file problem. It does require setting up server-side parent file processing (including temporary storage of image section files). An alternative that does not require a server-side helper is to create a special PNG representation file explicitly tied to the original event data. Once downloaded into JS9, the image can be reconstructed from this file for display. The file maintains information about the original FITS binary table for use in remote analysis. The idea is that you create a representation file from the original FITS binary table and use that file for display in JS9, while supporting server-side analysis on the original FITS event file.

Display of a representation file is fully integrated into JS9:

• The relatively small PNG file is downloaded and read using standard, optimized browser support.
• RGB image values are retrieved using getImageData() into an off-screen (non-visible) canvas. This is the packed representation of the FITS file.
• The FITS header is extracted into a JavaScript object, and actual image dimensions and datatype are determined.
• The original image data is unpacked into an HTML5 typed array of the specified data type, with endian conversion applied as necessary.
• The standard DS9 algorithm is applied to this array to convert pixel values to an array of RGB values.
• The converted RGB array is sent to the screen using putImageData() and displayed by the browser.

Using this representation file, image data values are available to the client JavaScript code without having to download the much larger binary table. This means that the contrast/bias conversion can be performed, image positions/values displayed, etc. using standard browser capabilities and relatively straight-forward array manipulation code. Browser-based image plugins can process the image data, and JS9 can communicate with a server to provide more sophisticated FITS-based analysis support.

Note that JS9 is able to distinguish between PNG representation files and ordinary PNG files and will correctly load either type.

The PNG Representation File

The PNG representation file contains the following information:

• fitsfile: the pathname of the FITS file used to generate this PNG file, including the FITS bracket extension (if present)
• fitsheader: a FITS header containing the WCS information for the generated image
• image: a PNG image containing a json version of the FITS header and image data (in its native data type) packed into RGB triplets

Generating the PNG file using tpos and fits2png

[NB: A maximum image size is enforced by Apple on Safari mobile devices. (See https://discussions.apple.com/thread/4975106 for a discussion.) If you want your JS9 PNG representation files to display on iPhones and iPads, they should be restricted to a size of less than approximately 1900x1900, depending on the size of the FITS header. So a PNG file of size 1024x1024 should be fine, while a file of size 2048x2048 certainly will be too large. (April 9, 2015)] A PNG representation file can be created either statically or dynamically at display time as needed. The low-level tpos program and high-level fits2png script facilitate this conversion:

    tpos [ifits] [opng]
    switches:
    -b bl       # block factor for binary tables (cfitsio only)
    -e list     # list of event extensions to look for (cfitsio only)
    -f filter   # filter for binary tables (cfitsio only)
    -s sect     # section string for binary tables (cfitsio only)
or
    fits2png [switches] [ifits] [opng]
    switches:
    -abs	# convert relative path to absolute path for storage in PNG
    -gzip       # assume the file is in gzip format, regardless of its extension
    -dim	# dimension for PNG image (use to calculate block factor)
    -js9	# set dim, odir, repl parameters for automatic JS9  conversion
    -odir	# specify output directory (default: from opng path)
    -repl	# replace existing PNG? (default: true)

The tpos program can be linked against either the cfitsio library or the funtools library, depending on how you configured your JS9 build. (Note that funtools is deprecated. Please use cfitsio where possible.)

The fits2png switches are meant to provide flexibility when running tpos in batch mode. The fits2png script also is used to generate PNG files on the fly (i.e., when offering FITS files on your web page directly instead of the PNG representation.) Note that if you have linked against cfitsio, you must ensure that the HEASOFT environment is set up properly when running fits2png.

By default, tpos and fits2png will convert a FITS image or binary table to a PNG representation file having the same image dimensions:

    tpos m13.fits m13.png

    tpos -s "1024@4027,1024@3944" -b 2 casa.fits casa.png    # cfitsio
or:
    tpos 'casa.fits[1024@4027,1024@3944,2]' casa.png         # funtools

For automatic processing with fits2png, specifying the -dims switch will tell fits2png to calculate the block factor in such a way as to generate an image of the specified size:

    fits2png -dims 512 512 casa.fits casa.png

In addition to the image, the (generated) FITS image header and the FITS pathname are stored in the PNG file for use by both the browser and the server-side helper programs. The image header is used to provide WCS information for individual pixels as the mouse is moved across the image. It also is used to provide region information in WCS format (i.e. independent of block factor). The FITS pathname is used to locate the original FITS file in order to execute analysis tasks.

In order to run analysis tasks, the FITS data must be accessible to the server-side helper program. Therefore, it seems preferable to store an absolute pathname in the PNG file, but more experience is needed on this score. You can specify the absolute pathname on the tpos command line, or else specify the -abs switch on fits2png and it will be determined by the script.

If you store a relative path in the PNG file, note that this path will be utilized by the server-side JS9 helper to locate the FITS file. This means that if the helper is not started in the same directory that tpos (fits2png) was run, the relative path will not be correct. In this case, you can set the JS9.analOpts.dataDir parameter in the js9prefs.js file to a path that will be used instead of the relative path.

You also must decide where to store the PNG files, e.g. with the FITS data or in a separate directory. Clearly, this will depend on how your archive is set up and where you have write access. By default, PNG files will simply be stored in the path specified on the tpos command line. You can use the -odir switch on the fits2png script to specify a generic location:

    tpos ./png ./fits/casa.fits ./png/casa.png    # store in png subdirectory
    tpos -odir ./png ./fits/casa.fits casa.png    # same

The -odir switch can be used to specify a session-based directory in which to store PNG files. This facility could be used, for example, in a case where each user has files stored in her or her own directory, which might be removed at the end of the session. To facilitate session-based directory specification, a standard HTML cookie is used to pass the session information between client and server as follows:

• When a JS9-enabled page is loaded, a cookie is set containing the session id in the web page. For example, one might a set a cookie whose name is JS9_ID and whose values is 0x1234.
• The odir switch is given a directory value containing the cookie name as part of the string, preceded by a percent sign, %. For example, odir might be set to ./png/%JS9_ID.
• When fits2png is executed, the %cookie name is replaced by the cookie value. In the example above, the resulting odir value is ./png/0x1234.
• The PNG representation file is stored in this odir directory, as usual.

Finally, the special value of @IFILE@ tells fits2png to store the PNG file in the same directory as the FITS file:

    tpos -odir @IFILE@ .../casa.fits casa.png     # store PNG with FITS file

Regardless of where the PNG files are stored, you must adhere to the W3C "same-origin" security policy, i.e. the PNG data files must be hosted on the same web server as the JS9 code. This means that your PNG files must either be stored in the web site directory tree, or you must make a link within the web site tree to the top level PNG directory. Also note that Google Chrome's implementation of this policy prevents you from using JS9 with a file:// URL. (On Linux and Macs, you can start Chrome with the --allow-file-access-from-files switch to work around this restriction.)

Loading a PNG File From Your Web Page

Once you have generated your PNG files, you can make them available on your JS9 web page by creating URLs that call the JS9.Load() routine:

    href='javascript:JS9.Load(filename, opts);'

For example:

    href='javascript:JS9.Load("png/casa.png", {scale: "log"});'

See JS9 Public API for complete documentation about the JS9.Load() routine.

Run-time Conversion of FITS to PNG

If you don't generate PNG files beforehand, you can still specify a FITS file as the first argument to JS9.Load() and have the JS9 server-side helper run fits2png at run-time.. To do this, you set the fits2png property in js9prefs.js:

{
  "globalOpts": {"fits2png": true ...}
}

    href='javascript:JS9.Load("fits/3c58.fits");'

    fits2png -js9 -odir ./png