JS9: image display right in your browser

Eric Mandel, Alexey Vikhlinin
Harvard-Smithsonian Center for Astrophysics
Cambridge, MA 02138

Introduction to JS9

JS9 is a JavaScript version of the de facto standard DS9 image display program. It allows you to view and manipulate astronomical image data in your browser.

Please choose from the following topics:

Getting Started with JS9

JS9 provides astronomical image display capabilities right in your browser. JS9 takes both its name and its core functionality from the de facto standard DS9 image display program for desktop use, which is available at:

The JS9 display consists of one or more components that can be added to a web page by the web page designer. At a minimum, the JS9 display will contain an image display canvas. It usually also will display a menu strip containing several pull-down menus. Traditionally, this menu strip is placed on top of the image canvas, but web designers have complete control over its placement. JS9 also can display an info box, a command-line window, a pan window, a zoom window, as well as other plugins. All of these windows can be brought up dynamically from the View menu.

Astronomical image data usually is offered on a JS9 web page as one or more clickable URLs. When you click on a data URL, it is displayed on the JS9 image canvas. Multiple images can be loaded into a single JS9 display. The File menu allows you to switch between these images.

Once an image is loaded, you can move the mouse (or a single finger on a touch screen) to display position and pixel value information. Pressing the left mouse button and moving the mouse (or using two fingers on a touch screen) will change the contrast/bias of the displayed image, bringing image features into relief.

These mouse/touch actions are configurable, both by web page developers and by users. See the Mouse Touch plugin for more information.

Menu options allow you to change the scaling algorithm and/or color map, add geometric regions of interest, change world coordinate system (WCS) parameters, and run site-specific astronomical analysis tasks on the original FITS data.

JS9 Menus

The following menus are in the default JS9 menu bar. Of course, web designers have control over which menus are displayed (or even whether the menu bar itself is displayed). Thus, not all of the menus listed below will be found on all JS9-enabled web pages.

Note that the default menubar has a style in which all of the major menus are shown at the top-level of the menubar. This is the classic style. JS9 also supports a mac style menubar, in which the File, Edit and View menus are placed on the left side of the menubar and the Help menu on the right. The other main menus are displayed as sub-menus within the View menu.

The default top-level JS9 menus are:

JS9 Mouse Interaction

In keeping with the needs of mobile devices, JS9 utilizes a single mouse button for user interaction. Keyboard input also is minimized. Moving the mouse (or a single finger on a tablet) over the image will display the position/value of individual pixels. Pressing and moving the mouse (or two fingers) will change the contrast and bias of the image. A double-click (or double-tap) inside a region will bring up the configuration menu for that region.

JS9 Regions

Regions are geometric shapes that can be used to mark part of an image for analysis. JS9 allows you to create the following region types: annulus, box, circle, ellipse, line, point, polygon. A text region also can be created to annotate an image. When one of these options is selected, the region is created in the center of the image. It then can be dragged to the desired location. Arrow keys also will move the region one screen pixel in the specified direction. A selected region can be deleted by pressing the Delete key (where available. On a tablet, use the delete option in the configuration menu).

Click inside a region to select it and display the resize/rotate controls around its perimeter. Grabbing a handle allows the size of the region to be adjusted or rotated. In the case of the box and ellipse regions, the width and height are controlled separately. Click outside the region to de-select (or click another region to select that one).

For a line region, the end-points serve as both resize controls (arrow icon) and stretch points (hand icon). You might have to move the mouse around a bit to switch from one to another. The control action is to resize the region in both directions (i.e., the same as other regions). The stretch action allows you to move this end-point while the other one remains fixed.

A double-click inside a region brings up a configuration menu. You can change various values associated with a region by entering new values in the appropriate text boxes and the clicking Apply.

The configuration menu has the following standard options:

In addition, regions of different type support specific configuration parameters in this menu.
The annulus region supports:

The box region supports: The circle region supports: The ellipse region supports: The polygon and line regions support: The text region supports: A discussion of how JS9 implements DS9/Funtools regions syntax can be found here.

Meta Key Accelerator

The meta key is the Command key on a Mac and the Control key everywhere else.

When a keyboard is available, pressing the meta key while clicking in the primary image window will pan the image so that the clicked location is in the center of the display.

The meta key also disables execution of plugin callbacks on all mouse events. See Local Tasks for more information about plugins and browser-based analysis.

Within a polygon or a line, if you press meta and click the mouse on the polygon or line border, a new point will be added at that point. If you press the meta key and click on an existing point, it will be deleted.

Drag and Drop Images

You can drag and drop FITS images and binary tables, PNG images, and JPEG images onto JS9 to display the image data. All browser-based functions (scaling, colormap, pan, zoom, regions, WCS) should work as expected. You can execute server-side analysis tasks on the FITS files if the back-end server is running on your local host machine. In this case, you probably will need to set your DataPath variable in the Analysis menu to help JS9 locate the original data file.

Resizing the JS9 Display

The JS9 Display can be resized using the the View:change width/heightmenu option (or the JS9.ResizeDisplay() JavaScript routine). The View menu's resize parameter can be two values (width and height) or a single value representing both. In addition, if an image containing wcs info is being displayed, you can append a single quote to specify a size in arc minutes (e.g. 5') or a double quote to specify a size in arc seconds (e.g. 300").

The View: set to image size option will set the display size to the size of the current image. The View: set size to full window option will resize the JS9 display to the size of the browser window's window.innerWidth and window.innerHeight properties, and will scroll the display to the center of the window. (Note that the rest of the web page is still available via scrolling, including the menubar.) The View: reset to original size option will set the display size back to the original size. Display resize can be turned off by setting the JS9.globalOpts.resize variable to false in the js9Prefs.json file.

Also by default, the JS9 Display can be resized using a grab handle in the lower right-hand corner of the display. This feature can be turned off setting the JS9.globalOpts.resizeHandle variable to false in the js9Prefs.json file.

See Known Issues for a discussion of limitations imposed on resize by Webkit browsers such as Chrome and Safari.

Last updated: February 7, 2019