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 run the Node.js-based helper (instead of the CGI helper), this sort of external communication is supported by the js9 script and its underlying js9Msg.js module. The script runs Node.js with js9Msg.js as its first argument. Using command line syntax, it will send a single JS9 command to the browser and return the results:
sh> js9 cmap heat # change colormap to heat OK sh> js9 cmap # return the current colormap heat
Alternatively, if no command-line arguments are specified, js9 will enter a "read-line" loop, executing commands as they are input:
sh> js9 JS9> cmap heat OK JS9> cmap heat
When no arguments are supplied, js9 will read 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
Note that 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 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 - region(Without the - ("dash") switch, standard input will not be read. The "region" command will be executed to return current regions.)
A list of available JS9 commands can be retrieved using the ''help' command:
sh> js9 help analysis run/list analysis for current image (ana) colormap set/get colormap for current image (cmap) colormaps get list of available colormaps (cmaps) 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 regions add region to current image or list all regions (reg, region) scale set/get scaling for current image scales get list of available scales 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 imageThese are the same commands that are available to the JS9 light-weight Console window.
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 js9.cfa.harvard.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 js9.cfa.harvard.edu -id myJS9 cmap heat OK
A final esoteric security note: special considerations are required when a helper host wants to talk to one of several instances of JS9 connected to the helper. Being on the same host as the helper, the js9 script is allowed to send messages to any of these clients. But for security reasons, it can only send a message to an individual browser, not to all browsers at once. If the target browser's ip address is known, the -browser switch can be used to differentiate browsers running the same page. For example, if you want to talk to the JS9 client browser on bynars:
sh> js9 -browser bynars.cfa.harvard.edu -id myJS9 region circle OK sh> js9 -browser bynars.cfa.harvard.edu -id JS9 region ICRS; circle(23:23:26.929, +58:48:50.381, 14.76")or, from the readline loop:
sh> js9 -browser bynars.cfa.harvard.edu -id myJS9 JS9> region circle OK JS9> region ICRS; circle(23:23:26.929, +58:48:50.381, 14.76")
The JS9 interface will evolve to meet the needs of the astronomical community.