OAA_LIB-utilities Library Help

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Tue May 15 16:15:50 2007.


List of Routines


Routine Descriptions

[Next Routine] [List of Routines]

 NAME:

	INDDIM



 PURPOSE:

 	Format change array index from linear to 2D dimensional



 CATEGORY:

	Array routine



 CALLING SEQUENCE:

 	vect = indimm(index, dim)



 INPUTS:

 	index: index linear vector

	dim: dim 2D square (only scalar)



 OUTPUTS:

	vect: array with 2D coordinates



 KEYWORDS:

	TRANSPOSE: give the vectors in a tranpsose way



 MODIFICATION HISTORY:

 	Written by:	Xompero Marco, Mar 2003.

(See utilities\inddim.pro)


AIR_RELATIVE_PERMITTIVITY

[Previous Routine] [Next Routine] [List of Routines]
 eps_r = air_relative_permittivity(h, T, P)

 the function returns the electric relative permittivity
 of the air as a function of relative humidity (h, 0 to 1),
 temperature (T [K]) and pressure (P [Pa])

 HISTORY

 Jul 2006 written by A. Riccardi, INAF-OAA

(See utilities\air_relative_permittivity.pro)


AMAX

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

 same as max, but it returns the N-dimensional subscript
 in Max_Subscript, where N is the number of dimensions of
 the input array

 MODIFICATON HISTORY

    Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                riccardi@arcetri.astro.it

(See utilities\amax.pro)


AMIN

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

 same as min, but it returns the N-dimensional subscript
 in Min_Subscript, where N is the number of dimensions of
 the input array

 MODIFICATON HISTORY

    Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                riccardi@arcetri.astro.it

(See utilities\amin.pro)


ANIMATION

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

 show an animation of the frames stored in the input array.

 animation, cube[, /VERB][, SHOWF=velue][, SSHOWF=velue][, MINI=value][, MAXI=value] $
                [, PIXELS=velue][, DEC=value]

 cube:   3-dim real array[xdim,ydim,nframes]

 SHOWF:  integer, scalar. Number of frames to show in the anmations
 SSHOWF: integer, scalar. Starting frame to show
 MINI:   real scalar. Minimum value used to scale the colors
 MAXI:   real scalar. Maximum value used to scale the colors
 PIXELS: integer, scalar. Zoom factor for the frame display
 DEC:    integer, scalar. Decimation of the frames in cube to diaplay

 by G. Brusa, Osservatorio Astrofisico di Arcetri (OAA)

(See utilities\animation.pro)


BISECTION

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

 apply the bisection method to find a zero of the function func_name in
 the interval start_interval

 res=bisection(start_interval, func_name[, TOL=value])

 start_interval: real 2-element vector. Interval containing the zero of the function
 func_name:      string, scalar. Name of the function having the zero in start_interval
 
 TOL:            real scalar. Tollerance of the solution. Default value=1d-6.

 MODIFICATON HISTORY

    Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                riccardi@arcetri.astro.it

(See utilities\bisection.pro)


CIRCUS_MAX

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

 This function returns the center and the radius of the smallest
 circle containing all the non-zero points in the 2D array mask.
 Center and radius are returned in pixel coordinates of the x-axis.

 ret = circus_max(mask [, ASPECT_RATIO=aspect][, /DISPLAY])

 ASPECT_RATIO:  deltaY/deltaX. Set it to the right value if x-pixels
                and y-pixels have not the same linear scale. Aspect
                ratio is set to 1 by default.
 DISPLAY:       Set it to display the graphical result of the fitting.

 ret = [x0,y0,Radius], where:

 Radius is the cirle radius in pixel units of x-axis
 x0 is the x coordinate in pixel units of x-axis
 y0 is the y coordinate in pixel units of y-axis


 HISTORY

 Apr 2004: written by M. Xompero

 14 Apr 2004: A. Riccardi.
  *Unused CENTER keyword removed.
  *help fixed

(See utilities\circus_max.pro)


COMPLEMENT

[Previous Routine] [Next Routine] [List of Routines]
 not_included = complement(list, larger_list, out_list, count)

 return in out_list the complement of list in the larger_list.
 list must be included in larger_list. If it is not included
 not_included=1B (=0B otherwise).
 count: # of elements in out_list. If the complement is empty
 the out_list is undefined (i.e. n_elements(out_list)=0) and count=0L

 if the range of the union between list and larger_list is larger then 256*1025
 the routine could be slow (depending on the length of larger_list)

 MODIFICATON HISTORY

    Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                riccardi@arcetri.astro.it

(See utilities\complement.pro)


COMP_COLORS

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

 returns a vector of n RGB (long integer) values of different colors

  colors = comp_colors(n)

 MODIFICATON HISTORY

    Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY
                riccardi@arcetri.astro.it

(See utilities\comp_colors.pro)


CONV2BIN

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

 converts data in strings containing their binary representation

 str = conv2bin(data)

 str has the same dimentions as data. Dcomplex, objref, pointers and
 structures are not handled.

 HISTORY
   31 May 2004, written by A. Riccardi (AR)
   10 Aug 2004, AR
     bug with no scalar input fixed.

(See utilities\conv2bin.pro)


CONV2HEX

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

 converts data in strings containing their hexadecimal representation

 str = conv2hex(data)

 str has the same dimentions as data. Dcomplex, objref, pointers and
 structures are not handled.

 HISTORY
   31 May 2004, written by A. Riccardi

(See utilities\conv2hex.pro)


CREBIN

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

 The function is a wrapper of the REBIN function that is also able to manage
 complex and dcomplex variables. If the array is complex/dcomplex, CREBIN returns a
 complex/dcomplex array having a rebinned real and imaginary part. The input array
 cannot have more then 8 dimensions.

 SYNTAX

 Same as REBIN

 HISTORY

 24 Mar 2002, written by A. Riccardi
 Osservatorio Astrofisico di Arcetri, ITALY
 riccardi@arcetri.astro.it

(See utilities\crebin.pro)


CW_FILENAME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       CW_FILENAME

 PURPOSE:
       

 CATEGORY:
	Compound widgets.

 CALLING SEQUENCE:
	widget = CW_FILENAME(parent)

 INPUTS:
       PARENT - The ID of the parent widget.

 KEYWORD PARAMETERS:
	UVALUE - Supplies the user value for the widget.
       VALUE  - Supplies the initial filename (scalar string)

       TITLE        -+
       ALL_EVENTS    |
       FRAME         |
       FIELDFONT     +--- See cw_field function
       FONT          |
       NOEDIT        |
       RETURN_EVENTS |
       XSIZE        -+

       PATH         -+
       FILTER        +--- See Dialog_pickfile function
       FIX_FILTER    |
       MUST_EXIST   -+

       GET_PATH - if set only directories can be input


 OUTPUTS:
       The ID of the created widget is returned.

 PROCEDURE:
	WIDGET_CONTROL, id, SET_VALUE=value can be used to change the
		current value displayed by the widget.

	WIDGET_CONTROL, id, GET_VALUE=var can be used to obtain the current
		value displayed by the widget.

 MODIFICATION HISTORY:
       April 1999, written by A. Riccardi 

(See utilities\cw_filename.pro)


DERIV_2D

[Previous Routine] [Next Routine] [List of Routines]
 DERIV_2D
 
 INPUT:
 x:	x-vector. N-elements.
 y:	y-vector. M-elements
 func:	NxM-elements matrix to derive

 OUTPUT:
 de_x:	x-derivative matrix
 de_y: y-derivative matrix

 MODIFICATION HISTORY:
   Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY

(See utilities\deriv_2d.pro)


DEW_POINT

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

 computes the dew and frost point

 t_point = dew_point(vp [, /FROST][, /KELVIN])

 vp:      float scalar or vector. Vapour pressure in hPa
          vp = vp*(hr/100.0), where vp is saturation vapour
          pressure in hPa and hr is relative humidity in
          percentage (0-100)
 KEYWORDS:
   FROST: if it is set, the frost point is returned. Default is
          dew point.

   KELVIN: if it is set, the dew/frost point is returned in
           kelvin. Defaults is Celtius degrees.

 HISTORY
   2002: written by G. Brusa, CAAO Steward Obs., USA
         gbrusa@as.arizona.edu

(See utilities\dew_point.pro)


DIAGONAL_MATRIX

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

  ret = diagonal_matrix(diag)

  Returns a diagonal matrix having the same data type of diag and
  diag as diagonal elements.

 21 Oct, 2002 Written by A. Riccardi, INAF-Osservatorio Astrofisico di Arcetri (Italy)
              riccardi@arcetri.astro.it

