JS9 Demo: catalogs

Move circle catalog:

JS9 catalogs come in two flavors:

  • Astronomical catalogs are tab-delimited tables containing RA and Dec columns
  • Primitive catalogs are arrays of shapes having x,y positions

Astronomical catalogs

Astronomical catalogs are a special type of JS9 shape layer, in which the shapes have been generated from a tab-delimited text file of columns, including two columns that contain RA and Dec values:

    # comments are allowed
    ra        	        dec        	magj	magh	magk
    ------------	------------	------	------	------
    23:22:56.003	58:44:45.429	15.612	15.103	14.9
    23:22:56.230	58:45:32.011	13.723	13.174	12.981
The Archives and Catalogs plugin will load astronomical catalogs from SAO and VizieR. You can also load local catalogs using the File: load catalog menu option or the JS9.LoadCatalog() public access routine. This routine takes a layer name as the first argument, and string or blob containing the tab-delimited text as its second argument. The final opts argument sets options:
        # retrieve a catalog as text, read a file into a blob, or ...
        var mycat = "RA	        Dec	        magj\n" + 
	"------------	--------	------\n" +
	"23:23:16.548	58:47:35.443	15.186\n" +
	"23:23:17.310	58:47:34.797	16.111\n";
        JS9.LoadCatalog("mycat", mycat, {color: "red", shape: "circle", radius: 5});
Please see the Public Access API for more detailed information about catalog format and catalog options, including use of global properties in JS9.globalOpts.catalogs.

When saving astronomical catalogs in the Shape Layers plugin, you have the choice of saving as regions or saving the original tab-delimited catalog.

Primitive catalogs

At a lower and more general level, primitive catalogs are arrays of JavaScript objects having the following elements (as well others that you wish to include): In addition, for each shape, the appropriate size and position parameters can be specified. These are the same as for regions: Catalogs are added to an image by first creating a new shape layer and then adding shapes:
    JS9.NewShapeLayer(catalog_name, opts);
    JS9.AddShapes(catalog_name, catalog_array, opts);
where catalog_name is an indentifying name for the catalog. The optional opts parameter in the first call allows you to specify default options for the new layer. You can set a default for any property needed by your shape layer. See JS9.Regions.opts in js9.js for example of the default options for the regions layer.

The JS9.Catalogs.opts object is also supplied as a possible default object for new shape layers. It differs from the JS9.Regions.opts object in that it does not define regions-specific processing (such as double-click to edit a region parameters). It also makes the new layer non-interactive: individual shapes cannot be moved, rotated, resized, or deleted. By default, they will respond to events.

Starting with the JS9.Catalogs.opts object as a default, you can make the new layer interactive in a few different ways. The first way is to set the movable property in the opts object to true. This will permit individual shapes to be moved, rotated, resized and deleted. Shapes will also be movable and resizeable as a group.

The second way is to supply one or more event callbacks as properties to the opts object:

When the associated mouse event occurs on a shape, these functions will be called with the following arguments: For example, to define mouseover and mousedown callbacks:
    opts.onmouseover = function(im, xreg, evt){
        console.log("mouseover: %s %s", im.id, xreg.data.tag);
    opts.onmousedown = function(im, xreg, evt){
        console.log("mousedown: %s %s", im.id, xreg.data.tag);
Note that the shapes are still not movable unless you also set the movable property.

In addition to firing callbacks on events for individual shapes, you can set the ongroupcreate property in the opts object to a function that will fire when two or more objects are selected into a group (which is done using the Command key on a Mac, or Control key everywhere else):

The function will be called with the following arguments: Note that an array of xreg objects is passed in this case instead of the single "current" object passed in the other event callbacks. For example:
    opts.ongroupcreate = function(im, xregs, evt){
        var i, nshape, xcen, ycen;
        var xtot=0, ytot=0;
        nshape = xregs.length;
        for(i=0; i<nshape; i++){
          xtot += xregs[i].x; ytot += xregs[i].y;
        xcen = xtot / nshape; ycen = ytot / nshape;
        console.log("average pos for %s objects: %s,%s", nshape, xcen, ycen);

The final way to make a shape layer interactive is to specify a tooltip to display when hovering over objects in this shape layer. This is done by assigning a tooltip format string to the tooltip property of the opts object. This string can contain HTML directives, and it also can contain references to properties in the im, xreg, and evt objects. When the mouse hovers over an object, a tooltip string is generated by macro-expanding the values for these properties. The generated tooltip string is displayed as the inner HTML of the tooltip. When the mouse leaves the object, the tooltip is hidden.

For example, consider the following tooltip string:

    opts.tooltip = "<b>id: $im.id</b><br>pos: $xreg.x $xreg.y<br><i>$xreg.data.tag</i>";
Note how properties of the im and xreg objects are specified with a "$" prefix. When the mouse hovers over an object, the generated tooltip will display current image id in bold, followed by that object's x,y pixel position, followed by a user "tag" property passed in the data object when the shape was added.

JS9 Demos: