Information

CONTENTS

FIGS for the Impatient

To make a FIGS graphics file for data or Monte Carlo do the following: These five steps will create a FIGS graphics file with at most 20 events, by writing events to your FIGSOUT file. To view the events in the file, run FIGS. You can also skip the last two steps if you want to look at the first 20 events without selecting any particular events.

Note: this produces the largest possible FIGS graphics file. To refine your selections, see the following description of the FIGSFLAG namelist.

Creating a FIGS graphics file

A FIGS graphics file is an ASCII file that is used for graphics purposes, and it usually includes the FOCUS detector geometry, data recorded by the detector, and results from event reconstruction software. The file is arranged so that the detector geometry comes first, followed by data for individual events.

FIGS graphics files can be created for data or Monte Carlo. The code that writes the files has been fully integrated into the driver routines, so anybody who is familiar with the template can create FIGS graphics files by following these steps:

Set flag(s) in the CONTROL namelist:

There are two flags (DOFIGS and FIGALL) in the CONTROL namelist that control the routines that write FIGS graphics files. The DOFIGS flag is used to tell the routines to write a file, by setting DOFIGS = 1. Note that the default setting is DOFIGS = 0, which tells the routines NOT to write a graphics file. The FIGALL flag is used to set a value for all of the flags in the FIGSFLAG namelist. For example, to write out all of the available graphics data for every detector, set FIGALL = 2. Note that this produces the largest possible graphics file for your events.

Include a FIGSFLAG namelist:

The FIGS routines use a namelist called FIGSFLAG to control what is written to a FIGS graphics file. This namelist is very similar to DRVFLAG in format and purpose. To work correctly within the template, it should follow USRFLAG in the e831job.nam namelist or the mcfocus.nam namelist.

A complete list of FIGSFLAGs can be found in "What does FIGS have now?"

This is a sample FIGSFLAG namelist: 

 $FIGSFLAG
  MAXFIGS =          20
  FIGSTG  =           0,
  FIGSSD  =           1,
  FIGPWC  =           1,
  FIGSTW  =           0,
  FIGCER  =           0,
  FIGIEC  =           1,
  FIGOEC  =           0,
  FIGHDC  =           0,
  FIGOMU  =           0,
  FIGIMU  =           0,
  FIGHXV  =           0,
 $END

You can see that there is a flag for each detector as well as MAXFIGS, which sets the maximum number of events that will be written out.

A negative value for the detector flag means that the geometry information (a picture of the detector) is written out, but no event information is output.

A postive value means that both geometry and event infomation is written out for that detector element. Different positive values of the flags make it possible to instruct the individual routines to write out different types of information. This mechanism is used for the SSD and PWC routines, which write out tracks and/or hits depending on the value of FIGSSD and FIGPWC, respectively. For example, to write out PWC tracks set FIGPWC = 1; to write out PWC tracks and PWC hits set FIGPWC = 2.

Define the FIGSOUT environment variable:

To write a FIGS graphics file you must supply the name of an output file. Use the FIGSOUT environment variable to do this in your e831job.run or mcfocus.run file.

Here is an example: 

  setenv FIGSOUT figs.ster
  if (-e $FIGSOUT) rm -f $FIGSOUT

The second line in this example will delete a figs.ster file, if one exists. Note that you can also write the FIGS graphics data to a UNIX named pipe (a file that acts like a FIFO) by adding 

  mknod $FIGSOUT p

to your script. This will not work for AFS directories, so you could use an NFS mounted scratch disk if you are working on fnalu.

Selecting events in your USRANAL:

To select particular events for output to the FIGS graphics file, you can impose cuts to select the events in your USRANAL routine and set FIGEVNT = 1 to write out the events. Events that should NOT be written to the graphics file should have FIGEVNT = 0 in USRANAL.

Calling FIGSANAL for diagnostic purposes:

FIGSANAL is the subroutine that is called by DRVANAL to write an event to the FIGS graphics file. You can easily write the same event more than once by calling FIGSANAL at different locations in the code. This is useful to see what an event looks like at different stages in the event reconstruction. In order to "label" the event to keep track of the different stages, one can temporarily use the spill number to tag the event. For example, 
      isave_spill = spill
      spill = 3
      FIGEVNT = 1
      call FIGSANAL
      FIGEVNT = 0
      spill = isave_spill

can be inserted anywhere in the reconstruction code. This will write an event to the FIGS graphics file, and tag the event using the spill number. Note that the FIGEVNT variable must be set to one so that the FIGSANAL routine will write out the event.

Adding more things to FIGS

FIGS was designed to make it easy to add more detectors, to add different ways of viewing event data, and easy to modify the graphical user interface. We have numerous examples of code in the FIGS library to display the detectors and event data for FOCUS. The code in the FIGS display library can be modified to add new features to FIGS.