(See utilities\diagonal_matrix.pro)


DUAL_PLOT

[Previous Routine] [Next Routine] [List of Routines]
 it draws a plot with different left and right y-scales. If X2TOP is set, then
 different bottom and top x scales are plotted.

(See utilities\dual_plot.pro)


EPSILON

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
       EPSILON 
 
 PURPOSE: 
       This function returns the machine precision.
 
 CATEGORY: 
       Utilities. 
 
 CALLING SEQUENCE: 

       Result = EPSILON() 
 
 KEYWORD PARAMETERS: 
       DOUBLE: If set calculates double type machine precision. Float
               otherwise.
 
 OUTPUTS: 
       This function returns the machine precision: the smallest floating
       point eps that: 1. + eps ne 1. (1.d + eps ne 1.d if DOUBLE is set).
 
 EXAMPLE: 
       Test if matrix C have zero elements using a tollerance.

           Eps = EPSILON()
           Toll = MAX(ABS(C)) * Eps
           IF (WHERE((C LT Toll) AND (C GT -Toll)))(0) ne -1 THEN $
               PRINT, 'C have zero-stimated elements'

 
 MODIFICATION HISTORY: 
       Written by:     A. Riccardi; April, 1995

(See utilities\epsilon.pro)


EQUALIZE_LIMITS

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

  Computes the range including most of the values of the input array or vector.
  It is usefull to display images with spikes to filter out.
 
  The function returns a range eq_range=[r1,r2] of image values for which:
  the number of image values with values less then r1 is lower then LOW_THESHOLD
  the number of image values with values less then r2 is lower then HIGH_THESHOLD

  eq_range = equalize_limits(image[, LOW_THRESHOLD=value][, HIGH_THRESHOLD=value] $
                             [, BINSIZE=value])

  default values:
  LOW_THRESHOLD=0.01
  HIGH_THRESHOLD=0.99
  BINSIZE=(max_image_value-min_image_value)/1000

 MODIFICATION HISTORY

 Written by: A. Riccardi, Osservatorio di Astrofisico di Arcetri, ITALY
             riccardi@arcetri.astro.it

(See utilities\equalize_limits.pro)


EXTRACT_DIAGONAL

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

 Result = EXTRACT_DIAGONAL(A)

 INPUT
 A:	square matrix

 OUTPUT
 vector containg the diagonal elements of A matrix

 MODIFICATION HISTORY

 Written by: A. Riccardi, Osservatorio Astrofisico di Arcetri, ITALY

(See utilities\extract_diagonal.pro)


FFT1

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

 perform FFT for real data, providing the correct scaling
 and PSD (pixels^2/Hz)

 HISTORY:
    ?? 19??  Written by Guido Brusa, Osservatorio Astrofisico di Arcetri
             brusa@arcetri.astro.it


(See utilities\fft1.pro)


FIND_IN_PATH

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

 The function searches a file in all the directories specified
 in the !PATH system variable

 SYNTAX

   res = find_in_path(filename, /VERBOSE)

 INPUTS

   filename:  scalar string. File name to search for. only the
              filename without any path. Wild characters are allowed.

 OUTPUT

   res:       empty string ("") if no file has been found. Vector of
              strings containing the results of the search if
              successful.

 HISTORY

   22 Mar 2002:  Written by A. Riccardi
                 Osservatorio Astrofisico di Arcetri, Italy
                 riccardi@arcetri.astro.it

(See utilities\find_in_path.pro)


FIND_TAG

[Previous Routine] [Next Routine] [List of Routines]
  NAME:
   FIND_TAG

  PURPOSE:
   This routine helps you to find a forgetten field into a large structure.

  USAGE:
   FIND_TAG, regexp, struct, strout

  INPUT:
   regexp: string. Regular expression special chacacters are permitted. (See IDL help)
   struct: struct. This is the place where we are looking for the tag.

  OUTPUT:
   strout: (optional) string array. Result of the matching. If nothing is found, 
            it return an empty string. If the struct parameter is wrong, it's set to
            an integer value -1.

  NOTE:
   None.
  
  PACKAGE:
   OAA_LIB/UTILITIES

  HISTORY:

  07 Dec 2004
   Created by Marco Xompero (MX)
   marco@arcetri.astro.it

(See utilities\find_tag.pro)


FP_OPEN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	FP_OPEN

 PURPOSE:
	Open the communication with a field point device.

 CATEGORY:
	Communication initialization.

 CALLING SEQUENCE:
	err =  fp_open(com_port_str, fp_config, VERBOSE=verb, PORT_ID=port_id)

 INPUTS:
	com_port_str: input structure.
					If the device is driven by socket, it needs two fields:
								- ip_address: 	ipaddress of the device
								- port:			port number
					If the device is a COM port, it's need only the string name of the port.
 OUTPUT:
	fp_config: 	configuration structure

 KEYWORDS:
	VERBOSE: prints more informations.
	PORT_ID: return the port_id opened.

 PROCEDURE:
	The procedure collects the configuration data of the field point device and return all in the structure fp_config.
 	 To close a open connection with the field point, just have a "free_lun" of port_id.
 	 If there is no port_id keyword specified, the connection is closed at the and of the routine automatically.

 MODIFICATION HISTORY:

	Created by Armando Riccardi on 2003

	Modified 2003/07/16 busoni
	 Added control if Empty Base is present
	 Added section for FP-AI-100

	Modified 2004/01/16 riccardi
	 Socket communication is now supported thru serial<->TCP/IP converter
 	 Added VERBOSE and PORT_ID keywords
 	 Changes in case of trapped error (an error code is returned without stopping)
 	08 Apr 2004 M.Xompero
 	 Arg_present test fixed

(See utilities\fp_open.pro)


FP_READ

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	FP_READ

 PURPOSE:
	READ the field point data.

 CATEGORY:
	Data acquisition.

 CALLING SEQUENCE:
	err = fp_read (fp_setting, module_idx, channel_list, UNIT=unit, VERBOSE=verb, $
						PORT_ID=port_id , ERROR=return_error, FP_ERROR=err_resp)

 INPUTS:
 	fp_setting:

 OUTPUT:
	fp_config: 	configuration structure
	module_idx: int index of the module fp to read
	channel_list: int list of the channels to read 

 KEYWORDS:
	VERBOSE: prints more informations.
	UNIT:	return measur unit of the data read.
	PORT_ID: port_id on which to read the data.
	ERROR: error code return
	FP_ERROR: field point error string

 PROCEDURE:
	The procedure read the data from the field point device by fp_send_command.pro

 MODIFICATION HISTORY:

	Created by Armando Riccardi on 2003

	16 Jan 2004: A. Riccardi
  	Added PORT_ID, ERROR and FP_ERROR keywords.
     In case of error the function returns 0 and
     fills ERROR with a error code. FP_ERROR
     returns the value contained in the fp_send_command
     ERROR_RESP keyword.
; 08 Apr 2004: M. Xompero
		Arg_present test fixed

(See utilities\fp_read.pro)


FP_SEND_COMMAND

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	FP_SEND_COMMAND

 PURPOSE:
	Send a command to the Field Point device.

 CATEGORY:
	Device driver.

 CALLING SEQUENCE:
	err = fp_send_command (com_data, command_in, resp, N_ITERATIONS=n_iter $
                        , ERROR_RESP=err_resp, VERBOSE=verb, PORT_ID=port_id)

 INPUTS:
	com_data: input structure.
					If the device is driven by socket, it needs two fields:
								- ip_address: 	ipaddress of the device
								- port:			port number
					If the device is a COM port, it's need only the string name of the port.
	command_in: command to send

 OUTPUT:
	resp:		data collected

 KEYWORDS:
	VERBOSE: prints more informations.
	PORT_ID: return the port_id opened.
	ERROR_RESP: error code response
	N_ITERATIONS: return the iteration made for an exact checksum (min 1)

 PROCEDURE:
	The procedure send the command to the Field Point davice and return the data if they are corrects.

 MODIFICATION HISTORY:

	Created by Armando Riccardi on 2003

 	16 Jan 2004: A. Riccardi
 		Socket communication is now supported thru serial<->TCP/IP converter
 		Added VERBOSE and PORT_ID keywords
 
 	08 Apr 2004: M. Xompero
 		Arg_present test fixed

(See utilities\fp_send_command.pro)


