# location to install the JS9 web files: ./configure --with-webdir=[path_to_web_install]
# where to find cfitsio and install binaries, what sort of helper to build: ./configure --with-cfitsio=[path_to_cfitsio] --prefix=[path_to_prog_install] --with-helper=nodejs
The current release of the JS9 source tar file is available at:
https://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
The most up to date version of JS9 is available on GitHub:
git clone https://github.com/ericmandel/js9
The GitHub version will contain the latest bug fixes and improvements.
Once you have cloned JS9, you can retrieve the latest update:
git pull
Note that the main JS9 web site runs the latest software from GitHub.
# web pages are loaded relative to the directory in which the server is run # use any port number of your choice, above 1024 python3 -u -m http.server 8000You then can load web pages using localhost:8000 as the domain, e.g.:
# basic js9 web page http://localhost:8000/js9.html # demo web page with imexam plugins http://localhost:8000/demos/js9imexam.htmlYou can drag any FITS image file onto the JS9 display and view it, change contrast/bias, colormaps, scale, create regions, etc.
You also should be able to load any of the JS9 web pages into your browser using the file:// URI and no web server. For example, if you unpacked the tar file into /Users/me on a Mac, then you should be able to point your browser to:
file:///Users/me/js9-[version]/js9.html
to see the basic JS9 page without starting a web server.
Unfortunately, browser developers are making use of the file://URI increasingly difficult. By default, it does not work in Google Chrome, since default Chrome doesn't permit a local HTML file to read other local files. Instead, you must 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 now also restricts use of the file:// URI, as documented here. For Firefox, the work-around is turn off the privacy.file_unique_origin preference in about:config.
If you want to use the file:// URL, please glance at Known Issues to check the latest reports about using the file:// URI. It seems that browser developers are slowly adding more and more restrictions ...
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.
Running JS9 on the desktop simply requires that you install Electron.js, an app building platform that combines Node.js and the Chrome libraries. To install Electron, go to the Electron GitHub release page, choose the latest available stable release, and download the zip file for your platform. On a Mac, Electron.app should be installed in the /Applications or ~/Applications directory. On Linux, the electron program should be placed in your PATH. Note that Electron requires a relatively recent version of Linux: Ubuntu 12.04, Fedora 21, Debian 8, CentOS 7 (not CentOS 6).
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:
# the -a switch tells the script to bring up the desktop js9 app js9 -a ~/data/casa.fits &and then use the same script to interact with the JS9 page (or any other JS9-enabled web page):
# without -a, the script sends commands to the JS9 display js9 cmap cool js9 regions circle
For more details, see: Desktop JS9.
./configure --with-webdir=[path] ... other switches ... make make installAt 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.
Furthermore, we recommend that you not split up the JS9 files or install them outside the JS9 install directory. Not only is this difficult to update, but it actually will break JS9: at runtime, it is assumed that js9.css is located in the JS9 install directory, and its actual location is used to determine the JS9 install location relative to the main web page. If you must move the js9.css file, you will also need to add the installDir property to the globalOpts object within js9prefs.js, specifying the relative path from the web page to the JS9 install directory. Failure to do this correctly will cause a host of problems, starting with JS9 not loading astroem.js and js9worker.js. Please contact us if you have problems (the first indication of which probably will be JavaScript error messages when failing to load astroem.js and js9worker.js.)
As described in Creating a JS9 Web Page, a few JavaScript and CSS files must be loaded into a JS9-enabled web page. Ordinarily this is done in the page's header, which typically will look something like this:
<head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge;chrome=1" > <meta name="viewport" content="width=device-width, initial-scale=1" > <link type="image/x-icon" rel="shortcut icon" href="./favicon.ico"> <link type="text/css" rel="stylesheet" href="js9support.css"> <link type="text/css" rel="stylesheet" href="js9.css"> <script type="text/javascript" src="js9prefs.js"></script> <script type="text/javascript" src="js9support.min.js"></script> <script type="text/javascript" src="js9.min.js"></script> <script type="text/javascript" src="js9plugins.js"></script> </head>Also during startup, JS9 will asynchronously load the js9worker.js file in order to create a worker process and will load either the astroem.js file or the astroemw.js and astroemw.wasm files, depending on whether WebAssembly is supported on your browser.
Although none of these files are large, it always is worthwhile making downloaded files smaller to shorten the web page load time. One straight-forward way to do this, if you have control of the Apache web server, is to use the Apache rewrite capability to serve gzip'ed files in place of requested (uncompressed) files, if the former exist. Using this technique, your header can remain as shown above, but the Apache server will send gzip'ed versions when available. To do this, you can add code such as the following to the Apache httpd.conf:
<IfModule mod_headers.c>
# turn on rewrite
RewriteEngine on
# Serve gzip compressed CSS files if they exist
# and the client accepts gzip.
RewriteCond "%{HTTP:Accept-encoding}" "gzip"
RewriteCond "%{REQUEST_FILENAME}\.gz" -s
RewriteRule "^(.*)\.css" "$1\.css\.gz" [QSA]
# Serve gzip compressed JS files if they exist
# and the client accepts gzip.
RewriteCond "%{HTTP:Accept-encoding}" "gzip"
RewriteCond "%{REQUEST_FILENAME}\.gz" -s
RewriteRule "^(.*)\.js" "$1\.js\.gz" [QSA]
# Serve gzip compressed wasm files if they exist
# and the client accepts gzip.
RewriteCond "%{HTTP:Accept-encoding}" "gzip"
RewriteCond "%{REQUEST_FILENAME}\.gz" -s
RewriteRule "^(.*)\.wasm" "$1\.wasm\.gz" [QSA]
# Serve correct content types, and prevent mod_deflate double gzip.
RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1]
RewriteRule "\.wasm\.gz$" "-" [T=application/octet-stream,E=no-gzip:1]
<FilesMatch "(\.js\.gz|\.css\.gz|\.wasm\.gz)$">
# Serve correct encoding type.
Header append Content-Encoding gzip
# Force proxies to cache gzipped &
# non-gzipped css/js files separately.
Header append Vary Accept-Encoding
</FilesMatch>
</IfModule>
Note that the JS9 Makefile contains a rule called install-gzip which will install gzip'ed copies of several JS9 files along side the uncompressed versions:
./configure ... make make install make install-gzip
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 installSee: Installing a Server-side Helper for details.
./configure [your JS9 switches]
and then build the JS9 system using the make command:
makeMinor note: the cloned js9 script will be modified by the build to include knowledge of the source and install directories. This change allows you to run using the installed code instead of the source code. But since this modification will prevent subsequent "git pull" calls from completing, it will be reset by install or clean.
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.
When the build is completed, you can install the JS9 into your web tree:
make install
The first time you install JS9, your preference files will also be installed. After that, the install command will not install these files in order to avoid overwriting custom files. You can explicitly re-install preference files using:
make install-prefs
or simply copy them into the install directory.
In addition, the install procedure will rename an existing node_modules directory to onode_modules before installing the node_modules directory. This action prevents the accumulation of unneeded and possibly conflicting modules after multiple installs. If you need one or more modules from the original modules directory, please copy them from onode_modules or re-install them.
Clean up the build directory using the command:
make clean
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:
https://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