# readScan.pro

At present this program is installed in the /usr/local/epics/extensions/bin/$HOST_ARCH directory. This program is written in IDL 5.1 programming language . It provides the IDL user conveninent methods of accessing scan data set automatically saved by the IOC savedata software.

In order to access scanSee data from other IDL program, a user has to make sure that the following environment variable is set before invoking IDL :

         setenv EPICS_EXTENSIONS  /usr/local/epics/extensions

         setenv IDL_STARTUP /usr/local/epics/extensions/bin/$HOST_ARCH/viewer_startup.pro

and make sure including the directory /usr/local/epics/extensions/bin/$HOST_ARCH in his/her IDL search path.

During an IDL session to access scanSee data by entering :

         .run readScan

For an example to access the scan data with the scan data structure pointer gD, where the scan data is saved in the file 'rix:._0003.scan':

         readScanFile,'rix:._0003.scan',gD

To view the scan data summary:

         scanImage_print,gD

# List of Routines

- READSCANFILE
- SCAN1DDATA
- SCAN2DDATA

# Routine Descriptions

## READSCANFILE

[Next Routine] [List of Routines]

     NAME:
           READSCANFILE

     PURPOSE:
    	This procedure reads the scan file which was automatically created
           by the IOC and returns a pointer structure to point to the scan
           data components.

     CALLING SEQUENCE:
           READSCANFILE, Filename, Gp, Scanno

     INPUTS:
    	Filename:    Specifies the IOC saved scan file name to be read.

     KEYWORD PARAMETERS:
           None.

     OUTPUTS:
           Gp:          Parameter used to return the pointer of scan
                        structure which consists of the scan data pointers to
                        scan data components

           Scanno:      Optional output, it returns the scan number of the file.

     RESTRICTIONS:
           The directory /usr/local/epics/extensions/bin/solaris must be
           in your IDL search path.

           The scan data is saved in XDR format by the IOC scan save data
           software.

     EXAMPLE:
           In the following example it read a 2D scan file 'cha:_0000.scan' from
           the directory /home/sricat/CHA/rix directory and the pointer gD is
           used to store the scan data structure.

           Then the image of detector 2 is selected and plotted and the 2D
           image is returned as Im varaible (15 detectors supported).

           Then for 1D scan # 5, a 1D plot is desired, the positioner 1 is
           selected as X axis, the detecor 1,2,3 are selected for Y array.

           file = '/home/sricat/CHA/rix/cha:_0000.scan'
           ReadScanFile, file, gD
           scan2Ddata, gD, 2, /view, xarr=xarr, yarr=yarr, im=im
           scan1Ddata, gD, 5, /plot, xarr=x, yarr=y, xsel=0, ysel='0,1,2'

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Sept 4, 1998.
    	xx-xx-xxxx	comment

(See readScan.pro)

## SCAN1DDATA

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           SCAN1DDATA

     PURPOSE:
    	This procedure extracts scan data and returns as IDL varibles
           from the given scan structure pointer. It is able to extracts
           data from either 1D or 2D scan data.

     CALLING SEQUENCE:
           SCAN1DDATA, gD, sN, /PLOT, Pa=Pa, Da=Da, Xarr=Xarr, Yarr=Yarr, ...

     INPUTS:
           gD:          Parameter to specify the pointer of scan data structure
                        returned by the procedure READSCANFILE
           sN:          Speicifies the desired 1D scan number.

     KEYWORD PARAMETERS:
           Plot:        If specified, the selected detector data will be plotted
                        by PLOT1D program.
           Xsel:        Specifies the desired positioner as X aixs, default 0
           Ysel:        Specifies a string of desired detectors, default to all
                        defined detectors in the Da array
           Xarr:        Returns the X vector of the selected  positioner
           Yarr:        Returns the Y array of the selected detectors
           Xdesc:       Returns the X positioner desc string
           Ydesc:       Returns the Y positioner desc string
           Xengu:       Returns the X positioner engu string
           Yengu:       Returns the Y positioner engu string
           Npts:        Returns the data points in the X vector
           Title:       Returns the inner scan record pvname
           Pa:          Returns the original positioner array of inner scan
           Da:          Returns the original detecotr array of inner scan
           id_def:      Returns the vector of monitored positioners and detectors
                        of inner scan record
           Scanno_2d:   Returns the 2D scan number

     RESTRICTIONS:
           Same as READSCANFILE.

     EXAMPLE:
           In the following example it read a 2D scan file 'cha:_0000.scan' from
           the directory /home/sricat/CHA/rix directory and the pointer gD is
           used to store the scan data structure.

           Then the image of detector 2 is selected and plotted and the 2D
           image is returned as Im varaible (15 detectors supported).

           Then for 1D scan # 5, a 1D plot is desired, the positioner 1 is
           selected as X axis, the detecor 1,2,3 are selected for Y array.

           file = '/home/sricat/CHA/rix/cha:_0000.scan'
           ReadScanFile, file, gD
           scan2Ddata, gD, 2, /view, xarr=xarr, yarr=yarr, im=im
           scan1Ddata, gD, 5, /plot, xarr=x, yarr=y, xsel=0, ysel='0,1,2'

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Sept 4, 1998.
    	xx-xx-xxxx	comment

(See readScan.pro)

## SCAN2DDATA

[Previous Routine] [List of Routines]

     NAME:
           SCAN2DDATA

     PURPOSE:
    	This procedure extracts various 2D scan data components and returns
           as IDL varibles from the given scan structure pointer.

     CALLING SEQUENCE:
           SCAN2DDATA, gD, dN, /VIEW, Im=Im, Xarr=Xarr, Yarr=Yarr, ...

     INPUTS:
           gD:          Parameter to specify the pointer of scan data structure
                        returned by the procedure READSCANFILE
           dN:          Speicifies the desired image number, i.e. detector number.

     KEYWORD PARAMETERS:
           View:        If specified, the TVSCL of the 2D image is plotted.
           Xarr:        Returns the positioner 1 vector of X scan
           Yarr:        Returns the positioner 1 vector of Y scan
           Im:          Returns the 2D image of the selected detector
           Width:       Returns the X width of the 2D image
           Height:      Returns the Y height of the 2D image
           Xdesc:       Returns the X positioner desc string
           Ydesc:       Returns the Y positioner desc string
           Xpv:         Returns the X scan record pvname
           Ypv:         Returns the Y scan record pvname
           Scanno:      Returns the 2D scan number

     RESTRICTIONS:
           Same as READSCANFILE.

     EXAMPLE:

           In the following example it read a 2D scan file 'cha:_0000.scan' from
           the directory /home/sricat/CHA/rix directory and the pointer gD is
           used to store the scan data structure.

           Then the image of detector 2 is selected and plotted and the 2D
           image is returned as Im varaible (15 detectors supported).
           Then for 1D scan # 5, a 1D plot is desired, the positioner 1 is
           selected as X axis, the detecor 1,2,3 are selected for Y array.

           file = '/home/sricat/CHA/rix/cha:_0000.scan'
           ReadScanFile, file, gD
           scan2Ddata, gD, 2, /view, xarr=xarr, yarr=yarr, im=im
           scan1Ddata, gD, 5, /plot, xarr=x, yarr=y, xsel=0, ysel='0,1,2'

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Sept 4, 1998.
    	xx-xx-xxxx	comment

(See readScan.pro)