# scan2d__define.pro

At present this program is installed in the /usr/local/epics/extensions/bin/$HOST_ARCH directory. This program is written in IDL 5.0 object programming language . It allows the IDL user easily to access 2D scan data captured by the data catcher.

In order to access scan2d object 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.

From the unix operating system to access IDL scan2d object class by entering :

         idl  go_scan2d

The files u_read.pro, and scan2d__define.pro are automatically loaded into IDL 5.0 for user.

For an example to create a 'scan2d' object with variable name as v2, where the 2D catcher data is saved in the file 'junk2.image':

         v2 = obj_new('scan2d',file='junk2.image')

To view the image number 135 from the file:

         v2->view,135

# List of Routines

- SCAN2D::ASCII
- SCAN2D::DATATOTEXT
- SCAN2D::INDEX
- SCAN2D::OPEN
- SCAN2D::PANIMAGE
- SCAN2D::POINT_LUN
- SCAN2D::PRINT
- SCAN2D::READ
- SCAN2D::SAVE
- SCAN2D::VALID
- SCAN2D::VIEW

# Routine Descriptions

## SCAN2D::ASCII

[Next Routine] [List of Routines]

     NAME:
    	scan2d::ASCII

     PURPOSE:
           This method allows the user to create a list of ASCII data files
           based on the user specified list of image numbers. The name convention
           of each ASCII file will be the image file suffixed with its 4 digit
           image number.

     CALLING SEQUENCE:
           Obj->[scan2d::]ASCII, List, /NOWIN

     ARGUMENTS:
         List:      List is used to specify the sequence of image files to be
                    generated. It can be a list of short integers which
                    explicitly specify the desired images or it can be
                    string variable. If it is a string, it will be parsed
                    into a list of image number first by this method.
                    The user has to insure that the number entered is valid
                    for normal operation of this method.

     KEYWORDS:
         NOWIN:     If specified, only the ASCII files will be created but the
                    xdisplayfile window will not be shown.

     EXAMPLE:
         Example 1 creates the ASCII data files for the image [10,20,30] from the
             'junk2.image', and each file will be displayed automatically.
             The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->ASCII,[10,20,30]

         Example 2 creates the ASCII data files for the images 10, 20 to 30, and
             40 from the 'junk2.image', and no ASCII file will be displayed.

             v2->ASCII,'10,20-30,40',/NOWIN

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::DATATOTEXT

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

     NAME:
    	scan2d::DataToText

     PURPOSE:
           For the current scan2d object, this method creates its tabulated 2D
           image data in a disk file and uses the xdisplayfile command to
           show the contents of the created ASCII file.

           It will try to create the ASCII file in the following order:
           try the data directory first, if failed then try the user starting
           directory, if still failed then try the  user home directory.

     CALLING SEQUENCE:
           Obj->[scan2d::]DataToText, Data, Px, Py, OUTFILE='outfile', /NOWIN

     ARGUMENTS:
         Data:      Optional output variable, gives the output image data array.
         Px:        Optional output variable, gives the X positioner vector.
         Py:        Optional output variable, gives the Y positioner vector.

     KEYWORDS:
         OUTFILE:   If not specified, the default outfile text file name with
                    'view2d_data.txt' will be used.

                    If OUTFILE=1 is specified, then the outfile name will be
                    generated from the image file name suffixed with 4 digit
                    image number.

                    If OUTFILE='anyname' then the outfile name suffixed with
                    '.txt' will be used by the text file.

         NOWIN:     If specified, the xdisplayfile window will not be shown.

     EXAMPLE:
         Following example reads and plots the 135th image from file 'junk2.image'
             and generates an ASCII outfile with file name 'junk2.image.0135'.
             The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->View,135
             v2->datatotext,/OUTFILE

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
          05-15-1998  bkc  Catch error for openw

(See scan2d__define.pro)

