External Communication with JS9

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 image
These 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:

Note that the js9 script on one host cannot communicate with a target browser on another host (unless the first host is the helper host).

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.

Last updated: July 2, 2015