Plot Symbols

The symbol keyword value describes how to plot and label objects in a user interface based on the values in a query result row. You can, for example, specify that you want yellow circles drawn around guide stars from the GSC catalog with a size based on the magnitude of the object in image pixels. You can also specify the shape and orientation of an ellipse to be drawn around each object, based on the values in each query result row and label each object with a variable string. The syntax for the symbol keyword value is as follows:

symbol : colNames symbolInfo sizeExpr : colNames symbolInfo sizeExpr : ...

where:

colNames

is a list of column names that may be used as variables in symbolInfo or sizeExpr . Only these column names will be available as variables. The names should be separated by spaces. Column names that contain embedded spaces or special chars ( Tcl syntax ) should be placed in " double-quotes " or { braces }.

symbolInfo

is the name of a symbol to plot, or optionally a list of the form:

symbol color ratio angle label condition

Only symbol is required, the other values are all optional.

symbol is the symbol to plot and may be one of: square , circle , triangle , cross , diamond , plus, ellipse, compass, line, arrow . Some of these symbols (the last 5 in the list above) are typically plotted in the orientation of the image, i.e.: they are rotated relative to the world coordinate north of the image, if it is known (see also angle below).
color is the color of the symbol and may be any valid X color name, such as red , yellow , blue , etc. The default is to draw the symbol in black and white, so that it will always be visible in any color image.
ratio and angle are only used for symbols where it makes sense, such as ellipse, line, arrow, compass and plus . The ratio gives the shape of the symbol as a ratio width / height and angle is the rotation angle of the symbol, relative to WCS north. Both values may be expressions using the column names given in colNames above.
label may also be an expression or text mixed with an expression and is used to label each object.
condition may be an expression (using the column names as variables) that evaluates to a boolean value (1 for true , or 0 for false ). If the condition evaluates to 1, the symbol is displayed for that object, otherwise it is not. Multiple symbols may be used, each with a different condition, so that different symbols, shapes and colors are used depending on the column values.

sizeExpr

is an expression in terms of the column names given by colNames above and is used to determine the size of the symbol. It may also be a list of { expr units} , where:

expr gives the size of the object (a valid Tcl expression using column names as variables).
units is either image ( for image pixels), " deg J2000 " or " deg B1950 " ( for World Coordinate degrees in the given equinox ).

examples:

symbol : mag circle 15-$mag
Plot circles with the size 15-$mag image pixels.
symbol : mag {circle yellow} {$mag/60 {deg J2000}} : rmag {square red} {$rmag*3.5}
Plot yellow circles with the size $mag/60 degrees (J2000) and red squares with the size $rmag*3.5 (image pixels).
symbol : {a/b pa mag} {ellipse yellow ${a/b} $pa mag=$mag} {15-$mag}
Plot yellow ellipses with the ratio ${a/b}, the angle $pa, and the size 15-$mag (image pixels) and label each object with the text "mag=$mag" (inserting the value for $mag).
symbol : "a/b pa mag" "ellipse yellow ${a/b} $pa mag=$mag" "15-$mag"
Same as above, but using "double-quotes" instead of {braces}.
symbol : "a/b pa mag" "ellipse yellow ${a/b} $pa mag=$mag $mag<12" "15-$mag" \
: "a/b pa mag" "cross blue ${a/b} $pa mag=$mag $mag>=12" "15-$mag"
Same as above, but plot yellow ellipses for symbols with mag less than 12 and blue crosses for the others..

Remember that whenever there are ambiguities (embedded spaces or special chars), the Tcl list and variable syntax is used. This makes it very easy for Tcl applications to evaluate the expressions.

If you are not able to calculate the correct size of an object in an expression, there might still be a way to do what you want (at least for your own catalogs). You can insert a call to a Tcl proc or command in the expression. For example:

symbol : "rmag bmag" circle "[my_plot_proc $rmag $bmag]"
Plot circles with a size in image pixels calculated by the Tcl proc my_plot_proc.

Note that the cat package does not actually plot any symbols or deal with images directly. See the skycat package for that. It defines subclasses of some catalog user interface classes and adds image plotting support.