Configuring JS9 Site Preferences

JS9 supports a site configuration file that is read after the JavaScript variables are loaded but before JavaScript code is compiled and executed. This file allow you to tailor JS9 to meet the needs of your site without having to modify the js9.js file directly.

To support site configuration, JS9 tries to load a json file called js9Prefs.json from the same server on which the main js9-[version].js file resides. The file will be looked for first in the same directory as the web page and then in the js9 install directory.   (Firefox has deprecated synchronous XHR requests in the main window. As a result, we have been forced to deprecate automatic loading of the js9Prefs.json file. Please use js9prefs.js instead.)

To support site configuration, load the JS9 json preference file file (referred to here as js9prefs.json, but it can be named anything, of course) into your web page before loading other JS9 javascript:

  <script type="text/javascript" src="js9prefs-local.js"></script>
  <script type="text/javascript" src="js9support.min.js"></script>
  <script type="text/javascript" src="js9.min.js"></script>

NB: the JS9 Node.js helper still utilizes the js9Prefs.json file. Please ensure that the properties defined in these two files are consistent.

This preference file can be used to override the default parameter settings for JS9. A look through the beginning of JS9 code will show a number of Javascript objects containing these default parameters. They all have names ending in Opts, i.e. JS9.imageOpts, JS9.analysisOpts, etc. A description of some of these objects is given below:

  1. JS9.globalOpts: this JavaScript object contains global information, including parameters concerned with the back-end services used by JS9. Currently, it allows you to specify the helperPort on which to connect. Note that this same preference file is read the Node-based js9Helper, so changing the helper port in this file will change both the client and server.

  2. JS9.imageOpts: This JavaScript object contains initial values for image parameters such as: contrast, bias, whether to invert the colormap, colormap, scale, WCS system , WCS units, whether to display value/position, and whether to list regions when they change (listonchange).

  3. JS9.analOpts This JavaScript object contains the dataDir option, which specifies the pathname prefix to add to each FITS filename instead of the pathname stored in the PNG file. You can set this variable if you have moved the location of the raw FITS files after generating the PNG files.

  4. JS9.Regions.opts: This JavaScript object contains default values for regions, including the initial size of various regions, initial inner and outer radii for annuli, initial angle, etc. You can set or override properties for this object by adding them to the regionOpts object in the js9prefs.js file.

  5. JS9.menuButtonOptsArr: this JavaScript array of objects allows you to change and re-arrange which menu options are provided. If you prefix the name of a menu option with '#', that option is disabled.

  6. Module: a global JavaScript object with attributes that Emscripten-generated code calls at various points in its execution. You can set or override properties for this object by adding them to the emscriptenOpts object in the js9prefs.js file. One important case occurs when you have installed the astroemw.wasm binary file in a location other than the JS9 install directory. You would then use Emscripten's wasmBinaryFile property to specify a path to this file, relative to the JS9 install directory. For example, if the JS9 install directory and the resources directory are at the same level in the directory hierarchy:

    var JS9Prefs = {
      "emscriptenOpts": {
         "wasmBinaryFile": "../resources/js/astroemw.wasm"
      # other preferences ...
    See Emscripten's Module Object documentation for more information, and please let us know if you have problems.
In addition to the above-mentioned objects, the preference file can be used to set some internal variables. The JS9.DEBUG parameter is an example, as shown in the default preference file. Ordinarily, users need not be concerned with these variables.
Last updated: May 15, 2018