## SCAN2D::INDEX

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

     NAME:
    	scan2d::Index

     PURPOSE:
           This method explicitly reads in the whole 2D image file and creates
           the index structure for the image file. It then moves the file pointer
           at the beginning of the file.

           This method is automatcally called by the obj_new creation if the file
           keyword is specified on the object creation.

     CALLING SEQUENCE:
           Obj->[scan2d::]Index, Filename

     ARGUMENTS:
      FILENAME:  Specifies name of the 2D image file (generated by the data catcher)

     KEYWORDS:
         None.

     EXAMPLE:
        Following example shows how to open and index the 2D image file  with
        name 'junk2.image', and the file pointer is positioned at the beginning
        of the file.
        The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d')
             v2->index, 'junk2.image'

        The above example is equivalent to the following example.

             v2 = obj_new('scan2d',file='junk2.image')

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::OPEN

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

     NAME:
    	scan2d::Open

     PURPOSE:
           This method opens the 2D image file according to the data binary type.
           It supports both native binary type and XDR binary type.

    	This method is automatically called by the object creation method.

     CALLING SEQUENCE:
           Obj->[scan2d::]Open, Filename [,Wid]

     ARGUMENTS:
      FILENAME:  Specifies the 2D image file (generated by the data catcher)
      WID:       Optional input, specifies the input droplist widget ID to
                 reflect the binary TYPE in an existing widget program

     KEYWORDS:
         None.

     EXAMPLE:
        Following example shows how to explicitly open the 2D image file  with
        name 'junk2.image', and the file pointer is positioned at the beginning
        of the file.
        The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d')
             v2->open, 'junk2.image'

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::PANIMAGE

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

     NAME:
    	scan2d::panImage

     PURPOSE:
           This method pops up a new PanImage window for a given 2D scan #.
           If the 2D scan # is not specified, then the 2D scanno # will be
           calculated from the current 2D image sequence number.

     CALLING SEQUENCE:
           Obj->[scan2d::]panImage [,Scanno] [,Factor]

     ARGUMENTS:
      Scanno:  Specifies the 2D scan #
      Factor:  Optional input, to specify the panImage window ratio factor

     KEYWORDS:
         None.

     RESTRICTION:
        For a given 2D scan, before calling scan2D::panImage the scan2D::read
        should have been called for one of the detectors in order to
        figure out the dimensions of the image objects.

     EXAMPLE:
        Following example shows how to get the panImage of all detectors
        for 2D scan #2, #3, and # 5 from the 2D image file 'junk2.image'.
        The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->read
    	  v2->panImage,2
    	  v2->panImage,3
    	  v2->panImage,5

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Nov 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::POINT_LUN

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

     NAME:
    	scan2d::Point_lun

     PURPOSE:
           The method moves the 2D image file pointer to the end of the
           specified record.

     CALLING SEQUENCE:
           Obj->[scan2d::]Point_lun, SEQNO

     ARGUMENTS:
         SEQNO:   Specifies the zero based image sequence number.

     KEYWORDS:
         None.

     EXAMPLE:
        Following example moves the file pointer to the end of the 10th record
        of the 2D image file 'junk2.image'.
        The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->point_lun,10

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
          05-15-1998  bkc  Add message dialog if illegal number entered

(See scan2d__define.pro)