G_HYPERG[1]

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
       G_HYPERG
 
 PURPOSE: 
       Evaluates generalized hypergeometric function. 
 
 CATEGORY: 
       Special function. 
 
 CALLING SEQUENCE: 

       Result = G_HYPERG(Alpha, Beta, Z) 
 
 INPUTS:
       Alpha: 	real or double vector.

		Beta:	real or double vector.

		Z:		float, double or complex. Evaluating point.
        
 KEYWORD PARAMETERS: 
       eps:	float. Fractional precision requested. If it isn't set
				then eps=1.e-6 is assumed.
 
 OUTPUTS:
       This function returns:

		Sum(n=0 to N)((Alpha)n/(Beta)n*z^n/n!)

		where:
		(Alpha)n = (Alpha(0))n*...*(Alpha(P-1))n
		(a)n = a*(a+1)*...*(a+n-1)
		P=n_elements(Alpha)
		(same as Beta)

		N max value of n in the sum. Truncation of the series.
		N is stimated from eps
 
 RESTRICTIONS: 
       P=n_elements(Alpha)
		Q=n_elements(Beta)
		Generalized hipergeometric series converges always if P<=Q,
		conerges for abs(Z)<1. if P=Q+1 and diverges for all z not equal
		to zero id P>Q+1.
		If P=Q+1, s=Re(total(Alpha)-total(Beta)) then the series converges
		for all abs(Z)=1 if s<0; it converges for all abs(Z)=1 and Z not eq 1
		if 0<=s<1 and diverges if s>=1.
 
 EXAMPLE: 
       
 
 MODIFICATION HISTORY: 
       Written by:     A. Riccardi; July, 1995. 

(See utilities\g_hyperg.pro)


G_HYPERG[2]

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
       G_HYPERG
 
 PURPOSE: 
       Evaluates generalized hypergeometric function. 
 
 CATEGORY: 
       Special function. 
 
 CALLING SEQUENCE: 

       Result = G_HYPERG(Alpha, Beta, Z) 
 
 INPUTS:
       Alpha: 	real or double vector.

		Beta:	real or double vector.

		Z:		float, double or complex. Evaluating point.
        
 KEYWORD PARAMETERS: 
       eps:	float. Fractional precision requested. If it isn't set
				then eps=1.e-6 is assumed.
 
 OUTPUTS:
       This function returns:

		Sum(n=0 to N)((Alpha)n/(Beta)n*z^n/n!)

		where:
		(Alpha)n = (Alpha(0))n*...*(Alpha(P-1))n
		(a)n = a*(a+1)*...*(a+n-1)
		P=n_elements(Alpha)
		(same as Beta)

		N max value of n in the sum. Truncation of the series.
		N is stimated from eps
 
 RESTRICTIONS: 
       P=n_elements(Alpha)
		Q=n_elements(Beta)
		Generalized hipergeometric series converges always if P<=Q,
		conerges for abs(Z)<1. if P=Q+1 and diverges for all z not equal
		to zero id P>Q+1.
		If P=Q+1, s=Re(total(Alpha)-total(Beta)) then the series converges
		for all abs(Z)=1 if s<0; it converges for all abs(Z)=1 and Z not eq 1
		if 0<=s<1 and diverges if s>=1.
 
 EXAMPLE: 
       
 
 MODIFICATION HISTORY: 
       Written by:     A. Riccardi; July, 1995. 

(See utilities\test_g_hyperg.pro)


IDX2RGB

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

   the function returns the RGB long numbers corresponding to the 
   indexes of the current color table given by idx

 rgbcodes = idx2rgb(idx, /SCALE)

   if SCALE keyword is set, idx is scaled to fit the 0-255 range.

(See utilities\idx2rgb.pro)


IDX_ARRAY

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

  The function convert a one-dimensional indexes of a
  N-dimensional array (returned by the where function,
  as instance) in vectors containinig the corresponding
  collections of N-dimensional indexes

   idx_vec = idx_array(idx, array)
  or
   idx_vec = idx_array(idx, size(array), /SIZE_OF_ARRAY)

  	idx:   input. non floating point M-elemnts vector.
          one-dimensional index of array[*]
   array: input. N-dimensional array.

   index_vec: output, long NxM array.

  EXAMPLE:

 IDL> a=fltarr(10,5,6)
 IDL> a[7,2:3,5]=1
 IDL> idx=where(a eq 1)
 IDL> print, idx
          277         287
 IDL> print, idx_array(idx, a)
 IDL> print, idx_array(idx, a)
            7           2           5
            7           3           5
 IDL> print, idx_array(idx, size(a), /SIZE_OF_ARRAY)
            7           2           5
            7           3           5

 HISTORY:
    04 Dic 2002. Written by A. Riccardi. INAF, OAA, Italy
                 riccardi@arcetri.astro.it

(See utilities\idx_array.pro)


IMAGE_AR

[Previous Routine] [Next Routine] [List of Routines]
resample an image sampled with a different step in y and x axis to the same step.
usage : resampled_image=image_ar(aspect_ratio,image)
			aspect_ratio is the image aspect ratio

(See utilities\image_ar.pro)


IMAGE_SHOW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   IMAGE_SHOW

 PURPOSE:
   Display an image.

 CATEGORY:
   General graphics.

 CALLING SEQUENCE:

 image_show, input, x_vec, y_vec, NX=nx, NY=ny, XAXIS=xax, YAXIS=yax $
    , WINDOW_SCALE = window_scale, ASPECT = aspect, MAX_VALUE = max_value $
    , MIN_VALUE = min_value, SHOW_BAR = show_bar, INV = inv, POSIZ = posiz $
    , DIG = dig, INTERP=interp, _EXTRA=plot_keywords, SCALE = scale $
    , BAR_TITLE=ytitle_bar, NOERASE=noerase, NO_GT=no_gt, NO_LT=no_lt $
    , TITLE=title, YTITLE=ytitle, YTICKF_BAR=ytickf_bar, YSTYLE=ystyle $
    , XSTYLE=xstyle, COL_INVERT=col_invert, LOG=log, XBAR=xbar $
    , CONTOUR=do_contour, NLEV = nlev ,PERCENT = percent, EQUALIZE=equalize

 INPUTS:
   input:  If x_vec and y_vec are not present, "input" is the two-dimensional array
           to display. If x_vec and y_vec are present, "input" is a vector of values
           of the map to dispaly in the corresponding irregular grid defined by x_vec
           and y_vec.

   x_vec, y_vec  cannot be used when "input" is a two-dimensional array. If they are
           defined, they have to be vectors with the same size as "input". In the last
           case TRIGRID is used to obtain a regular gridded two-dimensional array
           to display.

 KEYWORD PARAMETERS:

   NX,NY:  Used only when three parameters are passed. Same keywords as TRIGRID.

	XAXIS:	Two elements array containing minimum and maximum x-axis values

	YAXIS:	Two elements array containing minimum and maximum y-axis values

   WINDOW_SCALE:   Set this keyword to scale the window size to the image size.
       Otherwise, the image size is scaled to the window size.
       This keyword is ignored when outputting to devices with
       scalable pixels (e.g., PostScript).

   ASPECT: Set this keyword to requested image's aspect ratio (y/x).
       1 implies square pixels.  If WINDOW_SCALE is set, the
       aspect ratio is automatically retained.

   MAX_VALUE: Set this keyword to change the limit of the lookup table

   MIN_VALUE: Set this keyword to change the limit of the lookup table

   SHOW_BAR: Set this keyword to show the color lookup table

   INV: Set this keyword to invert the lookup table (can be used to
        reduce the amount of toner/ink used when printing certain images)

   POSIZ: Returns the device coordinates of the displayed image
          (can be used to overplot something on the main image)

   DIG: Sets the number of digits used to label the ticks of the lookup table
           (otherwise set automatically)

   INTERP: Uses an interpolation method as described in the routine
           poly_2d

	_EXTRA: Allows to use the general keywords used with the plot routine to
           insert titles and other features (see help on plot).

   SCALE:  Scales x and y axis (not used on XAXIS or YAXIS values)

	BAR_TITLE: Allows to insert a title over the color bar

   XBAR:    0.0 < xbar < 1.0, normalized starting point of the color bar
            in the horizontal direction of the plotting window.
            0.75 by default

   NOERASE: If set, the window or page is not erased before plotting

   YTICKF_BAR: tick format strin of the color bar labels

   COL_INVERT: invert the background and foreground colors

   LOG:    if set, display the array values using logarithmic scale

   CONTOUR:  if set, overplot a contour plot on the array map

   NLEV:   number of levels to use in the contour plot (10 by default)

   PERCENT: if set, contour label are expressed in percent value of
             the plotting range

   EQUALIZE: if set, the function equalize_limit is called to compute
             the optimal color cuts. MIN_VALUE and MAX_VALUE keywords
             override the EQUALIZE setting. In order to restrict the
             computation of the equalized limits over a subset of data,
             set this keyword to the corresponding list of elements to use.

 OUTPUTS:
   No explicit outputs.

 COMMON BLOCKS:
   None.

 SIDE EFFECTS:
   The currently selected display is affected.

 RESTRICTIONS:
   None.

 PROCEDURE:
   If the device has scalable pixels, then the image is written over
   the plot window.

 MODIFICATION HISTORY:
   DMS, May, 1988. (image_cont)
	several times. G. Brusa Zappellini (Osservatorio Astrofisico di Arcetri)
                  brusa@arcetri.astro.it.
   Mar 2002. A. Riccardi (OAA) riccardi@arcetri.astro.it
             Keywords CONTOUR, NLEV, PERCENT added.
             Computation of the optimal value for DIG if is not not passed.
   Mar 2002. AR, Implemented the possibility to pass an irregularly gridded set of points.
   Dic 2002. GBZ, added the XBAR keyword
   Dic 2002. AR, Error in the computation of the optimal value of dig fixed.
                 Image x-size is computed as 95% of xbar.
                 Definition of NX and NY keyword fixed.
                 New data type (code numbers from 12 to 15, see SIZE function) are
                 now accepted. The data type check is performed earlier in the code.
                 Check on the x_vec and y_vec data type added.
                 keyword EQUALIZE added
   June 2003. AR, A subset of data can be now used to compute the equalized limits
                 (see EQUALIZE keyword)
                 ASPECT keyword implements the possibility to have non-squared
                 pixels
   May 2006. AR, fixed computation of number of digits in case minimum value
             is zero

