Displaying Your Data

Displaying Your Data With JS9

Loading a FITS File From Your Web Page

Once you have your web page set up, you can make your FITS data files available on your JS9 web page by creating URLs that call the JS9.Load() routine:

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

where opts can be:

filename is the path relative to the current web page location
imageOpts: an object containing params to be merged with the default JS9.imageOpts object

For example:

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

Clicking on this URL will load the casa.fits file (here, stored in the fits directory directly beneath the web page location). If the JS9 server-side helper is running, it will be alerted about this new file so that it can run analysis, etc.

As of version 1.3, the cfitsio library is used to process FITS files in JS9. (Technical note: we used emscripten to compile cfitsio to JavaScript, and then added thin C and JavaScript layers to provide an interface to J9.) Thus, you can utilize the cfitsio extended file name syntax to tailor the image data being displayed. For example:

    href='javascript:JS9.Load("fits/snr.fits[events][pi==pha]");'

will display display all photons in the EVENTS binary table having the same pi and pha values. Cfitsio also supports display of arbitrary image extensions, gzip'ed files, tile compressed files, image sections, etc. See the cfitsio documentation for more information.

Note to users who are upgrading to version 1.3: to use cfitsio, simply remove the load of fitsy.js (or fitsy.min.js) from your web page.

To override default image parameters, specify imgOpts parameters as the second argument:

    href='javascript:JS9.Load("fits/m13.fits", {scale:"linear", colormap:"sls"});'

To load an image into a specified display, pass the display id in an object as the last argument in the call. This can be the second or third argument, depending whether the image object also is passed:

    # the display object can be passed as the second argument ...
    href='javascript:JS9.Load("fits/casa.fits", {display: "myJS9"});'
    # but when image opts is also passed, it's the third argument  
    href='javascript:JS9.Load("fits/3c273.fits", {scale: "linear"}, {display: "myJS9"});'

Web browsers do not support allocation of unlimited memory, regardless of the amount available on the given host. It seems that 1Gb is a limit often encountered; trying to allocate more memory can result in browser hangs (e.g., the Mac spinning wheel being displayed indefinitely.) To minimize these problems, JS9 enforces an image size limit using the JS9.globalOpts.maxFITSMemory property. Its default value is 450000000, which supports images of size 10600 x 10600 x 4-bytes. You can change this value in the js9Prefs.json file, or, once JS9 is initialized, reset it via the JS9.fits.maxFITSMemory(bytes) routine.

Memory usage and availability is a fast-moving part of browser technology and we will revise the JS9 limit as warranted. Keep in mind that, in all cases, using a huge amount of memory to display data will result in poor responsiveness.

Pre-Loading a File From Your Web Page

You can pre-load one or more data files into JS9 when the web page itself is loaded by adding the JS9.Preload() routine to the onload event in your web page body element:

<body onload="JS9.Preload('fits/casa.fits', 
		          'fits/snr.fits[events][pi==pha]', {colormap:'heat'},
		          'fits/3c58.fits',
		          'fits/m13.fits', {scale:'linear', colormap:'sls'},
		          'fits/3c273.fits',
		          'fits/ngc1316.fits', {scale:'linear'},
		          'fits/ngkper.fits', {colormap:'grey'});">

Note that this routine takes a list of images, each of which optionally can have an associated imgOpts argument. The display opts can be passed as the final argument and will apply to all images.