POW works in terms of objects (although at the moment, it's not written
using object-oriented TCL). Each of these objects has a name (just an
ASCII string). Once an object is "constructed", you use the name
to refer to it in the various things you want to do to it ("methods").
The main objects are:
PowData - this object is an array (in the C sense) in memory somewhere
along with info on data type and the length of the array.
At creation, you can specify that POW should make it's own copy
of the data, allowing you to "free" your copy, or you can save
space by allowing POW to use your copy of the data, just don't
free or change it unless you destroy the PowData object first.
PowVector, PowImage - these are your choices for what you can create using
your PowData, they give "physical" meaning to the data by specifying
units and, for images, dimensions. You can make any number of
Images and Vectors from one chunk of Data, and you can specify
offsets so as to use only part of the Data.
PowCurve - This is a collection of 1 to 6 vectors which represent a curve in
space and its associated errors. Currently, nothing is done
with the z and z-error vectors, but suggestions are welcome.
PowGraph - This is the only *displayed* object in POW. I.e. you can display
your Images and Curves only by creating a Graph with them as
members, or by plotting them on an existing Graph (at which
point they become part of that Graph). One Image or vector
can, of course, appear in any number of Graphs.
The TCL interface:
*arguments in angle brackets are optional
"Constructors"
powSetupColormap toplevel free_cells ?force_cmap? ?options? -
You should call this to create the first toplevel window for your
application unless you really want to do your own colormap
management. This proc will use the default colormap if it can
allocate enough colors or will allocate a Private pseudocolor colormap
with an attempt to minimize flashing. If this fails to find any
pseudocolor visuals, it will use the default colormap and disable
pseudocolor images in POW.
toplevel - this is the name of the toplevel you want to create.
it should probably be the first toplevel your application
creates (e.g. .mytop) and all subsequent toplevel creation
statements should include a "-colormap .mytop" option.
free_cells - the number of colors your application will need in
addition to what POW allocates for itself. If you get
BadColor errors (or the like) in your application, try
making this number bigger. If you keep getting a Private
colormap when your Default colormap is full, try making
this number smaller.
force_cmap - Forces different colormap behaviors. You might want
to give your users a way to set this themselves.:
0 - Default behavior. I.e. choose the "best" colormap.
1 - Force POW to setup a new private pseudocolor colormap
(very safe)
2 - Force POW to use truecolor mode (very safe, but
looks bad on low color displays and runs slower than
pseudocolor). Note: this will cause powSetupColormap
to look for a truecolor visual; if it can't find one,
it will allow the main Tk code to pick a visual,
but POW will still use "truecolor mode" (i.e. the
Tk photo widget) to display images.
3 - Force use of the screen default colormap. This should
be reasonably safe now, but often won't be what you
want.
options - a string of extra options to hand to the toplevel creation
command, if you need them.
See comments under powInit for more details.
powInit ?XColormapWindow? ?container? ?powGUI? - creates the .pow toplevel
window, all the user interface buttons and the .pow.pow
canvas. The second optional argument is the pathname of a
container window for POW if you want to embed POW in your own
toplevel (only works for Tcl/Tk8.0 and later versions).
The first optional argument is the name of a window in your
application and tells POW to use the same X colormap as that
window; this will allow your user to reliably see both POW
and your application in the proper colors at the same time.
Note, if you give an argument to powInit, that window should
have a pseudocolor visual with at least 60 free read-write
colorcells (call powSetupColormap first) or POW will disable
pseudocolor images. The third argument indicates wether you
want POW to wrap its main canvas in an enduser GUI. Unless
you're embedding POW in a specialized application, you'll
want to leave this at the default of 1; a value of 0 removes
the GUI.
If you call 'powInit none' (or with no argument) pow will handle
its own colormap needs, but if it creates a private colormap, you
will see serious flashing between your application's windows and
the POW window.
Usually, the window you specify for powInit would be the toplevel
window for your application and you should use powSetupColormap
to avoid excessive flashing and Xlib induced crashes. Make sure
you create any other toplevels with the same colormap. Unfortunately,
Tk has a stupid default behavior for picking the visual of a
new toplevel when it's colormap is specified, so it's recommended
that you use powToplevel to create all your toplevels (sorry folks,
this one's not my fault). Ok, since this is probably confusing,
here's an example.
Suppose (for argument) your application uses 10 colors (for
backgrounds highlights, etc) and your application's main window
is '.mytop'. And you want the background of your application to
be pink and you want it to be 100 pixels wide.
When you create .mytop instead of calling 'toplevel', instead do:
powSetupColormap .mytop 10 0 "-background pink -width 100"
Invoke POW with:
powInit .mytop
If you create any other toplevel windows, be sure to create
them with:
powToplevel .mydialogbox .mytop
If you need to pass other options to "toplevel", put them
all in one string like:
powToplevel .mydialogbox .mytop "-class \"My Extra Window\" -bg blue"
powToplevel topwin refwin ?option_string? -
This is a replacement for the Tk toplevel command. The Tk toplevel
command with a "-colormap" argument but no "-visual" argument
*doesn't* use the visual of the given colormap to create the new
window; instead it uses the screen default visual and then dies
if they're not compatible. Why? Who knows?
topwin The name of the toplevel you want to create.
refwin The window whose colormap you want to use.
option_string Any other options you want to pass to the "toplevel" command.
This needs to be a single string.
If you don't want to call powToplevel, doing this yourself is simple.
Here's the code for the powToplevel proc:
proc powToplevel {topwin refwin {options ""}} {
#this implements what *should* be default behavior. Apparently the evil
#of Xlib colormap handling is contagious.
eval "toplevel $topwin -colormap $refwin -visual \"[winfo visual $refwin] [winfo depth $refwin]\" $options"
}
powCreateData data_name data_pointer data_type length ?copy? -
This "constructs" a PowData object. The other ways
to create PowData at present are with the powCreateVectorEN
or the powCreateDataFromList commands, see below.
data_pointer This argument will probably be the return value from either:
$fitsfile load image
or
$fitsfile load column
See fitsTcl documentation for details. Or you can write your
own TCL command to make data. Just have it return a void
pointer formatted with:
sprintf(interp->result,rstring,"%p",(void *)dataptr);
data_type This is one of the strings (or an integer):
"BYTE" or 0 or 8 1 byte
"SHORTINT" or 1 or 16 2 bytes
"INT" or 2 or 32 4 bytes
"REAL" or "FLOAT" or 3 or -32 4 bytes
"DOUBLE" or 4 or -64 8 bytes
Note: 8 byte integers are not supported at this time
copy If copy is a positive integer, POW makes its own copy of the
data array and uses that, freeing it when the object gets
destroyed. If copy is zero, POW uses the supplied
data_pointer directly (no copy), but does not try to free
it when destroyed. If copy is negative, POW takes ownership
of the data_pointer, using it directly and freeing it when
the object gets destroyed. In this last case, the
data_pointer *must* have been allocated using TCL's
ckalloc() function (always true for data from fitsTcl).
The default value is 0.
powCloneData new_data_name old_data_name ?offset? ?length? ?copy?
This creates a new PowData object from an existing PowData object.
!!Use this function with caution unless you are specifying
a copy flag > 0 or you could wind up with POW Data objects that
point to invalid areas of memory if you destroy one of the
partners of the clone but not the other!!
Returns the length of the new POW Data object.
offset Specifies an offset to the starting point of the data
in memory. Default is 0.
length How much of the old data do you want to use? If you specify
"NULL" the new data will have the same endpoint as the
old data. If you specify a length that ends beyond the end
of the previous data, the length will be adjusted to match
the endpoint of the old data. Default is "NULL".
copy If copy is a positive integer, POW makes a new copy of the
old data array and uses that, freeing it when the object gets
destroyed. If copy is zero, POW uses the old data pointer
(plus offset) directly (no copy), and does not try to free
the memory when the new data object is destroyed. If copy is
negative, POW will flag the new_data_name as the "owner" of
the data array so destroying the old_data_name will not
free the associated memory, but destroying the new_data_name
will. If you specify copy < 0 and offset != 0, powCloneData
will return an error. The default value of copy is 0.
powCreateDataFromList data_name list_o_data ?stringflag? -
This creates a PowData object using the contents of a TCL list.
The data object will be of type DOUBLE unless stringflag is
is Yes. String data should only be used as the "z" vector
of a PowCurve object, in which case, the specified string will
be plotted at the position given by the corresponding x and y
values.
powRegisterData powdata_pointer
If you have an application that creates it's own PowData objects (like
the LHEA orbit library or the internal routines in TAKO), you must
"register" them in the main PowData hash table in order to use
them in plotting functions. Naturally, if the PowData objects
aren't properly or fully created, you could run into trouble.
The pointer is a string created the same way as described above for
the data_pointer argument to powCreateData, except that it should
be a pointer to a PowData structure rather than to a simple array.
powCreateVector vector_name data_name offset length units -
Creates a PowVector. If length is "NULL" uses the length
of the Data.
powCreateVectorEN vector_name data_name length start increment units -
Creates a vector and the data to go with it. This is nice
for generating test data among other things. You *can*
make a PowImage using the data this generates, by the way.
(EN stands for Ex Nihilo)
powCreateImage image_name data_name xoffset yoffset width height xorigin \
xinc yorigin yinc xunits yunits zunits -
Creates a PowImage. The xorigin and xinc arguments are the origin
and pixel size in the units specified in the xunits and yunits
arguments.
powCreateCurve curve_name x_vector x_error y_vector y_error ?z_vector z_error?
- Creates a PowCurve (displayable). All but one of the component
vector arguments can be the string "NULL" and POW will deal with
it in a hopefully sensible default manner. The length of the
curve will be the length of the first non-null vector (I might
change this to be length of the shortest vector present).
I'm also thinking of allowing scalar errors indicated by an
"=" sign in the argument (but this isn't done yet).
POW curves are now implemented with a new canvas item type.
For a curve named ACURVE displayed on a graph named BGRAPH,
the powCurve item has a tag "ACURVEBGRAPH". powCurve supports
most of the options available for the Tk native "line" type.
So to change the fill color of ACURVE to blue and make it a dashed
line (5 pixel dashes) do:
.pow.pow itemconfigure ACURVEBGRAPH -fill blue -dash 5
The only use of z_vector so far is if the z_vector is
created from STRING type data (e.g. using powCreateDataFromList),
then the strings will be printed at the positions given by the
corresponding x and y elements.
powCreateGraph graph_name curves images xunits yunits xlabel\
ylabel ?xdimdisp ydimdisp xmin ymin xmax ymax? -
This is the main one that actually draws on the .pow.pow canvas.
See discussion of powStartNewRow below to see how POW decides
where to place incoming graphs. Some details (hopefully the
rest is self-explanatory):
curves, images - these are Tcl "lists" of PowImages and PowCurves to plot
xunits, yunits - These are the physical units associated with an axis
and will be printed next to the label.
xlabel, ylabel - An optional label for each axis. The y-axis label will
be printed horizontally at the top of the y-axis since the Tk
canvas does not allow rotated text at this time.
xdimdisp, ydimdisp - the "maximum size" for the display of the graph in
screen pixels. The graph will be shrunk or expanded from its
"natural" size to fit into an area of the canvas of this requested
size. If "NULL" is passed, a default value will be used.
xmin ymin xmax ymax - the bounding region for the displayed area of a
graph. These are in the units of each respective axis. Parts
of images or curves falling outside this box will not be plotted.
Each of these arguments can be a list if more than one y or x axis is
present.
powGraphOptions graph_name option value ?option value option value ...? -
This function was added to allow easy customization of several
(more every day :) additional options that would have been too
unweildy to add to the already too long powCreateGraph call.
Specify as many option value pairs as you like. Boolean values
should have values of Yes/No if one wants POW's menus to properly
reflect the new values. In addition to all of the arguments to
PowCreateGraph, current options are:
bgcolor - A background color for the whole graph
xmargin - The amount of space around a graph (in pixels by default)
ymargin - This will only affect subsequent operations on the graph
(chain alignments, replottings, etc.), it doesn't move
the graph immediately.
handletext - Change the text that normally says:
"Select/Move: graphname"
handleanchor - Change the anchor point of the handletext. Default
is "sw".
handleposition - Change where on the graph's bounding box the
handle is anchored to. Choices are:
t - midpoint of top
l - midpoint of left side
b - midpoint of bottom
r - midpoint of right side
Combine to get corners. Default is "tl".
xNumTicks - An integer number used to indicate how many ticks to
place on the X axis. 3-6 are reasonable values.
yNumTicks - An integer number used to indicate how many ticks to
place on the Y axis. 3-6 are reasonable values.
xTickLength - 4 element list indicating how long to draw the x
tick marks on each of the 4 sides of the graph. Order
is {left right top bottom}. Negative values cause
tickmarks to be drawn inside the graph box.
yTickLength - Same for y tick marks.
xLabelTicks - 4 element boolean list indicating whether the x tick
marks should be labeled along each side of the graph.
Order is {left right top bottom}.
yLabelTicks - Same for y tick labels.
xTickScal - Scaling method for the X tick marks. Valid values
are "linear", "wcs" (for celestial coordinates/right
ascension), or "log" (for logarithmic scaling). Tick
marks and labels will be drawn accordingly. WCS scaling
occurs only if WCS information exists for the graph.
Logarithmic scaling *does not* affect the drawing of
curves (ie, curve data are assumed to be in logarithmic
format).
yTickScal - Same for y ticks. WCS scaling assumes declination
values for the y axis, though.
GridLines - A boolean value indicating whether to draw grid lines
connecting the graph's tick marks
GridColor - The color of the grid lines
GridDash - Dash value of the