(See utilities\image_show.pro)


INTERSECTION

[Previous Routine] [Next Routine] [List of Routines]
 empty_inters = intersection(list1, list2, out_list)

 if the range of the union between list1 and list2 is larger then 256*1025
 the routine could be slow (depending on the length of list2)

(See utilities\intersection.pro)


IS_EVEN

[Previous Routine] [Next Routine] [List of Routines]
 NAME:           
       IS_EVEN           
           
 PURPOSE:          
       IS_EVEN returns true (1B) if its argument is even.
		False (0B) otherwais.          

 CATEGORY:           
       Utility          
           
 CALLING SEQUENCE:           
       Result = IS_EVEN(Value)           
           
 INPUTS:
		Value:	scalar or array.

 OUTPUT:
		Result: byte scalar or array (same size of Value).
           
 MODIFICATION HISTORY:           
       Written by:     A. Riccardi; March, 1995.           

(See utilities\is_even.pro)


IS_WRITABLE_DIR

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

 NAME

    IS_WRITABLE_DIR

 SYNTAX

    ret = is_writable_dir(dirname)

 dirname: scalar string containing the directory name to test.

 ret:     scalar byte. 1B if it is possible to write in dirname. 0B otherwise.

 April 1999, written by A. Riccardi (OAA) 

(See utilities\is_writable_dir.pro)


LIN2D_FIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     LIN2D_FIT


 PURPOSE:
     The procedure fits a 2-dim (or 1-dim as a particular case)
     linear operator A described by the following relationship:

     y = A ## x

     where A is a real LxN (L>=1,N>=2) matrix and x and y are real NxM and LxM
     matrices respectively.
     The M>N corresponds to a proper fitting case.
     x is assumed without error and the columns of y are assumed to have
     the same variance-covariance matrix C (LxL) and no covariance
     between the columns themselves.
     The elements of C are related to covariances of y, by:

      = C[j,l]*I[i,k]

     where I is the MxM identity matrix and i,k are the column
     indexes and j,l the row indexes of y following the IDL conventions.

 CATEGORY:
     Fitting Routines


 CALLING SEQUENCE:
     lin2d_fit, x, y, A


 INPUTS:
     x:     real NxM matrix. N is the number of columns of A.
              M is the number of measured sets. Each set is stored
              in a column of x.

     y:     real LxM matrix. L is the number of rows of A.
              M is again the number of measured sets. Each set is
              stored in a column of y.


 KEYWORD PARAMETERS:
    COVAR_Y:      real LxL symmetric matrix. Covariance of each
                    column of y.

    CHISQ:        named variable. Provides the sum of the squared errors.

    DOUBLE:       set this keyword to force double precision calculation.

    SIGMA:        named variable. Returns the standard deviation of
                    the elements of A.

    SINGULAR:     named variable. Contains the number of singular
                    values equal to zero.

    COVAR_FACTOR: named variable. Contains the NxN matrix F that can
                    be used to compute the covariances for the
                    elements of A (LxN):

                     = C[i,k]*F[j,l]

    YFIT:         named variable. Contains the vector A ## x, where
                    A is the fitted matrix.


 OUTPUTS:
    A:            named variable. Real LxN matrix. It contains the result
                    of the fitting.


 MODIFICATION HISTORY:

       Thu Aug 20 18:04:57 1998, Osservatorio Astrofisico di Arcetri,
                                 Adaptive Optics Group.
       Feb 03 2000, A.Riccardi. The possibility to fit non-square
                                matrices A is added.

(See utilities\lin2d_fit.pro)


LIN2D_FITXY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     LIN2D_FITXY


 PURPOSE:
     The procedure fits a 2-dim linear operator A described by the
     following relationship:

     y = A ## x

     where A is a real LxN matrix and x and y are real NxM and LxM matrices
     respectively. M is the number of measurements. N>1 and L>=1.
     The M>N corresponds to a proper fitting case.
     the columns of x and y are assumed to have the same
     variance-covariance matrix Cx and Cy repsectively for and no covariance
     between the columnes themselves.
     The elements of Cx and Cy are related to covariances of x and y, by:

      = Cx[j,l]*I[i,k]
      = Cy[j,l]*I[i,k]

     where I is the NxN identity matrix in the case of Cx and LxL in the case of Cy.

 CATEGORY:
     Fitting Routines


 CALLING SEQUENCE:
     lin2d_fit, x, y, A


 INPUTS:
     x:     real NxM matrix. N is the dimension of the domain of A.
              M is the number of measured sets

     y:     real LxM matrix. L is the dimension of the image space of A.
            M is the same as before.


 KEYWORD PARAMETERS:
    COVAR_X:      real NxN symmetric matrix. Covariance of each
                    column of x.

    COVAR_Y:      real LxL symmetric matrix. Covariance of each
                    column of y.

    CHISQ:        named variable. Provides the sum of the squared errors.

    DOUBLE:       set this keyword to force double precision calculation.

    SIGMA:        named variable. Returns the standard deviation of
                    the elements of A.

    SINGULAR:     named variable. Contains the number of singular
                    values equal to zero.

    COVAR_FACTOR: named variable. Contains the NxN matrix F that can
                    be used to compute the covariances for the
                    elements of A:

                     = C[i,k]*F[j,l]

    YFIT:         named variable. Contains the vector A ## x, where
                    A is the fitted matrix.

    EPS:          float or double scalar. Minimum relative pecision requested
                    in the computation of the elements of the fitted matrix.
                    If undefined 1e-3 is assumed.

 OUTPUTS:
    A:            named variable. Real NxN matrix. It contains the result
                    of the fitting.


 MODIFICATION HISTORY:

       Thu Aug 20 18:04:57 1998, Osservatorio Astrofisico di Arcetri,
                                 Adaptive Optics Group.

(See utilities\lin2d_fitxy.pro)


LIST2RANGES

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

 LIST2RANGES

 This function returns a list of couples of numbers
 giving the ranges of consecutive numbers in the input list.

 ranges = LIST2RANGES(list, range_count [,BREAK_MODULUS=br])


 INPUTS

   list:            byte, short-int or long-int vector. The list don't need to
                    be ordered or having unique elements.

 OUTPUTS

   ranges:          byte, short-int or long-int array. Same type as list.
                    List of ranges of consecutive values
                    in list. The array has 2 columns and range_count rows.

   range_count:     named variable. This variable is set in output to the number of
                    indipendent ranges found in the list vector.

 KEYWORDS

   BREAK_MODULUS:   byte, short-int or long-int scalar. If defined
                    to a value N, it forces a range to be splitted
                    when k*N is included in the range
                    (k=+/-1,+/-2,+/-3,...). In other words it avoids
                    that k*N-1 and k*N are included in the same range.


 EXAMPLE

   list = [3, 14, 2, 13, 4, 1, 13, 11, -1, 5, 0]
   print, list2ranges(list, count)

   -1  5
   11  11
   13  14

   print, count

   3

   The result means that the list can be considered as 3
   not overlapping groups of numbers, the first ranging from
   -1 to 5, the second from 11 to 11 and the last from 13 to 14.

   The same list, using the BREAK_MODULUS keyword:
   list = [3, 14, 2, 13, 4, 1, 13, 11, -1, 5, 0]
   print, list2ranges(list, count, BREAK_MODULUS=5)

   -1   4
    5   5
   11  11
   13  14

   print, count

   4


 HISTORY:

       Nov 27 1999, Armando Riccardi (AR)
       

       Mar 10 2004: AR, BREAK_MODULUS keyword added.


