The JS9 Analysis menu provides flexible support for running a macro-expanded external analysis command on the web server and displaying results in the browser. But there are other scenarios in which it might be desirable for an external process to communicate with the JS9 client:
If you have installed the Node.js-based server-side helper (or Electron.js for the Desktop JS9 app), this sort of external communication is supported by the js9 script and its underlying js9Msg.js module. The script runs Node.js (or Electron.js) with js9Msg.js as its first argument. (See Installing a Server-side Helper for more more information about server-side helpers.)
To display the js9 script options, type:
sh> js9 --help
The js9 script supports two types of syntax:
The console syntax offers a restricted set of commands suitable for quick interactive use. Results are returned as simple strings:
sh> js9 cmap heat # change colormap to heat OK sh> js9 cmap # return the current colormap heatThe console commands include:
analysis list/run analysis for current image (run) colormap set/get colormap for current image (cmap) colormaps get list of available colormaps (cmaps) grid set/get coordinate grid for current image help get list of available commands helper get/set helper connection image get name of currently loaded image or display specified image images get list of currently loaded images load load image(s) pan set/get pan location for current image pix2wcs get image pixel value for specified wcs position print print image window refresh refresh current image using specified file (def: use last file) regcnts counts in regions for current image regions add region to current image or list all regions (reg, region) resize get/set display size for current image scale set/get scaling for current image scales get list of available scales section display section of current image status get status for specified (or current) image url display a url wcssys set/get wcs system for current image wcsu set/get wcs units used for current image wcssystems get list of available wcs systems wcsunits get list of available wcs units wcs2pix get wcs position for specified image pixel zoom set/get zoom for current image
The JS9 Public API syntax offers the full power of the public API. It passes and returns JSON-formatted strings with a richer set of options than is available via the console syntax:
# add a red circle region
sh> js9 AddRegions circle '{"color":"red", "tags": "foo"}'
# change color of all regions to violet and change the tags too
sh> js9 ChangeRegions all '{"color":"violet","tags":"goo"}'
# change color of selected regions to violet and change the tags too
sh> js9 ChangeRegions selected '{"color":"violet","tags":"goo"}'
# change color of red regions to violet
sh> js9 ChangeRegions red '{"color":"violet"}'
# change color of regions with "source" tag to violet
sh> js9 ChangeRegions source '{"color":"violet"}'
# get colormap
sh> js9 GetColormap
{"colormap":"grey","contrast":"3","bias":"0.8"}
# set colormap
sh> js9 SetColormap viridis 1 0.5
# get scale parameters
sh> js9 GetScale
{"scale":"log","scalemin":0,"scalemax":51}
# set scale in a different display
sh> js9 SetScale linear '{"display":"myJS9"}'
Passed arguments are the same as the public API arguments,
except that objects are passed as JSON strings. Returned objects
are also in JSON format. Note in the last example above that the
display object argument of the public API calls is supported.
See JS9 Public API for more information.
An example of the use of the public API is given in the shell script below, where we load the Chandra image of the Kes 75 supernova remnant, display three energy cuts as separate images, assign red, green, and blue colormaps to the three energy cuts, and then blend them into a single display:
#!/bin/bash
# Chandra event file of the Kes75 SNR
file="kes75/kes75_evt2.fits.gz"
# some Chandra energy filters
filter[1]="energy=500:1500"
filter[2]="energy=1500:2500"
filter[3]="energy=2500:8000"
# RGB colormaps
cmap[1]="red"
cmap[2]="green"
cmap[3]="blue"
# load event file
echo "loading event file: $file"
js9load $file
# turn blending off (since default is on)
js9 BlendImage false
# process each of the event filters
for i in {1..3}; do
echo "filter: ${filter[$i]}"
# generate section using event filter into a separately displayed image
js9 DisplaySection '{"filter":"'${filter[$i]}'","separate":true}'
# this actually takes a bit of time
sleep 4
j=`expr $i + 1`
# the new file with have a <n> string appended to the original id
id="kes75_evt2.fits.gz[EVENTS]<$j>"
# set image scale and assign one of the RGB colormaps
js9 SetScale "log" '{"display":"'$id'"}'
js9 SetColormap "${cmap[$i]}" '{"display":"'$id'"}'
done
# blend all the images
js9 BlendDisplay true
echo "all done!"
Note the use of the js9load script to load an image. This
auxiliary script uses the Load and GetLoadStatus API
calls to load an image and wait for completion before returning.
The default wait time is 10 seconds, but is configurable on
the command line.
If the "-" or "--pipe" argument is supplied, js9 will read commands from stdin. You can send multiple commands to the script's standard input (comments and blank lines are ignored):
sh> cat test.cmds
# colormap
cmap heat
# scale
scale log
# regions using image coords
region circle {"x":588, "y":590, "radius":30, "tags":"source"}
region circle {"x":390, "y":430, "radius":50, "tags":"background"}
sh> cat test.cmds | js9 -
DS9/Funtools region syntax can also be used for regions:
sh> cat test2.cmds
cmap heat
scale log
wcssys fk5
region box(23:23:35.236,+58:50:00.95,39.352",20.1679",24.0163)
region ellipse(23:23:33.323,+58:47:41.50,29.6394",11.0139",25.7599)
region polygon(23:23:19.379,+58:49:30.02,23:23:17.270,+58:49:40.93,23:23:14.834,+58:49:38.59,23:23:17.974,+58:49:13.64) {"tags": "background"}
sh> cat test2.cmds | js9 -
Finally, the - (or --pipe) switch also allows you to specify a string on the JS9 command line that will prefix all lines read from stdin. This allows you to send a regions file to JS9:
sh> cat ds9.reg # Region file format: DS9 version 4.1 global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1 fk5 box(23:23:35.236,+58:50:00.95,39.352",20.1679",24.0163) ellipse(23:23:33.323,+58:47:41.50,29.6394",11.0139",25.7599) polygon(23:23:19.379,+58:49:30.02,23:23:17.270,+58:49:40.93,23:23:14.834,+58:49:38.59,23:23:17.974,+58:49:13.64) # background sh> cat ds9.reg | js9 - regionWithout the - ("dash") argument, standard input will not be read and the "region" command will be executed to return current regions.
The js9 script can talk to a JS9 instance if the script is run from:
If a JS9 instance is connected to a helper on a remote host, you can use the --host or --helper switch to specify the remote host to contact. For example, if the helper is running on js9.cfa.harvard.edu, you can send a command to your instance of JS9 this way:
sh> js9 --host https://js9.si.edu region circle OK
If more than one instance of JS9 appears on a single web page, the --id switch can differentiate between instances. The value of the id switch is the div id for that JS9 instance. For example, if two instances of JS9 having div ids of "JS9" and "myJS9" are defined on the same page, then js9 can communicate with the latter in this way:
sh> js9 --id myJS9 region circle OK sh> js9 --id myJS9 region ICRS; circle(23:23:26.929, +58:48:50.381, 14.76")or, from the readline loop:
sh> js9 --id myJS9 JS9> region circle(23:23:26.929, +58:48:50.381, 14.76") OK JS9> region ICRS; circle(23:23:26.929, +58:48:50.381, 14.76")
Putting the last two techniques together, you can talk to one of many JS9 instances on a page connected to a remote helper this way:
sh> js9 --host https://js9.si.edu --id myJS9 cmap heat OK
Ordinarily, the js9 script talks to a displayed JS9 web page. It also can be used to start the JS9 Desktop app and load an image into the app's web page. The JS9 Desktop app simply requires that you install Electron.js, which is available here:
http://electron.atom.io/Once this is done, use the -a switch to specify the app startup and the -w or --webpage switch to specify a web page (default is a nice, basic JS9 web page).
sh> js9 -a ~/data/casa.fitswill start the JS9 Desktop app with a basic JS9 web page and load the Cas-A FITS files into the page, while:
sh> js9 -a --webpage ~/js9/js9basics.html ~/data/casa.fitswill display the same image in one of the JS9 demo pages. For more details, see: Desktop JS9.
The js9 script also can be used to start up a new browser, display a JS9 web page, and then load an image into that page. To do this, use the -b or --browser switch to specify the browser (chrome, safari, or firefox) and the -w or --webpage switch to specify a web page (default is a basic JS9 web page). For example:
sh> js9 -b chrome ~/data/casa.fitswill start a Chrome browser with a basic JS9 web page and load the Cas-A FITS files into the page, while:
sh> js9 -b firefox -w ~/js9/js9basics.html ~/data/casa.fitswill use Firefox to display the same image in one of the JS9 demo pages.
Instead of supplying the browser name each time on the command line, you can set the environment variable JS9_BROWSER and just use the -b switch with no argument. (Note that you still must supply the -b switch, which tells the script to start a browser.) Similarly, the default web page can be configured using the JS9_WEBPAGE environment variable:
sh> export JS9_BROWSER=chrome sh> export JS9_WEBPAGE=$HOME/js9/js9basics.html sh> js9 -b ~/data/casa.fits
Care must be taken that no JS9 web page is already being displayed when the -b or --browser switch is utilized, or else the specified image will be loaded into the existing web page (and no new browser will be started). Also, it is important to note that the Google Chrome browser must be started by the js9 script or it must be started by you using the --allow-file-access-from-files switch. Without this switch, Chrome will not permit a local HTML file to read other files. Finally, Mac OSX Safari occasionally experiences delayed data transfers when the js9 messaging script is located in a different Space (desktop) from the browser window, so keep these in the same Space.
If you do not have access to the js9 script, you can still send messages to a JS9 web page using wget or curl. This is possible because the JS9 helper also listens for HTTP connections. The syntax for HTTP-based commands is analogous to the scripting syntax, if somewhat more primitive: you pass a JSON-formatted string to the helper in a GET or POST request, as show below. (Note that accessing a secure web page using wget requires the --no-check-certificate flag, a problem not restricted to JS9):
export MYHOST="https://js9.si.edu:2718"
export ID="JS9"
export WARGS="-q -O- --no-check-certificate"
# GET request, using public api:
wget $WARGS $MYHOST'/msg?{"id": "'$ID'", "cmd": "GetColormap"}'
wget $WARGS $MYHOST'/msg?{"id": "'$ID'", "cmd": "SetColormap", "args": ["red"]}'
wget $WARGS $MYHOST'/msg?{"id": "'$ID'", "cmd": "RunAnalysis", "args": ["counts"]}'
# GET request, using command line api:
wget $WARGS $MYHOST'/msg?{"id": "'$ID'", "cmd": "zoom"}'
wget $WARGS $MYHOST'/msg?{"id": "'$ID'", "cmd": "zoom", "args": [2]}'
wget $WARGS $MYHOST'/msg?{"id": "'$ID'", "cmd": "analysis", "args": ["counts"]}'
# POST request, using public api:
wget $WARGS --post-data='{"id": "'$ID'", "cmd": "GetColormap"}' $MYHOST/msg
wget $WARGS --post-data='{"id": "'$ID'", "cmd": "SetColormap", "args": ["red"]}' $MYHOST/msg
wget $WARGS --post-data='{"id": "'$ID'", "cmd": "RunAnalysis", "args": ["counts"]}' $MYHOST/msg