Installing JS9

Summary for the Impatient

Retrieve and Unpack the Source Code Tar File

The current JS9 source tar file is available at:

    http://js9.si.edu
The source tar file will unpack into a js9-[version] directory with the usual tar command, e.g:
    tar xfz js9-[version].tar.gz
You also can clone JS9 from GitHub:
    https://github.com/ericmandel/js9

Run JS9 using the file:// URI

Once the tar file is unpacked, you should be able to load any of the js9*.html web pages into your browser using the file:// URI. For example, if you unpacked the tar file into /Users/me on a Mac, then you can point your browser to:
    file:///Users/me/js9-[version]/js9basics.html
to see the basic JS9 demo page. You then can drag any FITS image file onto the JS9 display and view it, change contrast/bias, colormaps, scale, create regions, etc. Furthermore, if you load the imexam web page:
    file:///Users/me/js9-[version]/js9imexam.html
you can move a region around and run browser-based analysis as the region changes.

NB: The file://URI does not work in Google Chrome: Chrome doesn't permit a local HTML file to read other local files. The workaround is to start Chrome with the --allow-file-access-from-files switch:

    # Linux:
    chrome --allow-file-access-from-files
    # Mac:
    open /Applications/Google\ Chrome.app --args --allow-file-access-from-files
Firefox and Safari do not have this restriction.

If you just want to run JS9 in this simple way, you are done. However, you might want to edit the js9Prefs.json file to set up default values for colormaps, scaling, etc. See: JS9 Site Preferences for a description of the available parameters.

Do You Want to Install JS9 in a Web Server?

If you want to run JS9 in a "real" web server tree, build and install the JS9 tools and files using the standard GNU ./configure; make; make install technique. You should run configure with the --with-webdir=[path] switch, which specifies the directory into which the JS9 web files (JavaScript, CSS, etc.) will be installed. We recommend that this directory only contain the installed JS9 files, i.e. that you install JS9 into its own self-contained directory. This will make upgrading to new versions much easier.

Do You Want to Configure Server-side Analysis?

JS9 supports server-side ("back-end") analysis on FITS data using a server-side helper. This capability allows you to execute virtually any command-line analysis program from JS9. The analysis command is run on the back-end server and results viewed on your web page. You can utilize your own web server as the JS9 back-end helper using CGI calls, or you can run a separate Node.js-based server to process JS9 back-end requests. The server-side analysis capability is especially useful for archive centers, but also can be attractive to individual users who want to integrate their own data analysis programs into JS9.

In addition, JS9 supports communication with external processes via the js9 script. This capability requires the configuration of a Node.js-based server-side helper.

You configure a JS9 back-end helper by adding additional switches to the configure command. See: Installing a Server-side Helper for details.

Build the JS9 System

Once you have decided on the configuration of your JS9 system, run configure to generate various build files:
  ./configure [your JS9 switches]

and then build the JS9 system using the make command:

   make

Finalize Your Site Preferences

When JS9 is loaded into your browser, it reads a file called js9Prefs.json from the JS9 web directory. This file contains various default settings for JS9, e.g. default colormap and scale for image display. Feel free to edit this file to set up your own site-specific parameters. See JS9 Site Preferences for a description of the available parameters.

Install the JS9 System

When the build is completed, you can install the JS9 into your web tree:

    make install

and then clean up the build directory using the command:

    make clean

Optionally Install the JS9 Test Data Files

If you want to display our test data files in the JS9 demo pages, you must retrieve the JS9 data file tar file from the JS9 web site:

    http://js9.si.edu
and untar it into the JS9 web install directory. This will create sub-directories containing the image data. These data files also are available on GitHub:
    https://github.com/ericmandel/js9data
Last updated: June 1, 2016