PROGRAMMER'S DOCUMENTATION FOR THE PIX ROUTINES by John Keyser 7/27/94 I. Overview The Pix routines are a set of routines designed to work with the E866 analysis program. The routines are based on CERN's HIGZ libraries, and were originally written using version 94b. The routines are closely tied in with the KUIP user interface system, and some routines rely on it. The routines create a HIGZ window in which a picture of the apparatus is drawn. Along with the picture, several pieces of data are printed out. Options are provided to allow the user to manipulate certain aspects of the picture (such as the viewing angle, colors, and whether or not certain parts of the picture are displayed). In addition several other functions are provided to handle miscellaneous things (such as printing a hardcopy or printing out the raw data) II. How the whole thing works The most basic routine in the program is PIX. It can be called in three modes - initialization (1), execution (2), or cleanup (3). PIX is initialized from COMAND, just after the initialization of KUIP (since the PIX initialization uses KUIP commands). PIX is executed after each event is processed, and is cleaned up from FINI. Initialization and cleanup are performed by calling the routines GRAPHSET and CLEANUP, respectively. When PIX is executed, TIMETOGO is called first to determine whether or not it is time to display a new picture (result is returned in Readyfornext). If it is time, the variable data (data which changes from event to event) is copied into pix data structures via PIXDATA. Then, the picture is drawn (DRAWIT). DRAWIT prepares the screen and then calls routines to draw the axes section (DRAWAXES), the text section (DRAWTEXT), and the picture of the apparatus (DRAWAPP). DRAWAPP in turn calls the routines which draw each component of the apparatus separately. The portions drawn are: the target (DRTGT), SM12 (DRSM12), SM3 (DRSM3), the beam dump (DRBMDMP), the calorimeter (DRCAL), the prop tubes (DRPTUBES), the hodoscopes (DRHODO), the drift chambers (DRDRIFT), and the tracks (DRTRACK). The commands to allow the user to manipulate aspects of the picture are contained within GETINPUT (for direct interaction), and ACTION (along with KUDEF for KUIP interaction). Writing the picture to a file is accomplished via HARDCOPY, and writing the raw event data to a file is accomplished via RAWDUMP. III. The routines PIX - The primary routine, it handles calling other routines for initialization, execution, and cleanup. GRAPHSET - The routine called to initialize the pix variables. It relies on several KUIP commands for operation (this can be modified fairly easily to not use KUIP commands, if desired). SETWINDOW - The routine to set up the window and normalization transformations which are used by HIGZ. TIMETOGO - The routine which determines whether or not it is time to display a new picture, based on the current mode settings. PIXDATA - Copies any variable data (data which varies by event) used by PIX into PIX data structures. DRAWIT - The routine called to handle drawing of the picture during the PIX execution phase. GETMAXMIN - Gets the maximum and minimum X and Y values which need to be able to be displayed on the screen. DRAWAXES - Draws the small set of axes in the upper right hand corner which give the user an idea of the direction of view. DRAWTEXT - The routine which draws the text section of the picture, along with the "help line" at the bottom of the picture. DRAWAPP - Handles drawing of the actual apparatus. It calls a separate routine for each portion of the apparatus. DRTGT - Draws the target (estimated). DRBMDMP - Draws the Beam Dump (estimated). DRSM12 - Draws SM12 (estimated). DRSM3 - Draws SM3 (estimated). DRCAL - Draws the calorimeter outline. DRPTUBES - Draws the prop tubes with any hits. DRHODO - Draws the hodoscopes with any hits. DRDRIFT - Draws the drift chambers with raw and associated hits. DRTRACK - Draws the reconstructed tracks, along with the intersections of these tracks with detectors. CLRAXES - Clears the axes portion of the screen by writing a background color box over it. CLRAPP - Clears the apparatus portion of the picture by writing a background color box over it. PRIMITIVE - The routine called to draw basic graphics primitives in 3 dimensions. It uses TRANSFORM to convert to 2-D. TRANSFORM - The routine which converts 3 dimensional coordinates to two dimensional coordinates based on viewing parameters. CLEANUP - Closes and deactivates things opened by PIX. GETINPUT - The routine which handles input from mouse-picture interaction. It will wait for some mouse-window interaction (such as movement within the window, leaving the window, or pressing a button in the window) before moving on. ACTION - Contains information on what to do given various KUIP commands. Commands other than just PIX commands are included here. HARDCOPY - Writes the current picture being displayed to a file. RAWDUMP - Writes the raw data for the displayed event to a file. Other routines which contain Pix calls or info, but are not pix routines are: ANALY, DIMUSE, EVENTS, TRACER, PBSWIM, FINI IV. Additional Comments There are still a number of areas in which the pix routines may be able to be improved. First of all, a number of the non-detector parts of the apparatus contain hardcoded data, survey file information which may be inaccurate, or outright guesses as to points. This is due to a lack of more accurate information at the current time. If better data becomes available, these routines should be modified to reflect this. The other major area for improvement comes in the area of user interaction with the picture. Right now, the only way that a user can interact directly with the picture is after giving the KUIP command INTERACT (under the /COMMAND/PICTURE directory). It would be nice to be able to interact directly with the picture at all times. A number of options have been explored toward this end, but so far, none have been successful. The primary reason that nothing has been successful is that in almost every case, one must write X routines. The X routines will require display and/or window information in order to work correctly. The display and window information used in HIGZ, however, is declared static (in C), which means that it is inaccessible outside of the HIGZ library. If this could be handled in some other way, one of the options looked at already might offer an accceptable solution. Briefly, the options looked at so far include: 1. Modify the IRQLC routine so that it will "poll" the mouse, returning a value regardless of whether or not the mouse has had any interaction with a window. This would let one call GETINPUT from several points in the program to check for mouse input. 2. Modify FSELECT to check whether the next event to be processed is one which occurred in the PIX window. If so, graphset could be called. If not, the normal event handlers would take over. 3. Modify KEYEV to call another routine, PIXEVENT, which would search the queued events, and if one were found for the PIX window, would stick it on the front of the queue and then call GETINPUT. This is along the same lines as modifying FSELECT. There are also other solutions which involve writing X routines to check events. 4. Put the HIGZ window inside a KUIP window, as explained in the KUIP manual (even this part has not been successfully done). Then, write a callback routine which handles any input which occurs in the PIX window and acts on it via GETINPUT. The main disadvantage to this type of solution is that input will only be checked as often as it is checked for normal KUIP events, which currently is only once per event. This is the solution suggested by Olivier Couet (who wrote much of HIGZ) when asked about the problem. His response is included here in order to aid any followup: > ----------------------------Original message---------------------------- > Hello. > I have a question regarding one of the CERN routines. I was > told to direct my question to this address, but if that is incorrect, > please excuse me and direct me to the correct person. > To put it simply, I am wondering if there is a (probably > undocumented and certainly unreleased) HIGZ routine which works like > IRQLC, but uses polling (as opposed to reqesting or sampling). > The overall situation is this: We have an analysis program > running with a KUIP (Motif) interface. This program calls a set of > routines which display a HIGZ window (not in a KUIP graphics window). > We would like to be able to continue analyzing events, but check > occasionally for interaction with the HIGZ window (much as we already > do to process KUIP commands). Unfortunately, using IRQLC causes the > program to wait at each check for input until it receives at least a > mouse movement. Polling would fix this. > We have thought of other possible solutions, involving > writing Xlib functions, but these would require access to the display > and window information from the HIGZ library. This information is > declared as static, however, so we are unable to access it. If > routines were added which could "pass out" this information, that > would offer an alternate solution to our problem. > If you have any comments or suggestions, or might be able > to direct me to someone else, I would really appreciate it. Thanks > for your time. > - John Keyser > keyser@p2hp2.lanl.gov > If I understand correclty, you want to include the HIGZ windows into the Motif event loop ? The only way to do that is to put the HIGZ windows inside KUIP windows as it is explain in the KUIP manual. After, a "call back" can be attached to these windows with the following calling sequence: SUBROUTINE XXX (IX,IY,NBI,IWIN) all are input parameters: IX, IY are the screen coordinates (in pixel) NBI is the button pressed IWIN the window. in this routine you you can call IRQLC like X = FLOAT(IX) Y = FLOAT(IY) CALL IRQLC(1,99,ISTAT,NT,X,Y) to convert IX IY into world coordinates. to declare XXX to KUIP you should do EXTERNAL XXX CALL KUMLOC(XXX) to tell HIGZ to put his windows inside KUIP windows put the directive: >Graphics inside the CDF. O.Couet -- Org: CERN, European Organization for Nuclear Research. Mail: CH-1211 Geneve 23, Switzerland Phone: +41 22 7674886 E-Mail: couet@hphigz.cern.ch Fax: +41 22 7677155 V. Flow of program ANALY ---> PIX(1) --------> GRAPHSET ------> SETWINDOW ^ | |--> TIMETOGO |--| EVENTS --> PIX(2) -----|--> PIXDATA | |--> DRAWIT --------| |--> GETINPUT |----> GETMAXMIN | | FINI ----> PIX(3) --------> CLEANUP | | | | | | -------------------------------------- | | | | |-----> CLRAXES | |-----> DRAWTEXT | | | | | |-----> DRAWAXES ------+-----> TRANSFORM <-------- | | ^ | | | | |-----> PRIMITIVE <--- | | |-----> DRAWAPP ----- | | | |--> DRTGT --------] | |--> DRBMDMP ] | |--> DRSM12 ] | |--> DRSM3 ] | |--> DRCAL ]----- |--> DRPTUBES ] |--> DRHODO ] |--> DRDRIFT ] | (DRDCHIT) ] |--> DRTRACK ------] (DRINT) KUIP -- PIX ----- | | V V ACTION -----> GETINPUT ----- | |-----> DRAWIT | | |-----> RAWDUMP <--------+-----> DRAWAXES | | |-----> HARDCOPY <-------+-----> DRAWAPP | |-----> CLRAXES | |-----> CLRAPP