DERVISH primer

QUESTIONS

  • 1. What is DERVISH?
  • 2. What does DERVISH stand for?
  • 3. How do I access DERVISH?
  • 4. Can I print out documentation?
  • 5. What can I do?
  • 6. How can I turn c code into a DERVISH command?
  • ANSWERS

    1. What is DERVISH? To support the photometric pipeline development, the data acquisition system development, and the development of other pipelines, Fermilab has written or integrated a number of utility routines that are known collectively as DERVISH. At present these routines include the following: - a command line interpreter (TCL from Berkeley); - a plotting package (pgplot from Caltech); - a set of FITS IO routines (borrowing from LIBFITS by Alan Uomoto); - an image display routine (SAOIMAGE); - a system of help files and a hypertext reader. Typically, if you want to develop and test a module for one of the pipelines, you will start with TCL and the DERVISH routines together. 2. What does DERVISH stand for? Survey Human Interface and Visualization Application. It also is the Hindu goddess of destruction. 3. How do I access DERVISH? The following commands get you going: % setenv DISPLAY hostname:0.0 (This sends Xwindows output to your screen. I assume that is what you want. Replace "hostname" with the name of the machine you are looking at.) % setup www % setup dss % setup dervish % xmosaic & (This starts the help file browser) % dervish Executing commands in /usr/products/IRIX/dervish/vx_y/etc/dervishStartup.tcl: dervish> help . . listing of help; similar to xmosaic, but all in ASCII in case you don't . have or like Xwindows. . 4. Can I print out documentation? Look in $DERVISH_DIR/doc to find: - the_dervish_book.ps (a postscript file) - RELEASE_NOTES (text file). The basic idea is to have everyting online through www and its readers, but you may want to have a printed copy too. But note, that the online documentation is generally more up to date. 5. What can I do? Here is a quick example of reading in a FITS file, displaying it, making a simple plot, and writing out a FITS file. % dervish Executing commands in /usr/products/IRIX/dervish/v2_1/etc/dervishStartup.tcl: dervish> regNew h0 dervish> regReadAsFits h0 $INT_DIR/fits/m51.fits h0 dervish> saoDisplay h0 Spawning Fermi SAOimage 1 (This makes a new window. Position it and click to open the window. The display is mostly black. A couple of buttons help bring out the features: "sqrt" makes it use square root scaling; "Color" brings up another set of buttons; "cmap" brings up a set of color maps; "B" selects a particular color map. Move the cursor to the main display area of saoDisplay. Hold down the left mouse button and drag it around to change the color mapping. When you have seen enough: "etc" gives you the original set of buttons; "QUIT" gets you out of the display. dervish> dervishPlot ? (This gives you the list of options for this module.) dervish> dervishPlot h0 -row 100 (This brings up another window with a plot of pixel values vs. column number for row 100 of the region.) dervish> dervishPlot h0 -row 101 (You can do this easily by hitting the "uparrow" key and editing the command. dervish> quit (Note that this leaves the pgplot window around. You can kill it with window manager commands.) 6. How can I turn c code into a dervish command? Dervish is driven with a simple template program. To integrate new code into this template, you need to: - get your own copy of dervish_template.c - add a line that calls the module that defines your commands - get your own copy of the makefile and add in references to your code - write your code. Suppose we wanted to define a new command that takes the average of two numbers. We will call the command privateAvg. Here is what you do: A. Copy over the files of interest: % cp $DERVISH_DIR/examples/dervish_template.c . % cp $DERVISH_DIR/examples/Makefile . B. Compile and run this to make sure it works: % sdssmake Tue May 11 12:14:40 CDT 1993 Building for IRIX === Building main program : ./dervish_template === cc -g -I. -I/usr/products/IRIX/dervish/devel/include -I/usr/products/IRIX/dervish/devel/examples -I/usr/products/IRIX/ftcl/v1_2/include -I/usr/products/IRIX/libfits/v1_0/src ./dervish_template.c -L/usr/products/IRIX/ftcl/v1_2/lib -L/usr/products/IRIX/libfits/v1_0/lib -L/usr/products/IRIX/pgplot/v4_9ef1/lib -L/usr/products/IRIX/dervish/devel/lib -L. -o ./dervish_example -ldervish -ltcl -lfits -lpgplot -lsun -lgl -lF77 -lI77 -lU77 -lisam -lfgl -lX11 -lc -lm === Main program : ./dervish_template built === % dervish_template Executing commands in /usr/products/IRIX/dervish/devel/etc/dervishStartup.tcl: dervish> quit % C. Take a look at the dervish_template.c file: - a list of .h files to define our structures and functions - a place to change the prompt. - initialization to begin reading commands - declaration of commands - a place for your own TCL declarations - the standard initialization - a place for your own initialization - a loop that gets a command and executes it - a clean-up phase when you have no more commands. D. We will make three changes to this file. 1. Change the prompt to make the line look like this: #define L_SHPROMPT "NEWVERB> " /* Command line prompt for Dervish */ 2. Modify dervish_template.c to call the declaration module we will write. It will be called privateTclDeclare. So, after the comments line that says PLACE YOUR FAVORITE TCL DECLARATIONS HERE add the line: privateTclDeclare(interp); 3. Put in the prototype for this call, after the line that includes dervish.h: #include "dervish.h" void privateTclDeclare(Tcl_Interp *interp); E. Now we need to actually write the code! We have to write two separate things: an initialization for the verb, and the code that does the work. Put the following in a file called privateTclVerbs.c: (If you don't want to type this all in, look in $INT_DIR/dervish for this file.) /* * * This is privateTclVerbs.c to illustrate how to write a TCL verb in c * * Chris Stoughton May 11, 1993 * */ #include "dervish.h" /* * This is the code that does the actual work: * * The format of the verb is: * privateAvg x y * where x and y are floats to be averaged */ int privateAvg (ClientData clientData, Tcl_Interp *interp, int argc, char**argv) { /* declare variables we will use */ char *formalCmd="x y"; /* this is the prototype for the arguments */ double x, y; /* these are the two input values */ float average; /* the answer */ char answer[20]; /* the answer, as a string, returned to TCL */ /* parse information from the command */ /* create and initialize a new interpreter */ ftclParseSave("ftclParsePrivateAvg"); if (ftclFullParseArg(formalCmd, argc, argv)) { /* successful parse */ x = ftclGetDouble("x"); y = ftclGetDouble("y"); average = (x+y)/2.0; printf("x,y,average %g %g %f \n",x,y,average); sprintf(answer,"%f",average); Tcl_SetResult(interp, answer, TCL_VOLATILE); ftclParseRestore("ftclParsePrivateAvg"); return (TCL_OK); } /* successful parse */ else { /* not a successful parse */ Tcl_SetResult(interp, "Usage: privateAvg x y", TCL_VOLATILE); ftclParseRestore("ftclParsePrivateAvg"); return (TCL_ERROR); } /* not a successful parse */ } /* privateAvg */ /* * This is the declaration stage, called by the main program */ void privateTclDeclare(Tcl_Interp *interp) { Tcl_CreateCommand(interp, "privateAvg", privateAvg, (ClientData) 0, (Tcl_CmdDeleteProc *) NULL); } F. Tell the makefile to use this new code. Add to the line that defines USEROBJECTFILE so it looks like this: USEROBJECTFILE = dervish_template.o privateTclVerbs.c G. Build and test this new verb: fndaub % sdssmake Tue May 11 16:24:18 CDT 1993 Building for IRIX === Building main program : ./dervish_template === cc -g -I. -I/usr/products/IRIX/dervish/v2_1/include -I/usr/products/IRIX/ dervish/v2_1/examples -I/usr/products/IRIX/ftcl/devel/include -I/usr/products/IR IX/libfits/v1_0/src ./dervish_template.c privateTclVerbs.c -L/usr/products/IRIX/f tcl/devel/lib -L/usr/products/IRIX/libfits/v1_0/lib -L/usr/products/IRIX/pgplot /v4_9ef2/lib -L/usr/products/IRIX/dervish/v2_1/lib -L. -o ./dervish_template -lsh iva -ltcl -lfits -lpgplot -lsun -lgl -lF77 -lI77 -lU77 -lisam -lfgl -lX11 -lc - lm ./dervish_template.c: privateTclVerbs.c: === Main program : ./dervish_template built === sdssmake completed Tue May 11 16:25:03 CDT 1993 fndaub % dervish_template Executing commands in /usr/products/IRIX/dervish/v2_1/etc/dervishStartup.tcl: NEWVERB> privateAvg 4.4 6.6 5.500000 NEWVERB> privateAvg [privateAvg 1 2] [privateAvg 3 4] 2.500000