(See utilities\list2ranges.pro)


MAKE_XY

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
       MAKE_XY 
 
 PURPOSE: 
       This procedure generates zero-centered domains in
       cartesian plane or axis, tipically for pupil sampling
       and FFT usage.
 
 CATEGORY: 
       Optics. 
 
 CALLING SEQUENCE: 
 
       MAKE_XY, Sampling, Ratio, X [, Y] 
 
 INPUTS: 
       Sampling:   integer scalar. Number of sampling points per dimension of
                   the domain. Sampling>=2 and must be even.

       Ratio:  floating scalar. Extension of sampled domain:
                   -Ratio <= x [,y] <= +Ratio
               Ratio < Sampling

       X:      variable. Not used as input.
 
 OPTIONAL INPUTS: 
       Y:      variable. Not used as input. Specify this variable if you
               want the y coordinates in the 2-dimension domain case
				(see VECTOR keyword).
        
 KEYWORD PARAMETERS: 
       DOUBLE: set it to have double type output. 
 
       POLAR:  set it to have domain sampling in polar coordinates. If
               VECTOR keyword is set, POLAR setting is not considered.

       VECTOR: if set, 1-dimensional domain is sampled and you needn't
               specify Y variable as input.

       ZERO_SAMPLED:   if set, origin of the domain is sampled.

		QUARTER:	if set, only 1st quadrant is returned. The array (vector)
					returned has Sampling/2 X Sampling/2 (Sampling/2) elements.
		
		FFT:	if set, order the output values for FFT purposes.
				For example, vector -5,-3,-1,+1,+3,+5 is returned as
				+1,+3,+5,-5,-3,-1.
 
 OUTPUTS: 
       X:  floating vector or squared matrix. Returns X values of sampled
           points. Radial values if POLAR is set.
 
 OPTIONAL OUTPUTS: 
       Y:  floating squared matrix. Returns Y values of sampled points.
           Azimuthal angle values if POLAR is set. If VECTOR is set and
           Y is specified as input, it is left unchanged.

       HOW IS SAMPLED THE DOMAIN:

           -ZERO_SAMPLING is not set-
           the edge of the domain is not sampled and the sampling is
           symmetrical respect to origin.

               Ex: Sampling=4, Ratio=1.
                   -1   -0.5    0    0.5    1    Domain (Ex. X axis)
                    |     |     |     |     |
                       *     *     *     *       Sampling points


           -ZERO_SAMPLING is set-
           the lower edge is sampled and the sampling is not symmetrical
           respct to the origin.

               Ex: Sampling=4, Ratio=1.
                   -1   -0.5    0    0.5    1    Domain (Ex. X axis)
                    |     |     |     |     |
                    *     *     *     *          Sampling points

			If FFT keyword is set, output values are ordered for
			FFT purposes:

           Ex: 2-dimensional domain: N = Sampling
           X or Y(0:N/2-1, 0:N/2-1)   1st quadrant (including origin
                                      if ZERO_SAMPLEDis set)
           X or Y(N/2:N, 0:N/2-1)     2nd quadrant
           X or Y(N/2:N, N/2:N)       3rd quadrant
           X or Y(0:N/2-1, N/2:N)     2nd quadrant
 
 EXAMPLE: 
       Compute the squared absolute value of FFT of function
       (x+2*y)*Pupil(x^2+y^2) and display the result.
       Pupil(r)=1. if r<=1., 0. otherwise.

       MAKE_XY, 256, 1., X, Y
       Pupil = X*X+Y*Y LE 1.
       TV_SCL, ABS(FFT((X+2*Y)*Pupil))^2
 
 MODIFICATION HISTORY: 
       Written by:     A. Riccardi; April, 1995. 

(See utilities\make_xy.pro)


MK_VECTOR

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

    Result = MK_VECTOR(Sampling, Min, Max)

    Returns a vector with Sampling elements from Min to Max.

    KEYWORDS
        
        DOUBLE:     force double precision values

        LOGARITMIC: if set, element of the vector are equispatiated on
                    a logaritmic scale

(See utilities\mk_vector.pro)


PRESSURE_PSD

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

 PSD of Dynamic wind pressure fluctuations. A Kaimal wind turbulrnce model is ; used.

 p_psd = pressure_psd(f [,z [,v10]] [,ROUGHNESS=z0] [,AIR_DENSITY=rho]
                      [,STATIONARY_PRESSURE])

 f:      real-number scalar or vector. (input) Temporal frequency vector
         in [Hz]
 z:      real-number, scalar. (optional input) See z in WIND_PSD function
 v10:    real-number, scalar. (optional input) See v10 in WIND_PSD function.

 p_psd:  real-number, same size of f. (output) Dynamic wind pressure [N/m^2]

 ROUGHNESS:  real-number, scalar. (optional input) See z0 in WIND_PSD function.
 AIR_DENSITY:real-number, scalar. (optional input) Air density in [Kg/m^3]
 STATIONARY_PRESSURE: Named variable. (optional output) Stationary value of
                      wind pressure [N/m^2]
 
 HISTORY
  11 Dec 2002, written by A. Riccardi, INAF-OAA, Italy
               riccardi@arcetri.astro.it

(See utilities\pressure_psd.pro)


PSEUDO_INVERT

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

 returns the pseudo-inverted matrix of a given matrix. The pseudo-inverted matrix is computed
 using singular value decomposition method filtering out the singular values w having:
  w < max(w)*eps
 If eps is not specified in the keywords, machine precision value is used.

 a_plus = PSEUDO_INVERT(a [,/DOUBLE][,EPS=eps][,W_VEC=w_vec][,U_MAT=u][,V_MAT=v] $
                        [,INV_W=inv_w][,IDX_ZEROS=idx][,COUNT_ZEROS=count][,/VERBOSE])

 a = u##diagonal_matrix(w)##transpose(u)
 IDX_ZEROS: indexes of vector w related to singular vectors filtered out (-1 if none)
 COUNT_ZEROS: number of singular vectors filtered out
 INV_W: pseudo-inverted of diagonal(w) (equal to diagonal(1/w) if no vectors filtered out)
 /DOUBLE: force double precision computation

 HISTORY:
 09/03/2006: written by A. Riccardi (AR), riccardi@arcetri.astro.it.

(See utilities\pseudo_invert.pro)


QROMLOG

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

 QROMLOG

 res = QROMLOG(func_name, a, b)

 same keywords as QROMO. If MIDEXP is set, only the parameter "a" is accepted ("b" is
 supposed to be infinity).

 a and b must be strictly positive and b>a

 the function computes the integral

 \b               \b                   \log(b)
 | f(x)*dx    as   | x*f(x)*d(log(x)) = | exp(z)*f(exp(z))*dz
 \a                \a                   \log(a)

 Mar 2002: written by A. Riccardi (Osservatorio Astrofisico di Arcetri)
           riccardi@arcetri.astro.it

(See utilities\qromlog.pro)


RAND_SEQ

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

 RAND_SEQ

 This function computes a real random sequence having a flat power
 spectral density inside the frequency range [f_min,f_max] and 0
 outside. The variance (i.e. the total power) of the output sequence is 1.

 seq = RAND_SEQ(f_min, f_max, dt, n_samples, SEED=seed, SPECTRUM=spec)

 f_min:   float, scalar. On input the lower limit of the bandpass.
          On output the lower limit used by the function because of the
          finite sampling.

 f_max:   float, scalar. The same as above for the higher limit of the
          bandpass.

 dt:      float, scalar. The sampling step of the sequence.

 n_samples: long or short integer, scalar. The number of sampling points
            in the sequence.

 SEED:    see randomu procedure.

 ZERO_DC_LEVEL: if set force zero-mean sequence even if f_min is equal to 0.

 SPECTRUM: named variable. On output this variable contains the spectrum of
           the sequence.

 FREQ_VECTOR: named variable. On output the frequency vector related to
              SPECTRUM.

 BIN_STEP: integer scalar. By default is 1. The step (in frequency bins) between
           two successive excited frequencyes. If it is 1 (or not defined) the
           power spectral density of the output signals is a box starting from
           f_min to f_max. If it is greater then one, the power spectral density
           is a sequence of equispaced Dirac's deltas starting from f_min, one
           every BIN_STEP frequency bins. The higher excited frequency bin is less
           then or equal to f_max.

 HISTORY:
   written by Armando Riccardi (AR)
   riccardi@arcetri.astro.it

   06 Aug 2004 Marco Xompero (MX)
    Now the number of samples can be ini, unit, long, ulong.

