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:
    git clone 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.js 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 Run JS9 as a Desktop Program from the Command Line?

JS9 can be used as a Desktop app: you can load images into the app's (Chrome) web page instead of using a browser. The JS9 Desktop app simply requires that you install Electron.js, which is described here:
  http://electron.atom.io
To install Electron, go to the release page: http://electron.atom.io/releases, choose the latest available release, and download the zip file for your platform. On a Mac, Electron.app should be installed in the /Applications folder; you will have to run it manually (from the Finder) the first time. On Linux, the electron program should be placed in your PATH. (Note that Electron requires a recent version of Linux: Ubuntu 12.04, Fedora 21, Debian 8. Thus, for example, it runs on CentOS 7 but not CentOS 6).

NB: It is important to note that Electron.js is not a web browser: the web pages you load are not sandboxed. Our JS9 Desktop application code takes additional precautions to enhance security by disabling node.js integration and Javascript eval in web pages. However, these precautions are likely to be insufficient to guard against malicious web pages. Therefore, it is critically important that you load only local or trusted remote web pages into the JS9 Desktop app. See: Electron.js security for more information.

Once the Electron app is installed, generate the JS9 quick-start files:

  ./mkjs9 -q
  Editing js9Prefs.json for Node.js helper ...
  Editing js9prefs.js for Node.js helper ...
  Generating js9 script for JS9 messaging and Desktop use ...

  If you plan to use Electron.app with JS9, consider codesign'ing it:

  sudo codesign --force --deep --sign - /Applications/Electron.app/Contents/MacOS/Electron/

  This will avoid repeated requests to allow incoming connections.
The mkjs9 script will create a js9prefs.js file (for the browser) and a js9Prefs.json file (for the JS9 helper), which you can edit to add preferred JS9 properties, as well as a js9 script to start the JS9 app. On a Mac, you probably will want to codesign the Electron.app application to avoid repeated requests about incoming connections (see example above).

Run the js9 script to start the app and load data files:

  js9 ~/data/casa.fits &
and then use the same script to interact with the JS9 page (or any other JS9-enabled web page):
  js9 cmap cool
  js9 regions circle
See: External Messaging for more details.

Do You Want to Install JS9 in a Web Server?

If you want to run JS9 in a "real" web server, build and install the JS9 tools and files using the standard GNU procedure:
  ./configure --switches...
  make
  make install
At a minimum, 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 or External Messaging?

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 command-line messaging between the shell and JS9, pyjs9 Python messaging between the Python and JS9, and also has large-file support via the use of representation files. These capabilities requires the configuration of a Node.js-based server-side helper.

You configure a JS9 helper by adding additional switches to the configure command, e.g.:

  # where to find cfitsio and install binaries, what sort of helper to build:
  ./configure  --with-cfitsio=[path_to_cfitsio] --prefix=$HOME --with-helper=nod
  make
  make install
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

The js9prefs.js file and js9Prefs.json file contain 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: July 10, 2017