JS9: astronomical image display everywhere

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

Introduction to JS9

JS9 is the latest in the SAOimage line of astronomical image display programs developed at the Center for Astrophysics | Harvard & Smithsonian (CfA.) Our previous effort, SAOimage DS9, has been the de facto standard desktop image display for more than 30 years. Now, with JS9, you can view and manipulate astronomical image data in your browser as well as on the desktop.

Please choose from the following topics:

Getting Started with JS9

JS9 provides astronomical image display capabilities both on the desktop and in your browser. JS9 takes its name as well as its core functionality from the de facto standard DS9 image display program for desktop use. JS9, on the other hand, can be run either on the desktop or in a browser. It also can be used without any installation at all by dragging/dropping a FITS file onto the JS9 website. In all three cases, the JS9 display consists of one or more HTML components that are added to a web page. At a minimum, the JS9 display will contain an image display canvas. It usually also will display a menubar containing several pull-down menus and a colorbar. Traditionally, the menubar is placed on top of the image canvas and the colorbar below, but web page designers (as well as individual users) have complete control over component 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 plugin 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.

Some menu options have keystroke accelerators and these are shown on the right-hand side of the menu option. Thus, for example, to open a local file, you can select the File:open...:local file menu option, or press the Meta-o key combination when the mouse is inside the JS9 display.

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 submenus 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.

Pressing the meta key disables the value/position display. It also disables execution of plugin callbacks on all mouse events. See Local Tasks for more information about plugins and browser-based analysis.

When a keyboard is available, pressing the meta key while clicking in the primary image window will pan the image so that the mouse location is in the center of the display (this panning is disabled inside a region.)

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.

Within an annulus, if you press meta and click the mouse, the annuli of the annulus region are replaced by an equivalent set of circles which can be resized (or deleted) individually, but not moved. Press meta and click the mouse again to finalize the region with the new annuli. Press shift-meta and click the mouse to cancel the edit and restore the original annuli.

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:resize:change width/height menu 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:resize:set to image size option will set the display size to the size of the current image. The View:resize: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:resize: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.js 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.js file.

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

Last updated: June 8, 2021