(See utilities\rand_seq.pro)


READ_ASCII_ARRAY

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_ASCII_ARRAY

 PURPOSE:
        The READ_ASCII_ARRAY function reads a text file containing the definition
        of an array. See below for format definition of the text file.

 SYNTAX:
        array = read_ascii_array(filename)

 RETURN VALUE:
        returns the array defined in filename. In case of error the return
        value is undefined.

 ARGUMENTS:
   filename:  scalar string containing the name of the text file that contains the
              array definition. The file has to have the ".txt" extension.

 DEFINITION OF THE FILE FORMAT

 The format of a text file describing an array is the following:

 ;optional comment or blank lines
 type dim1_len dim2_len ... dimn_len ; optional description
 array_val1 array_val2 ... array_valn
 array_valn+1 ... array_valm
 ...
 ...array_val_last

 Empty lines or lines having ";" or "#" as first non-blank character (optional
 comment lines) are skipped.

 The optional description must start with ";" or "#" character and cannot include
 any other ";" or "#" character.

 The first non-comment line contains the array type (type) and
 the size of each dimension of the array (dim1_len dim2_len ... dimn_len).
 Type can be one of the following case insensitive string:
        byte       (byte)
        int        (16bit short integer)
        long       (32bit long integer)
        float      (floating point)
        double     (double-precision floating point)
        complex    (complex floating-point)
        string     (double-quoted string, like "foo")
        dcomplex   (complex double-precision floating)
        uint       (unsigned 16bit short integer)
        ulong      (unsigned 32bit long integer)
        long64     (64bit long integer)
        ulong64    (unsigned 64bit long integer)

 Type and dimension sizes are separated by (single or multiple) tabs or spaces.
 The ordering of dimensions follows the standard standard IDL/Fortran index
 ordering (from the most to the least fast index, i.e. column-major format in the
 2D-array case).

 The array values start form the second non-comment line. The number of array values
 per line is arbitrary and can be different line by line.
 No comment or blank lines or pending comment are allowed among array values and
 between the first value and the type and dimension size line.
 The ordering of the array values follows the IDL/Fortran ordering (column-major format
 in case of 2D-arrays), with the first index running faster than the second, the second
 runnig faster than the third, etc..

 If type is string, the array string items are not limited by single or double
 quotes. The whole line (including leading or pending spaces) is consideres as
 correct array item value.

 Hexadecimal format is NOT supported for content of int, long, uint, ulong,
 long64 and ulong64 types, yet.
 Complex and dcomplex types are not supported, yet.


 FORMAT HISTORY:
   11 Dec 2003: Created by A. Riccardi riccardi@arcetri.astro.it
   30 May 2004: Help modified: NO hex format supported

(See utilities\read_ascii_array.pro)


READ_ASCII_STRUCTURE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        READ_ASCII_STRUCTURE

 PURPOSE:
        The READ_ASCII_STRUCTURE function reads a text file containing the definition
        of a structure. See below for format definition of the text file.

 SYNTAX:
        struc = read_ascii_structure(filename)

 RETURN VALUE:
        returns the structure defined in filename. In case of error the return
        value is undefined.

 ARGUMENTS:
   filename:  scalar string containing the name of the text file that contains the
              sructure definition. The file has to have the ".txt" extension.

 DEFINITION OF THE FILE FORMAT

 The format of a text file describing a structure is the following:

 ;optional comment or blank lines
 name1   type1   content1 ;optional description
 ;optional comment or blank lines
 name2   type2   content2 ;optional description
 ...
 ;optional comment or blank lines
 nameN   typeN   contentN ;optional description

 Empty lines or lines having ";" or "#" as first non-blank character (optional
 comment lines) are skipped.

 Fields are separated by (single or multiple) spaces or tabs.

 name: valid IDL variable name
 type: one of the following case insensitive strings:
        array      (see 'Content of array' section)
        byte       (content is a scalar byte)
        int        (content is a scalar 16bit short integer)
        long       (content is a scalar 32bit long integer)
        float      (content is a scalar floating point)
        double     (content is a scalar double-precision floating point)
        complex    (content is a scalar complex floating-point)
        string     (content is a double-quoted string, like "foo")
        structure  (see 'Content of strcture' section)
        dcomplex   (content is a scalar complex double-precision floating)
        uint       (content is a scalar unsigned 16bit short integer)
        ulong      (content is a scalar undigned 32bit long integer)
        long64     (content is a scalar 64bit long integer)
        ulong64    (content is a scalar unsigned 64bit long integer)

 Content of int, long, uint, ulong, long64 and ulong64 types can be
 given in hexadecimal format pre-pending x (or X), like x1F8C
 Complex and dcomplex are not supported, yet.

 CONTENT OF ARRAY
 The content of an array can refere to an external file or can be specified in-line.

 In the first case we have two possibilities: text files or FITS files. In case of text
 files the content is a double-quoted string addressing
 the array definition, like "./conf/array.txt". Only ".txt" extension is allowed.
 See read_ascii_array.pro help for a complete desription of the array definition format.
 Use unix-like ("/") directory separator.

 In case of FITS files the content is again a double-quoted string addressing
 the FITS file, like "./conf/array.fits" or "./conf/array.fts". Only ".fits" or ".fts"
 extensions are allowed. Use unix-like ("/") directory separator. Astrolib is required.

 The content of small arrays can be defined in-line using the same format used for
 array definition files:

 varname  array  ; no content after array string
   (array definition, see read_ascii_array help)
 end

 CONTENT OF STRUCTURES
 The content of a structure can refere to an external file or can be specified in-line.
 In the first case the content is a double-quoted string addressing
 the structure definition, like "./conf/struc.txt". The format is the same described in
 this help. Only ".txt" extension is allowed. Use unix-like ("/") directory separator.
 The content of small structures can be defined in-line using the same format used for
 structure definition files:

 varname  structure  ; no content after array string
    ... (structure definition, see above)
 end

 Example:

 ;start of structure definitin file
 name   string "test" ;string definition
 var    float  1.2    ;float definition
 struc1 structure "./struc.txt" ; indirect structure definition

 struc2 structure     ;in-line structure definition
     aa     int    5  ;int definition
     dd     double 6d0;double definition
 end                  ;end of in-line structure definition

 mat1   array  "./array.txt" ; indirect array definition

 mat2   array         ;in-line structure definition
     long 2 3         ;type and dimesion size definition
     123 233
     333 44
     6   1234
 end                  ;end of in-line structure definition

 ppp    ulong64 6457648638  ;unsigned 64-bit long int definition
 ; end of structure definition file

 HISTORY
  Created: 13 Dec 2003, A. Riccardi (AR), riccardi@arcetri.astro.it
	04 Feb 2004		AR and M.Xompero (MX)
					Fixed the bug in extensions retrieval.
   April 2005      D.Zanotti(DZ), comment unuseful keyword regex in row 279.

(See utilities\read_ascii_structure.pro)


REORDER_MATRIX

[Previous Routine] [Next Routine] [List of Routines]
 reorder a matrix of orthonormal modes with respect to a reference matrix of
 orthonormal modes

           modes: matrix of modes (by columns) to reorder
 reference_modes: matrix of reference modes (by columns)

 modes and reference_modes have to have the same number of rows
 Modes in both matrixes have to be normalized like follows:

 transpose(modes)##modes = Identity_matrix
 transpose(reference_modes)##reference_modes = Identity_matrix

 HISTORY:

 29 May 2003 written by A. Riccardi (Osservatorio di Arcetri, Italy)
             riccardi@arcetri.astro.it

(See utilities\reorder_matrix.pro)


