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:
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:
http://ds9.si.eduThe 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.
The following menus are in the default JS9 menu bar. Note that 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 web pages:
File: The File menu displays a list of all images currently loaded into this instance of JS9. The displayed image is marked with a star burst. To display a different image, simply choose it in the menu. The menu contains an open ... options which displays a file browser for loading FITS files (compressed or uncompressed). It also contains options to:
View: displays a list of plugin menu options, including the following core options:
In addition to these core options, the View menu also lists the currently-loaded View plugins. JS9 itself supplies the following plugins:
Web developers can develop and register other plugins (which generally are loaded into either the View or Analysis menus).
The display value/position option specifies whether image position and image pixel value is displayed as the mouse (or finger) moves over the image. By default, this information is displayed in the upper left of the image. You can redirect the display to a movable, light-weight window by choosing the InfoBox menu option.
The new image inherits current params option specifies whether a new image grabs the image params (e.g., colormap, scale, zoom, etc.) from the currently displayed image. If false, these params are taken from the default JS9.imageOpts object.
Finally, the change width/height menu option allows you to specify a new width and height for the JS9 display.
Zoom: The zoomIn and zoomOut menu options zoom the primary image in or out by a factor of two. The zoomToFit options calculates a zoom factor that fits the entire image into the JS9 display. You also can set the zoom factor to a pre-specified value using menu options. You can specify any floating point zoom factor in the numeric zoom value text box. The pan to center option pans to the center of the image, while the reset zoom/pan sets the zoom to 1 and centers the display.
Scale:Each scale option specifies a different scaling algorithm to use when converting image pixel values to RGB values. (The procedure for doing this conversion is detailed in the DS9 documentation titled "How It Works".) The log scale, for example, is especially useful with X-ray data. Histogram equalization (histeq) tries to maximize contrast across the range of data values and is useful in a wide variety of cases. The current scale is marked with a star burst.
You also can change the low and high values used to clip the image data before scaling by changing the low value for clipping and/or high value for clipping numbers. These values are set initially with the data's min and max values or the z1,z2 values calculated by the IRAF zscale algorithm (depending on the value of the web site's JS9.imageOpts.scaleclipping parameter. The default usually is "dataminmax".). Finally, you can set (or reset) the low and high values to data min,max or zscale z1,z2 using the set vals to data min/max or set vals to zscale z1/z2 options, respectively. (Note that zscale requires a considerable amount of memory and does not work on very large images. We will try to remove this restriction in the future.)
Colormap: Each colormap option specifies a different distribution of RGB values to use when converting image pixel values to RGB. (The procedure for doing this conversion is detailed in the DS9 documentation titled "How It Works".) Choose the colormap you like best, or try different ones to see how data features can be brought to the fore by color and contrast/bias.
The image filters menu option provides a number of well-known image processing functions that act directly on the displayed RGB image data (not the underlying raw astronomical data, as with the Gaussian blur in the Analysis menu). Thus, when you can run one of these routines on an image, its effect will be undone if you redraw the image by changing the contrast/bias, colormap, etc. Also, since these functions act on the current RGB image, their effect is cumulative. See the JS9.FilterRGBImage() section in the JS9 Public API for more information about the individual functions.
You can enter a floating point value into the contrast value and bias value text boxes to set the contrast/bias. Note that the contrast value ranges from 0 to 10 and the bias ranges from 0 to 1 (following DS9 conventions).
The reset contrast/bias option restores the original contrast/bias value (which is especially useful if you changed the contrast/bias or scale and now can't see any features at all!)
The load colormap option brings up a File menu from which you can choose a user-defined colormap to load.
The save colormap option saves the active colormap definition for the currently displayed image to a file (useful for editing to make a new colormap).
The invert colormap option inverts the colormap (e.g. in the gray map, this will change white to black and vice versa).
If you have three images of the same size, scale, and pointing direction (e.g. three energy cuts of a Chandra data set), you can display each one separately and assign to them one of the red, green, or blue colormaps. If you then select the RGB mode menu option, they will be displayed as one RGB composite image. The current image (as shown in the File menu) determines which of the three independent colormaps is changed by the contrast/bias manipulation. To remove an image from the RGB composite, give it a different colormap. Re-join (or add a new image) by assigning one of the RGB colormaps. Simply turn off RGB mode to display the images separately.
Region: Choose the appropriate menu option to create a region of type annulus, box, circle, ellipse, line, point, polygon, text. (see below for details on how to use regions). One or more regions can be created and manipulated on a single image.
The load legions menu option will load a file of regions and display them on the current image. Regions can be specified using the a dialect of the widely-used DS9/Funtools regions format, as described here.
The save regions menu option will save all regions to a file named js9.reg. The file will be saved in the folder where your other browser downloads are stored. NB: As of 4/2015, Safari does not permit this sort of file saving. The save regions command therefore displays the region text in a new tab (or window). Use Safari's File:Save As option to save the regions to disk.
The copy regions to menu option will copy regions from the current image to a specified image (or to all images). If one or more regions are actively selected in the current image, they alone will be copied. Otherwise, all regions will be copied.
The list regions menu option will display all regions. The remove regions menu option will delete all regions. The list selected menu option will display the selected region(s). The remove selected menu option will delete the selected regions(s).
The list on change menu option will cause all regions to be listed whenever one changes.
WCS: Use this menu option to select a world coordinate system when displaying pixel positions and regions (assuming the data file supports WCS). Available systems are: FK4, FK5, ICRS, galactic, or ecliptic. The native option chooses the system stored in the data file. The image and physical systems will display only image coordinates (not WCS coordinates). Physical coordinates are tied to the original (block 1) file coordinates while image coordinates are tied to the current image data being displayed. Server-side X-ray analysis routines operating on the original file generally want physical coords rather than image coords. Browser-based plugin routines generally use image coordinates to operate on the in-memory image data.
You also can choose the units in which WCS information is displayed: degrees, radians, or sexagesimal. Image and physical coordinates are displayed in units of pixels.
The alternate wcs menu option allows you to choose an alternate world coordinate system, if one or more are defined in the current FITS file. The submenu lists the WCS version (i.e. the letter "A" - "Z", or "default") and, if present, the WCSNAME header parameter associated with this WCS.
Finally the reproject menu option allows you to reproject the image using the WCS associated with another displayed image. The reprojected data is placed in a new raw data layer called "reproject". You can switch between layers using the View->raw data layers option.
Analysis: Each JS9 site can define server-side analysis tasks to be run from the Analysis menu. Tasks are of two types:
For example, the sample implementation of JS9 at
If you drag and drop a FITS file onto a JS9 web page connected to a
remove server (such as
In addition to server-side analysis, the Analysis menu lists the currently loaded Analysis Plugins. JS9 itself supplies the Imexam plugin, which offers the following tasks:
You also can perform a fast Gaussian blur by entering a sigma (radius) value into the Gaussian blur sigma option. A new raw data layer called "gaussBlur" is created, in which the image pixel values are blurred using a Gaussian function with the specified sigma. The routine uses the fast Gaussian blur algorithm (approximating a full Gaussian blur with three passes of a box blur) described here.
Finally the set data path ... option allows you to specify a colon-separated list of directories for JS9 to search when looking for FITS data files that have been dropped onto the display. This is used by JS9 when performing server-side data analysis on local drag-and-drop FITS files. It is necessary to specify data paths explicitly since web pages are not allowed to determine the pathname of such files automatically (for obvious security reasons).
Help: Show this and other JS9 help pages. The Help menu also contains help for Plugins, including the Imexam plugins listed above.
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.
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).
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 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.
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.
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.