## SCAN2D::PRINT

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

     NAME:
    	scan2d::Print

     PURPOSE:
           This method prints the current key variables for the object structure.
           It prints the starting and data directory, image filename, total #
           of 2D scan, totol # of images, current 2D Scan #, detector #, and
           image seq # at current image pointer, and the image seq array to
           corresponding to detector 1.

     CALLING SEQUENCE:
           Obj->[scan2d::]Print

     ARGUMENTS:
         None.

     KEYWORDS:
         None.

     EXAMPLE:
        Following example shows current key variables of the object v2.

             v2->print

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::READ

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

     NAME:
    	scan2d::Read

     PURPOSE:
           This method reads in one set of image record from the current file
           pointer.

     CALLING SEQUENCE:
           Obj->[scan2d::]Read, /VIEW, WIDTH=width, HEIGHT=height, $
              DETECTOR=detector, SCANNO_2D=scanno_2d, X=x, Y=y, IM=im

     ARGUMENTS:
         None.

     KEYWORDS:
         VIEW:     If specified, the read in 2D image will also be displayed on the
                   plot window.
         X:        If specified, it returns the X vector values.
         Y:        If specified, it returns the Y vector values.
         IM:       If specified, it returns the 2D IM array values.
         WIDTH:    It specified, it returns the X vector size.
         HEIGHT:   It specified, it returns the Y vector size.
         SCANNO_2D:If specified, it returns the corresponding 2D scan number.
         DETECTOR: If specified, it returns the detector number for the image.

     EXAMPLE:
        Following example reads the 136th image from the input image file and also
        plot the 2D image.
        The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->point_lun,135
             v2->read,/view

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::SAVE

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

     NAME:
    	scan2d::Save

     PURPOSE:
           This method allows the user read the next image record and save the
           data to a save file. The saved file can be restored by the restore
           command. Two type of variables can be saved by this command:
           either save the whole object or just save the x,y,im arrays.
           The data saved will be in XDR format.

     CALLING SEQUENCE:
           Obj->[scan2d::]Save, No, FILE=file, /VERBOSE, /OBJECT

     ARGUMENTS:
         No       Specifies the desired sequence number of the image record
                  to be read. If not specified then the next record is assumed.

     KEYWORDS:
         FILE:    Specifies the save file name, it defaults to 'idlsave.dat'.
         VERBOSE: If specified, the verbose mode is assumed, the variables
                  saved will be listed.
         OBJECT:  If specified, the complete data object is saved. Otherwise
                  only the NO, X, Y, IM variables are saved for the record.

     EXAMPLE:
        Example 1 - Saves the X,Y,IM arrays for the 135th record
        in 'junk2.image.s0135', also list the variables saved.
        The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->save,135,file='junk2.image.s0135',/verbose

        Example 2 - Saves all the variables for the 135th record
        in 'junk2.image.s0135', also list the variables saved

             v2->save,135,file='junk2.image.s0135',/verbose,/object

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::VALID

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

     NAME:
    	scan2d::Valid

     PURPOSE:
           This method checks whether the input image no is valid.

     CALLING SEQUENCE:
           Obj->[scan2d::]Valid,No,CODE=code

     ARGUMENTS:
         No       Specifies the image record number.

     KEYWORDS:
         CODE:    Returns the return code, 0 if valid, -1 if invalid.

     EXAMPLE:
         Following example checks whether image number 130 is a valid request
         for the 'junk2.image' file
         The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->Valid,130,code=code

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	xx-xx-xxxx      comment

(See scan2d__define.pro)

## SCAN2D::VIEW

[Previous Routine] [List of Routines]

     NAME:
    	scan2d::View

     PURPOSE:
           This method lets the user view any valid 2D image from the 2D data
           catcher image file.

           It also automatically pops up the flexible 2D plot package, it allows
           the user view 2D image in TV, SURFACE, CONTOUR, and SHADE_SURF and
           generated the printer copy from the PS file, idl.ps, if desired.

     CALLING SEQUENCE:
           Obj->[scan2d::]View, No, SCANNO=scanno, DETECTOR=detector, NOREAD=noread

     ARGUMENTS:
         No       Specifies the sequence number of the image record.

     KEYWORDS:
         SCANNO:    It specifies the 2D scan number. If specified,it ignore the
                    'No' specification. Valid SCANNO range:
                    [1 - self.scanno_2d_last]
         DETECTOR:  It specifies the desired detector number from the 2D scan.
                    If not specified, and SCANNO is given, detector 1 is assumed.
         NOREAD:    If specified, no reading from the file pointer is done,
                    only plot the current object is performed.
         NOPLOT:    If specified, no 2D flexible plotting package available.

     EXAMPLE:
         Example 1 reads and plots the 135th image from the 'junk2.image'
             The object v2 need to be defined only if it is not yet defined.

             v2 = obj_new('scan2d',file='junk2.image')
             v2->View,135

         Example 2 reads and plots the image of detector 7 of the 21th 2D scan
             from the 'junk2.image' file

             v2->View,scanno=21,detector=7

     MODIFICATION HISTORY:
     	Written by:	Ben-chin Cha, Jan 19, 1998.
    	12-16-1998      Add flexible 2D TV, SURFACE, CONTOUR,SHADE_SURF
                           plot option

(See scan2d__define.pro)