SEP_PATH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
    SEP_PATH

 PURPOSE:

    The SEP_PATH function separates the different components of a
    string containing a pathname. It returns the filename, a vector
    of subdirectories in which the filename should be located and the
    root directory, if present (in the Windows OS the latter contains
    the drive tag). The function works ONLY with the unix and Windows
    Operative System families.

 CATEGORY:



 CALLING SEQUENCE:

    filename = sep_path(path)

 INPUTS:

    path:      scalar string. The path string to process.

 KEYWORD PARAMETERS:

    ROOT_DIR:     named variable. Scalar string. The root or current
                  directory path. A disk specification is prepended
                  disk+root
                  in the path. A null string ("") if not defined in
                  path.
    SUBDIRECTORY: named variable. Vector of strings. The sequence of
                  subdirectories contained in path.

 OUTPUTS:

    filename:     scalar string. The filename if present in path,
                  otherwise a null string is returned.
                  Any trailing substring of path that doesn't end
                  with a directory-separator character is considered
                  to be a filename.

 MODIFICATION HISTORY:

    April 1999, written by A. Riccardi (OAA) 

(See utilities\sep_path.pro)


SET_DIAGONAL

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

 SET_DIAGONAL, A, Diag

 INPUT
 A:	matrice quadrata nXn
 Diag:	vettore di lunghezza n (diagonale da settare in A)

 OUTPUT
 In uscita la matrice A ha per diagonale Diag

(See utilities\set_diagonal.pro)


SHIFT_AND_ADD

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

 SHIFT_AND_ADD

 this function returns the shift-and-add result of the input image cube

 saa_image = shift_and_add(image_cube, BACKGROUND=bg, /AVERAGE, IDX_HISTORY=idx_hist)

 image_cube:  input, real 3-dim array. image_cube[N,M,L]. L images of
              size NxM

 BACKGROUNG:  optional input, real NxM array. Background to remove from
              each image before processing it.
 AVERAGE:     If it is set, shift_and_add/L is returned instead of
              shift_and_add

 IDX_HISTORY: optional output. named variable. The list of coordinates of
              the peak value is returned in this variable

 HISTORY:
   05 Dic 2002. Written by A. Riccardi. INAF-OAA, Italy
                riccardi@arcetri.astro.it
   06 Dic 2002. AR. IDX_HISTORY keyword added.

(See utilities\shift_and_add.pro)


SINC

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

 sinc(x) = 1 if x eq 0
         = sin(2*!PI*x)/(2*!PI*x) otherwise

 it's the Fourier transform of Pup(x)= 1 if x le 1
                                       0 otherwise

 Aug 2003  A.R. fixed bug when x=[0]

(See utilities\sinc.pro)


SURF_FIT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	SURF_FIT

 PURPOSE:
	This function determines a polynomial fit to a surface.

 CATEGORY:
	Curve and surface fitting.

 CALLING SEQUENCE:
	Result = SURF_FIT(x, y, z, idx_list, COEFF=coeff, ZOUT=zout, UPLUS=uplus, $
                ZERN=zern, UOUT=uout, UMAT=u, ONLY_COEFF=only_coeff)

 INPUTS:
 	x:
   y:
   z:
   idx_list:
	
 OUTPUT:
	This function returns a fitted array.

 KEYWORDS:
   ZERN:
   COEFF:
   ZOUT:
   UPLUS:
   UOUT:
   UMAT:
   ONLY_COEFF:

 PROCEDURE:
 	Fit a 2D array Z as a polynomial function of x and y.
 	The function fitted is:
  	    F(x,y) = Sum over i and j of kx(j,i) * x^i * y^j
 	where kx is returned as a keyword and i+j le degree.

 MODIFICATION HISTORY:
	July, 1993, DMS		Initial creation

(See utilities\surf_fit.pro)


SVP

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

 computes the saturation vapour pressure over water in Pa.
 It is valid in the range 0-100C, it is but used beyond this
 range.

 svp = svp(t [, /KELVIN])

 t:     float scalar or vector. Temperature

 KEYWORDS:
   KELVIN: if it is set, the input temperature is in Kelvin.
           Default is Celtius degrees.

 HISTORY
   2002: written by G. Brusa, CAAO Steward Obs., USA
         gbrusa@as.arizona.edu

(See utilities\svp.pro)


TELL_TYPE

[Previous Routine] [Next Routine] [List of Routines]
TELL_TYPE
result = tell_type(n_type, F_TYPE=format_type)

 returns the name of the type code

n_type: type codes return by the size function.

KEYWORDS 

 F_TYPE: return the format type associated to the n_type.

 HISTORY
 written by D.Zanotti(DZ)
 Osservatorio Astrofisico di Arcetri, ITALY
 zanotti@arcetri.astro.it
 

(See utilities\tell_type.pro)


TEST_TYPE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       test_type

 PURPOSE:
       test_type returns 1B if the type of the parameter var
       is NOT equal to one of the types specified in the keywords.
       Otherwise it returns 0B.

 CATEGORY:
       Utility

 CALLING SEQUENCE:
       err = test_type(var)

 INPUTS:
       var:          variable to test.

 OPTIONAL INPUTS:
       None.

 KEYWORD PARAMETERS:
       BYTE:         if set test for a byte
       INT:          if set test for an integer
       LONG:         if set test for a longword integer
       FLOAT:        if set test for a single precision floating point
       DOUBLE:       if set test for a double precision floating point
       COMPLEX:      if set test for a single precision complex
       DCOMPLEX:     if set test for a double precision complex
       STRING:       if set test for a string
       STRUCTURE:    if set test for a structure
       POINTER:      if set test for a pointer
       OBJ_REF:      if set test for an object reference
       UINT          if set test for an unsigned integer
       ULONG         if set test for an unsigned longword integer
       L64           if set test for a 64-bit integer
       UL64          if set test for an unsigned 64-bit integer
       UNDEFINED:    if set test for undefined

       NOFLOATING:   if set tests for integer numbers, overriding
                       the BYTE, INT, LONG, UINT, ULONG, L64 and UL64 keywords.
       REAL:         if set tests for real numbers, overriding the BYTE, INT,
                       LONG, UINT, ULONG, L64, UL64, FLOAT and DOUBLE keywords.
       NOREAL:       if set tests for complex numbers, overriding
                       the COMPLEX and DCOMPLEX keywords.
       NUMERIC:      if set tests for any numeric data, overriding the BYTE,
                       INT, LONG, UINT, ULONG, L64, UL64, FLOAT, DOUBLE,
                       COMPLEX, DCOMPLEX, REAL, NOREAL, NOFLOATING keywords.
       DIM_SIZE:     a named variable to receive a long array.
                       Firt element: number of dimensions. Following
                       elements: the number of elements for each dimension.
                       The number of dimensions is 0 if var is a scalar,
                       or is undefined.
       N_ELEMENTS:   a named variable to receive a long scalar.
                       The total number of elements.
       TYPE:         a named variable to receive a long scalar.
                       The type of the input (see SIZE)

 OUTPUTS:
       err:          byte scalar. 0B if var match one of the
                     requested types, 1B otherwise

 OPTIONAL OUTPUTS:
       See keywords

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       None.

 RESTRICTIONS:
       None.


 PROCEDURE:
       Use the SIZE function.

 EXAMPLE:
       if test_type(var, /LONG, N_ELEMENTS=n_var) then $
         message, "The variable is not a long"
       if n_var ne 1 then $
         message, "The variable must be a scalar"

 MODIFICATION HISTORY:
       May 1998. Written by A. Riccardi (AR). INAF-OAA, Italy
                 riccardi@arcetri.astro.it
       Dic 2002. UINT, ULONG, L64 and UL64 keywords added.
                 An error message added if an unknown data type code
                 is found.

(See utilities\test_type.pro)


TIMING

[Previous Routine] [Next Routine] [List of Routines]
 NAME: 
       TIMING 
 
 PURPOSE: 
       This function compute time elapsed since last calling. 
 
 CATEGORY: 
       Utilities. 
 
 CALLING SEQUENCE: 
  
       Result = TIMING(T) 
 
 INPUTS: 
       T:      long integer variable. System time returned by last calling
               of TIMING.
 
 OUTPUTS: 
       Result: float. Time elapsed since last calling in minutes. If
               T is undefined, Result is -1..

       T:      long integer. Updated to current system time for future use.
 
 RESTRICTIONS: 
       If T variable is modified since last calling, the Result is uncorrect. 
 
 EXAMPLE: 
       Print the time needed to execute a sequence of stantments:

       Dummy = TIMING(T)
       ...
       ...
       ...
       PRINT, TIMING(T)
 
 MODIFICATION HISTORY: 
       Written by:     A. Riccardi; Month, 1995. 
       July, 1994      Any additional mods get described here.  Remember to 
                       change the stuff above if you add a new keyword or 
                       something! 

(See utilities\timing.pro)


