----- file created by makedoc on: Fri May 31 15:22:23 2013
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/readsh.pro -----

 NAME:
	READSH
 PURPOSE:
	to load in an IDL structure a SHADOW  file. It can also be
	used to write a new idl/shadow structure with fewer rays by
	using the NOLOST keyword, or to append data into a shadow/
	idl structure by using the APPEND keyword.
 CATEGORY:
	SHADOW's utilities.
 CALLING SEQUENCE:

	Result = readsh('shadow_file_name')

	with that, IDL stores in a structure named Result (or whatever you
	want) the shadow_file_name (for instance, begin.dat).

   For help, type

	HELP,/ST,Result
 INPUTS:
	SHADOW_FILE_NAME can be either: 
           i) name of the input file 
           ii) idl/shadow structure
           iii) a "BEAM" object
 KEYWORD PARAMETERS:
	NFILES = number of files to be read. Optionally READSH can read
	a number of files from an iterative shadow run. These files must
	have the extension -1,-2...-n (i.e.  star.01-1,star.01-2,star.01-3)
	where - acts as a "seperator". The separator can be any sign 
	defined in the SEPARATOR keyword
	SEPARATOR = sign that acts a separator between the file name and
	the run number (default='-')
       NOLOST = consider losses in the returned shadow/idl structure
            0 all rays (default option)
            1 exclude losses;
            2 only losses;
       PARAXIAL = a value to "filter" paraxial rays. 
            Paraxial rays have small Numerical Aperture (NA), marginal rays
            have large NA. This option permits to read only paraxial or
            marginal rays for quick testing optical systems. Shadow's col21
            (angle from Y axis) is a good approximation to NA. The paraxial
            keyword value is used to extract the fractions of the rays 
            that have smaller or larger value of col21. For example: 
            a = readsh('star.01',PARAXIAL=0.1) will read only the rays
                with col21 values LT 0.1*max(col21), i.e., paraxial rays  
            a = readsh('star.01',PARAXIAL=-0.9) will read only the rays.
                with col21 values GT 0.9*max(col21), i.e., marginal rays.
       APPEND Set this keyword to a shadow file or idl shadow structure
	     to be appended. Thus Result=InFile+AppendedFile.
	GROUP The parent id for the caller widget (used to positioning
		error and information windows).
       VERBOSE Set this keyword to print some info (Default: verbose=1)
	
 OUTPUTS:
	A1 an IDL structure 
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None
 RESTRICTIONS:
	None.
 PROCEDURE:
 	
 EXAMPLES:
	1) read a shadow file and write it into a shadow/idl structure:
		a=readsh('begin.dat')
	2) same but using only good rays:
		a=readsh('star.01',/nolost)
	3) save 8 files (star.01-1, ..., star.01-8) in a shadow/idl str:
		a=readsh('star.01',nfiles=8)
	4) remove the bad rays from a shadow/idl structure
		a=readsh(a,/nolost)
	5) read the file 'star.05' five times and place the result in a:
		a=1 ; initialize variable
		for i=1,5 do a=readsh('star.05', append=a)
 MODIFICATION HISTORY:
	M. Sanchez del Rio. ESRF. Grenoble, May 1991
        92-07-09 MSR includes a 'spawn' call in order to run sh-idl from idl
        92-10-17 MSR includes NFILES option
        93-07-09 MSR includes SEPARATOR keyword
        94-06-09 MSR if the input is not a file, but a SHADOW-IDL
		structure, then returns this (the same) structure. This check 
		is done here, and can therefore be removed from the other 
		routines.
        94-11-29 MSR adds the /NOLINK flag, which is passed to getrays
        95-03-03 MSR removes the /NOLINK flag, unnecessary with the 
		new getrays function
	 96-06-18 MSR adds NOLOST keyword, updates doc, small changes.
	 98-04-02 MSR adds GROUP keyword.
	 2009-01-12 MSR adds VERBOSE keyword.
	 2011-09-19 srio@esrf.eu added "BEAM" object as possible input.

