----- file created by makedoc on: Thu Nov  5 15:14:56 2009
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/mirsur.pro -----

 NAME:
	MIRSUR

 PURPOSE:
	Plots the surface of a mirror starting from the 
	SHADOW file (i.e. mirr.xx)

 CATEGORY:
	SHADOW utilities.

 CALLING SEQUENCE:
	MIRSUR,'mirr.01'

 INPUTS:
	input: 	a SHADOW file or idl structure containing the SHADOW
		data. It can also be a fltarr(3,npts) with the x,y,z
		coordinates of the surface points.

 OPTIONAL INPUTS:
	z,x,y	The idl variables to strore the (output) surface for
		additional processing.
	
 KEYWORD PARAMETERS:
	QUINTIC: it is passed to the TRIGRID function:
	        If QUINTIC is set, smooth interpolation is per-
	        formed using Akima's quintic polynomials from "A 
	        Method of Bivariate Interpolation and Smooth Surface 
	        Fitting for Irregularly Distributed Data Points" in 
	        ACM Transactions on Mathematical Software, 4, 148-
	        159. The default method is linear interpolation.
	SHOW:	When set, shows the triangulation before the mirror
		surface.
	GS: 	passed to TRIGRID:
		If present, GS should be a two-element vector 
		[XS, YS], where XS is the horizontal spacing between 
	        grid points and YS is the vertical spacing. The 
	        default is based on the extents of X and Y. If the 
	        grid starts at X value x0 and ends at x1,then the 
	        horizontal spacing is
	LIMITS=[min_colx,min_coly,max_coly,max_coly] optinal limits
		for the mirror (default=min and max from the SHADOW
		data)
	NXPOINTS = number of points in x (default=21)
	NYPOINTS = number of points in y (default=51)
	EXTRAPOLATE = passed to TRIGRID:
        	This keyword sets the quintic interpolation 
	        mode. TRIGRID extrapolates to grid points outside 
	        the triangulation if this keyword is assigned to the 
	        array of boundary node indices returned by the 
	        optional parameter B of the TRIANGULATE procedure. 
	        The extrapolation is not smooth, but should give 
	        acceptable results in most cases.
	INVERT: When set, switch the X and Y columns
	CUTPOINTS=n the number of rays used for the plot (default=# of
		rays in the SHADOW input file)
 OUTPUTS:
	A grafic.

 OPTIONAL OUTPUTS:
	The surface data in the (optional) input variables x,y and z.

 COMMON BLOCKS:

 SIDE EFFECTS:
	this entry.

 RESTRICTIONS:
	It may be quite time  consuming. The graphic output may not be
	very well looking.

 PROCEDURE:
	As the mirror file of SHADOW contains the (x,y,z) coordinates
	for all the rays, and these points are irregularly spread over
	the mirror surface, a triangulation is necessary. For such a 
	purpose we use the TRIGRID and TRIANGULATE idl's routines.

 EXAMPLE:
	SURMIR,'mirr.01',z,x,y
	surface,z,x,y	; to repeat the plot

 MODIFICATION HISTORY:
 	Written by:	M. Sanchez del Rio. ESRF. May 1994
		94/07/08 MSR extends the input to a fltarr(3,*)
		96/01/30 MSR display 3D triangulation when /show is set.