TVSCL1

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

(See utilities\tvscl1.pro)


TYPE2NBITS

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

 the function returns the number of bits per elements of input data.

 n_bits = type2nbits(data, [TYPE=type])

 KEYWORDS

  TYPE:   optional named variable. On output contains the IDL code of the
          data type of input.

 HISTORY
   31 May 2004, written by A. Riccardi

(See utilities\type2nbits.pro)


UNDEFINE

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

  undefine the passed variable.

  undefine, var

  EXAMPLE

 IDL> a=1
 IDL> help, a
 A               INT       =        1
 IDL> undefine, a
 IDL> help, a
 A               UNDEFINED = 

   HISTORY

 1999 created by A. Riccardi
 28 Jul 2004 Marco Xompero (MX)
  It undefines more variable in the same command line.

(See utilities\undefine.pro)


UNION

[Previous Routine] [Next Routine] [List of Routines]
 list_union = union(list1, list2)

 list1, list2: numeric scalar or vector or array
 list_union: union (without repeated elements) of the input lists

(See utilities\union.pro)


WDEL

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

 NAME

  WDEL

 wdel

 delete all the windows currently defined.

 April 1999, A.R. (AOO)

(See utilities\wdel.pro)


WIND_PSD

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

 Kaimal Longitudinal Wind Turbulence: power spectral density (PSD) of wind
 speed fluctuations. The used formulation is valid for a few tens of meters
 from the ground (logarithmic profile of the stationary wind speed with
 respect to z)

 v_psd = wind_psd(f [, z [, v10]] [,ROUGHNESS=z0] [,STATIONARY_SPEED=v])

 f:      real-number scalar or vector. (input) Temporal frequency vector
         in [Hz]
 z:      real-number, scalar. (optional input) Height from the ground [m].
         Default value is 10.0m.
 v10:    real-number, scalar. (optional input) Stationary wind speed at 10m
         from the ground [m/s]. Default value 10.0m/s.
 z0:     real-number, scalar. (optional input) roughness constant [m], 0.01-0.1m
         for open grassland, 0.3-1.0m for forest and suburban areas.
         Default value: 0.3m

 v_psd:  real-number, same size of f. (output) Wind speed PSD [N/m^2]

 STATIONARY_SPEED: named variable. (optional output) sationary wind speed at
                   height z. [m/s]

 HISTORY

  11 Dec 2002, written by A. Riccardi, INAF-OAA
               riccardi@arcetri.astro.it

(See utilities\wind_psd.pro)


WRITE_ARRAY_ASCII

[Previous Routine] [Next Routine] [List of Routines]
Write_array_ascii, vector, FILENAME=filename
Purpose:
 Write an array in an ascii file txt
INPUT:
 vector: array to write in tne file
KEYWORD
 FILENAME: name of file where writes the array in ascci format.
HISTORY
 created by D.Zanotti(DZ)
  Osservatorio Astrofisico di Arcetri, ITALY
  


(See utilities\write_array_ascii.pro)


WRITE_LABELS

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

    WRITE_LABELS, Label_file

    Label_file: name of the file where store coordinates and labels in.

 History

   Sometime, created by A. Riccardi, Osservatorio astrofisico di Arcetri (Italy)
   21 Oct, 2002 - free_lun is used instead of close

(See utilities\write_labels.pro)


WRITE_STRUCT

[Previous Routine] [Next Routine] [List of Routines]
WRITE_STRUCT
err = write_struct(unit_s, struct_value, name_str)

PURPOSE:
 Writes a in-line struct in a text file, if the in-line struct
 cointains an array or another struct, for the struct another 
 text file is created and  refered in the source text file. 

unit_s: The unit number associated with the opened file.
struct_value: the structure to write in the file txt.
name_str: name of the structure

KEYWORDS 
 None.

 HISTORY
 written by D.Zanotti(DZ)
 Osservatorio Astrofisico di Arcetri, ITALY
 zanotti@arcetri.astro.it
 

(See utilities\write_struct.pro)


WRITE_STRUCTURE_ASCII

[Previous Routine] [Next Routine] [List of Routines]
WRITE_STRUCTURE_ASCII, name_struct, FILENAME=filename

PURPOSE:
 writes a structure in a file text in order to the text definition
 format.

   name_struct: The structure to write in the text file.

 KEYWORDS:
   FILENAME: the name of text file, if not set a default_name is
   used.

 HISTORY  
 written by D.Zanotti(DZ)
 Osservatorio Astrofisico di Arcetri, ITALY
 zanotti@arcetri.astro.it
 


(See utilities\write_structure_ascii.pro)


WRITE_STRUCTURE_MAP

[Previous Routine] [Next Routine] [List of Routines]
WRITE_STRUCTURE_MAP
 
write_structure_map, name_struct, FILENAME=filename

PURPOSE
  writes a structure of  address map in a text file.

name_struct: address map structure to write.

KEYWORDS
FILENAME: name of txt file.

HISTORY:
written by D.Zanotti (DZ)
Osservatorio di Astrofisico di Arcetri
zanotti@arcetri.astro.it

(See utilities\write_structure_map.pro)


XSHOW

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
   XSHOW

 PURPOSE:
   Wrapper to IMAGE_SHOW with zoom capabilities.
   Display min and max values of the input vector
   Left-click and drag to zoom
   Middle-click to unzoom
   Rigth-click to popup contect menu:
       -  save in jpg format
       -  show info window
       -  quit

 CATEGORY:
   General graphics.

 CALLING SEQUENCE:

 xshow, input, x_vec, y_vec, /LABEL, ZOOM_SCALE=zoom_scale, XSIZE=xsize, 
      YSIZE=ysize, KEYWORDS  with the KEYWORDS of IMAGE_SHOW 

 INPUTS:
   input:  If x_vec and y_vec are not present, "input" is the two-dimensional array
           to display. If x_vec and y_vec are present, "input" is a vector of values
           of the map to dispaly in the corresponding irregular grid defined by x_vec
           and y_vec.

   x_vec, y_vec  cannot be used when "input" is a two-dimensional array. If they are
           defined, they have to be vectors with the same size as "input". In the last
           case TRIGRID is used to obtain a regular gridded two-dimensional array
           to display.
 KEYWORDS:
   ZOOM_SCALE: if set, change the limit of the lookup table according to the zoom view. 
               Otherwise constants limits are used. See MAX(MIN)_VALUE in IMAGE_SHOW

   LABEL: If set display a status bar with selected pixel (coords and value) and 
          with minmax of input (coords and value)
   
   XSIZE: Set width of the window

   YSIZE: Set height of the window

 OUTPUTS:
   No explicit outputs.

 COMMON BLOCKS:
   None.

 SIDE EFFECTS:
   The currently selected display is affected.

 RESTRICTIONS:
   None.

 MODIFICATION HISTORY:
   22 May 2005  written by Lorenzo Busoni (LB)
   23 May 2005  A. Riccardi (AR), multiple instances bug fixed
   24 May 2005  LB, window resize handling and zoombox display added 
   25 May 2005  LB, color table is stored in the parameter structure
                    info window added
                    XSIZE,YSIZE added
   26 May 2005  LB, save_jpg and small zooms bugs fixed

(See utilities\xshow.pro)


XYPLOTERR

[Previous Routine] [List of Routines]
 NAME:
	XYPLOTERR

 PURPOSE:
	Overplot data points with accompanying error bars for x and y.

 CATEGORY:
	Plotting, 2-dimensional.

 CALLING SEQUENCE:
	OPLOTERR,  X,  Y , ErrX, ErrY, PSYM=Psym

 INPUTS:
	Y:	The array of Y values.

	Err:	The array of error bar values.

 OPTIONAL INPUT PARAMETERS:
	X:	An optional array of X values.  The procedure checks whether
		or not the third parameter passed is a vector to decide if X
		was passed.

		If X is not passed, then INDGEN(Y) is assumed for the X values.

	PSYM:	The plotting symbol to use (default = +7).

 COMMON BLOCKS:
	None.

 SIDE EFFECTS:
	None.

 RESTRICTIONS:
	Arrays cannot be of type string.  There must be enough points to
	plot.

 PROCEDURE:
	A plot of X versus Y with error bars drawn from Y - ERR to Y + ERR
	is written to the output device over any plot already there.

 MODIFICATION HISTORY:
	William Thompson	Applied Research Corporation
	July, 1986		8201 Corporate Drive
				Landover, MD  20785
       kdb, March, 1997  - Fixed a problem if 1 element arrays where used.

(See utilities\xyploterr.pro)