Writing display routines

The display routines for both FOCUS detectors and event data are called by two subroutines, figsgeom and figsanal. All together there are four routines that control the code that produces FIGS graphics files. The following description provides an overview of these four routines.

The first routine that is called is figsinit. This routine serves three purposes. First, it reads the FIGSFLAG namelist. The values from the namelist are put in a common block in FIGSFLAG.INC. Next it allocates a unit number with GETLUN, and opens the file that is associated with the FIGSOUT environment variable. Third, it defines various shades of orange that are used to represent different energy values, which are also stored in FIGSFLAG.INC.

The second routine is figsgeom. Each detector has a subroutine that is called to write graphics primitives to the FIGS graphics file. Each detector subroutine, FIGSG_xxx, includes the FIGSFLAG.INC file, and writes its output to UNIT=lunfigg. The output is a series of graphics primitives that specify the geometry of the detector.

The figsanal routine is similar in function to figsgeom. Detector routines that are called by figsanal write their output to UNIT=lunfigs, which has been defined to be the same as lunfigg (in an earlier version of the code we wrote the geometry and event data to two different files).

The fourth routine is figsstop, which shuts everything down and closes the files.


Graphics primitives

Each FIGS graphics object has several necessary parts and some optional parts that define the object. There are two parts that are essential to define an object for FIGS. The first is that the object must be given a NAME, which can be anything such as a mirror number, PWC track number, counter number with an ADC value, etc. Then the object is given a TYPE. See Erik for the right types for each object as it will affect how things are turned on and off in the display.

Optional parts include the COLOR of the object. Valid colors range from 1-39. The local ORIGIN of the object is optional and defaults to (0,0,0), the center of the M2 magnet. X-, Y-, and Z-UNIT vectors are optional, and can be used for scaling and coordinate transformations. In most cases the unit vectors are unnecessary and should be left out.

Here is an example borrowed from the IE code:

      write (lunfigg,5000) 'NAME: IE Calorimeter East'
      write (lunfigg,5000) 'TYPE: IE'
      write (lunfigg,5000) 'COLOR: 7'
      write (lunfigg,5100) 'ORIGIN: ',0.0,0.0,LGZFACE-SP(6)
      write (lunfigg,5000) 'X-UNIT: 1.0 0.0 0.0'
      write (lunfigg,5000) 'Y-UNIT: 0.0 1.0 0.0'
      write (lunfigg,5000) 'Z-UNIT: 0.0 0.0 1.0'
Next comes the code that specifies the lines and/or planes that define the object. For example, 
      write (lunfigg,5000) 'PLL: 2'
      write (lunfigg,5000) '    0.0  0.0  1.0'
      write (lunfigg,5000) '    5.0  0.0  8.0'
specifies a line that is drawn from (0,0,1) to (5,0,8). The PLL graphics primitive instructs FIGS to draw a line, and the "2" indicates that the two sets of x,y,z values that follow define the coordinates of the line. To draw a line with 6 points, use PLL: 6 followed by 6 sets of x,y,z values.

Other graphics primitives include PGL (polygon drawn with lines), PGF (filled polygon without a border), PGP (filled polygon with a border). The graphics object can include as many graphics primitives as are needed to specify the lines and planes that define the object.

What does FIGS have now

The following table lists the routines associated with each piece of the FOCUS apparatus, and lists the FIGS flags that can be used to select what you would like to include in a FIGS graphics files.

ApparatusGeometry CodeEvent CodeSettings for FIGS flags
Magnets figsg_mag.sf
none
BeO target figsg_tar.sf
none
Target Silicon figsg_stg.sf figsa_stg.sf FIGSTG=1 - planes and hits
SSDs figsg_ssd.sf figsa_ssd.sf FIGSSD=1 - planes and tracks
FIGSSD=2 - planes, tracks and hits
FIGSSD=3 - planes, tracks and strips
PWCs figsg_pwc.sf figsa_pwc.sf FIGPWC=1 - chambers and tracks
FIGPWC=2 - chambers, tracks and hits
IE figsg_iec.sf figsa_iec.sf FIGIEC=1 - detectors and hits
OE figsg_oec.sf figsa_oec.sf FIGOEC=1 - detectors and hits
HC figsg_hdc.sf figsa_hdc.sf FIGHDC=1 - detectors and hits
IMU figsg_imu.sf figsa_imu.sf FIGIMU=1 - detectors and hits
OMU figsg_omu.sf figsa_omu.sf FIGOMU=1 - detectors and hits
HxV & OH figsg_hxv.sf figsa_hxv.sf FIGHXV=1 - detectors and hits
Straws figsg_stw.sf
FIGSTW=1 - detectors

Last updated July 8, 1997