# 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
    ...
    

        # 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});
    

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):

• x: image x coordinate
• y: image y coordinate
• shape: "circle", "box", "ellipse", "polyon"
• color: color name or hex number

In addition, for each shape, the appropriate size and position parameters can be specified. These are the same as for regions:

• circle: radius
• box: width, height
• ellipse: eradius.x, eradius.y
• polygon: points

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:

• onmousedown: function(im, xreg, evt);
• onmouseup: function(im, xreg, evt);
• onmousemove: function(im, xreg, evt);
• onmouseover: function(im, xreg, evt);
• onmouseout: function(im, xreg, evt);

When the associated mouse event occurs on a shape, these functions will be called with the following arguments:

• im: the image handle for the currently displayed image
• xreg: the shape object, as described in JS9.GetShapes()
• evt: the original event object

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):

• ongroupcreate: function(im, xregs, evt);

The function will be called with the following arguments:

• im: the image handle for the currently displayed image
• xregs: an array of shape objects within the group
• evt: the original event object

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.