NAME:
	FF_SUMMARY


 PURPOSE:
	Get a 1-line summary of a FITS file (SMEI)


 CATEGORY:
	UTILS


 CALLING SEQUENCE:
	desc = ff_summary(file)


 INPUTS:
	file	string	The file to summarize (if the path key is set,
			then it can be a wildcard).


 KEYWORD_PARAMETERS:
	/template	Return a title bar for a summary
	path	string	A directory to search for the files. (If this
			is given then file is optional and defaults to
			the current directory.
	filelist str	If this is a named variable, then it will
			return the list of filenames (only really
			useful when path is given).
	startlist dbl	If this is a named variable then it will
			contain the JD's of the image start times.
	count	long	If this is a named variable, on return it will
			contain the number of files found.
	/no_file	If set then actually open each file rather
			than using the img_hdr.txt file to get the info.
	/norecurse	If set, then do not look in subdirectories.
	projections str	A named variable to hold the list of
			projections of the images.
	/no_progresss	If set, then do not create a progress bar to
			show progress through files and directories
			(mainly for running over a slow network). 		


 CALLS: ***
	CW_PROGRESS, EPOCH2JD, GET_COMP_NAME, HEADFITS [1], HEADFITS [2], HEADFITS [3]
	HIST_FIND, STRUCT_CONTAINS, UNIQ [1], UNIQ [2], UNIQ [3], doy2jd, fitshead2struct
	jd2doy, smei_msg, strsplit
 CALLED BY:
	MK_IMGHDRTXT, SMEI_SEQUENCE
 MODIFICATION HISTORY:
	Original: 13/12/02; SJT
	Modify for degenerate Aitoff files: 7/3/03; SJT
	Modify to allow use of a tree to store files: 1/7/03; SJT
	Add fold_case keyword to file_search calls: 23/7/03; SJT
	Fix crash in single plane images: 2/10/03; SJT
	Deal with possibility of files called .fts: 20/11/03; SJT
	Add projection information, and projections keyword, and save
	list: 16/2/04; SJT
	Do recursion explicitly to allow symlinked subdirs to work:
	12/8/04; SJT
	Major efficiency changes: 11/11/04; SJT
	Add list of mal-indexed directories: 31/5/05; SJT
	Support compressed fits files: 24/5/05; SJT
	Add no_progress keyword: 25/8/05; SJT

 NAME:
	filespec_common
 PURPOSE:
	Contains common block used by filespec procedures
 CATEGORY:
	String manipulation
 CALLING SEQUENCE:
	@filespec_common.pro
 INCLUDED BY:
	PutFileSpec, SetFileSpec
 PROCEDURE:
	File is set by SetFileSpec and updated by PutFileSpec
	File is used read-only by GetFileSpec
	Parts is used read-only by PutFileSpec and GetFileSpec
 MODIFICATION HISTORY:
	JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	Find2DGlitch
 PURPOSE:
	Find 'cosmic rays' in a set of 2D frames
 CATEGORY:
 CALLING SEQUENCE:
	Result = Find2DGlitch(Frames [,sumwidth=SumWidth, /exclude,	$
				sigmathreshold=SigmaThreshold, loc=Loc])
 INPUTS:
	Frames			array[n,l,m]; type: any (float or double needed to use NaN option)
						stack of 2D frames combined in 3D array; the last dimension counts
						the number of frames (if it is absent then a dummy dimension of 1
						is added).
						Frame elements set to the value !VALUES.F_NAN or D_NAN are ignored
 OPTIONAL INPUT PARAMETERS:
	SumWidth		scalar, type integer, no default
						defines a box of SumWidth by SumWidth pixels used by procedure FrameMoments
	SpotWidth		scalar, type integer, no default
						defines a box of SpotWidth by SpotWidth pixels used by procedure CleanGlitchBox
	sigmathreshold	scalar, any type, default: 4.
						see PROCEDURE
	minthreshold	scalar, any type, default: 0
						see PROCEDURE
	/exclude		if set, then each pixel in the Frames array is tested based on statistical
						moments calculated omitting the pixel itself
	/remove			if set the glitches are replaced by average values calculated
						after removal of the glitches
	/group			activates grouping of pixels that are close together.
 OUTPUTS:
	Result			scalar, type long integer
						number of glitches found
 OPTIONAL OUTPUT PARAMETERS:
	loc=Loc			1-dim array [*], type long integer
						location of the glitches
						glitch positions are identified by a one-dimensional array index
	/quiet			if set, the list of glitches found is not printed to the screen

	ngroup=ngroup
	pgroup=pgroup
	lgroup=lgroup	unmodified return arguments from a call to the GroupPixels procedure
	fgroup=fgroup	contains total # adus in each group (after subtraction of underlying average)
 INCLUDE:
	@compile_opt.pro	; On error, return to caller
 CALLS: ***
	ArrayLocation, BadValue, CleanGlitchBox, FrameMoments, GroupPixels, InitVar
 CALLED BY:
	qGlitch_Run
 PROCEDURE:
	If there are nT frames of dimension nX by nY then Frames has dimensions nX,nY,nT

	For each of the nX*nY pixels an average and standard deviation is calculated by averaging
	all nT boxes of SumWidth^2 pixels (total of SumWidth^2*nT pixels).

	A 'cosmic ray' is defined as a pixel where the frame value is more than SigmaThreshold
	standard deviations above the average.
	If MinThreshold is set than the frame value must be at least MinThreshold above the
	average to count as a glitch. This second test can be used to avoid that lots of points
	are flagged when the standard deviation becomes real small.
 MODIFICATION HISTORY:
	OCT-1998, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	FindAllFiles
 PURPOSE:
	Extended version of FindFile for locating file satisfying
	a list of file specs in a list of directories.
	FindAllFiles is intended to be robust; it is slow compared
	to a direct call to findfile.
 CATEGORY:
	Environment
 CALLING SEQUENCE:
	FUNCTION FindAllFiles, FilesIn, paths=PathsIn, count=Count, separator=Separator,	$
		shortnames=ShortNames, nodirectories=NoDirectories, recursive=Recursive, symlink=symlink, $
		excl_files=excl_files, excl_paths=excl_paths, excl_recursive=excl_recursive,	$
		forcecd=ForceCD, ls_style=ls_style
 INPUTS:
	Files			list of file specifications, specified as
					a comma-separated list, or a string array
					(default: *.*, NOT *)
 OPTIONAL INPUT PARAMETERS:
	paths=Paths		list of directories to be searched, specified
					as a separated list, or a string array
					(if omitted then the current directory is assumed)

	separator=Separator
					separator used between entries in Files and Paths
	/shortname		if set then only file name, type (and version
					on vms) are returned (default: return fully
					qualified names)
	/recursive		search recursively through all subdirectories
	/symlink		(only on Unix/Linux systems when /recursive is set)
					by default, a recursive search does not descent into
					directories that are symbolic links. If /symlink is
					set then it will (see "IsSymLink").
	/nodirectories	discards directories, i.e. only regular files are
					returned.
	/forcecd		THIS HAS ONLY BEEN TESTED ON LINUX.
					by default the IDL findfile function is called with
					argument of type full_dir+file_name_wildcard.
					The array returned by findfile will then also contain
					fully-qualified filenames. In deeply nested directories
					with lots of matching files findfile may return nothing
					at all (probably because some memory buffer overflows).
					Setting /force_cd will first cd into 'full_dir', then
					do a findfile with only file_name_wildcard. Findfile will
					only return file names (without a directory). 'Full_dir'
					is then explicitly prefixed to the output of findfile.
					This may prevent the buffer overflow.
	/ls_style		passed to findfile_fix. If set then the content
					of subdirectories is included.

	Three additional keywords allow files and/or paths to be excluded:

	excl_files=excl_files
					list of file specifications similar to 'Files'
	excl_paths=excl_paths
					list of directories similar to 'Paths'
	/excl_recursive
					triggers a recursive search similar to '/recursive'

	These three keyword are used as input for a recursive call to
	FindAllFiles. The result is subtracted from the files matching
	found using 'Files' and 'Paths'

 OUTPUTS:
	Result			string array with filenames; if no files are found then
					files is set to the null string (files='')
 OPTIONAL OUTPUT PARAMETERS:
	count=Count		number of files located
 INCLUDE:
	@compile_opt.pro		; On error return to caller
 CALLS: ***
	CheckDir, FILEPATH, FindAllSubDirs, GetFileSpec, InitVar, IsType, SetFileSpec
	UNIQ [1], UNIQ [2], UNIQ [3], findfile_fix, os_separator, where_common
 CALLED BY:
	SetFileSpec, htmd_cat, qView_FileFilter, qView_PickFiles, smei_base_testcase
	smei_buf_getframe, smei_frm_get, smei_getfile, smei_hdr_update, smei_sky_read
	vu_select, www_help_files
 SIDE EFFECTS:
 >	windows: Directories . and .. are omitted
	Trailing delimiter for directories are stripped off
 >	If both Files and Paths are specified as arrays then Separator is
	not used.

	The findfile function on Linux sometimes shows peculiar behavior
	(similar to the Unix ls command). Problems can arise when searching
	a directory with containing only one subdirectory; or when the
	directory contains a symbolic link.
 PROCEDURE:
	Separator is OS dependent: ',' on VMS and Win32, ' ' on all other
	Each entry in the Files list can contain a directory specification;
	in that case the Paths keyword is not used for that entry.
 MODIFICATION HISTORY:
	???-????, Paul Hick (UCSD/CASS)
	AUG-2000, Paul Hick (UCSD/CASS)
		Added /recursive keyword
	JUN-2001, Paul Hick (UCSD/CASS)
		Added /symlink
	JAN-2002, Paul Hick (UCSD/CASS)
		Added exclusion keywords
	SEP-2002, Paul Hick (UCSD/CASS)
		On Linux output from the IDL findfile function is now filtered
		through findfile_fix to deal with directories.
		(this may actually be necessary for all Unix flavors)
		Added /forcecd and /ls_style keywords. Added check to exclude
		wildcards in the directory paths.
	MAR-2003, Paul Hick (UCSD/CASS)
		Improved processing of FileIn=''. This now should handle directories
		with lots of files better (at least on Linux) by avoiding the used
		of an explicit wildcard (*.*) in the call to findfile.
	FEB-2004, Paul Hick (UCSD/CASS)
		Changed check for !version.os to check for !version.os_family.
		Makes this hopefully it bit more generally useful.
	OCT-2004, Paul Hick (UCSD/CASS)
		Modified handling of a path specification without a filename.
		Windows didn't handle the Linux solution correctly.
	OCT-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added forcecd keyword to FindAllSubDirs call

 NAME:
	FindAllSubDirs
 PURPOSE:
	Return a list of all subdirectories in a specified directory
 CATEGORY:
	Environment
 CALLING SEQUENCE:
	FUNCTION FindAllSubDirs, Path, count=Count, symlink=symlink, recursive=recursive, forcecd=ForceCD
 INPUTS:
	Path			scalar; type: string; default: current directory
 OPTIONAL INPUT PARAMETERS:
	/symlink		by default, symbolic links to directories are not returned
				unless /symlink is set (ignored on non-unix systems;
				see IsSymLink.
 OUTPUTS:
	List			array; type: string
						list of subdirectories
						fully-qualified directory names are returned.
						on Linux and Win32 the directories include the trailing (back)slash
						if no subdirectories are found then List = '' is returned.
 OPTIONAL OUTPUT PARAMETERS:
	count=count		scalar; type: integer
						number of subdirectories
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	CheckDir, FILEPATH, GetFileSpec, InitVar, IsSymLink, SetFileSpec
 CALLED BY:
	FindAllFiles, findfile_fix, mk_flick, www_help_tree
 RESTRICTIONS:
	Currently linux, Win32 and vms are implemented.
 PROCEDURE:
	Findfile is used to get a list of files in the specified directories. Then the
	directories are selected.
 MODIFICATION HISTORY:
	AUG-2000, Paul Hick (UCSD/CASS)
	JUN-2001, Paul Hick (UCSD/CASS)
		added /symlink keyword
	JAN-2002, Paul Hick (UCSD/CASS)
		Return arg 'Count' didn't exist on return if 'path' didn't exist.
		Now zero is returned.
	JUL-2002, Paul Hick (UCSD/CASS)
		Fixed a bug caused by peculiar behaviour of IDL findfile on Linux
		(and presumably every Unix flavor) when a directory is tested
		containing only a single subdirectory. This apparently reflects
		the same peculiar behaviour of the Unix 'ls' command.
	MAR-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added /recursive keyword
	SEP-2006, Paul Hick (UCSD/CASS)
		Added some code to deal with spaces in directory names (adding
		explicit quotes). Moved initvar statement for Path to start of function. 
	OCT-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added forcecd keyword.

 NAME:
	findfile_fix
 PURPOSE:
	Applies fix to output from IDL findfile procedure.
 CATEGORY:
	gen/toolbox/files
 CALLING SEQUENCE:
	new_files = findfile_fix(old_files, count=count)
 INPUTS:
	path
	file
	old_files	array; type: string
				Output from findfile
 OPTIONAL INPUT PARAMETERS:
	count=count	scalar; type: integer
				Output from findfile (# files)
 OUTPUTS:
	new_files	array; type: string
				Corrected 'old_files' array
 OPTIONAL OUTPUT PARAMETERS:
	count=count	scalar; type: integer
				# entries in new_files
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	FILEPATH, FindAllSubDirs, GetFileSpec, InitVar, SetFileSpec, where_common
 CALLED BY:
	FindAllFiles
 PROCEDURE:
	This is kludging at its best. On Linux (maybe even all Unix
	flavors??) a findfile call with a wildcard (in particular a
	single star) can pick up subdirectories:
		files = findfile('path/*')
	The result is a	string array of the form:
		full_file_1
		full_file_2
		..
		full_file_n
		(blank line)
		full_subdir_1:		(sub dir name followed by colon)
		file_1_in_subdir_1	(file name without directory)
		file_2_in_subdir_1	(file name without directory)
		..
		file_n_in_subdir_1	(file name without directory)
		(blank Line)
		full_subdir_2:		(sub dir name followed by colon)
		etc.

	The list of full_file_n at the beginning may not be present.
	Moreover, if only one subdirectory matches the template then
	full_subdir_1 will be missing too, and only the list
	file_n_in_subdir_1 remains. In this last case it is impossible
	to reconstruct the full file names. An attempt is made to recover
	the name of the subdirectory using FindAllSubdirs. If not
	successful then these entries (the whole list of files) is discarded.

	If it is possible to reconstruct full paths, two approaches
	are possible depending on the setting of /ls_style.
	If /ls_style is NOT set, then all entries inside subdirectories
	are discarded, and only the subdirectory name itself is returned.

	If /ls_style IS set, then the content of subdirectories is also
	returned (converted to full paths by prefixing the names of the
	subdirectory). Blank lines are always removed.
 MODIFICATION HISTORY:
	SEP-2002, Paul Hick (UCSD/CASS)
	MAR-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added a fix to make sure subdirectories have a trailing slash
		when output from findfile with only a directory (no filename)
		as argument is processed.

 NAME:
	FindPeaks
 PURPOSE:
	Find local maxima in 2D array
 CATEGORY:
	smei/gen/idl/toolbox
 CALLING SEQUENCE:
	Peaks = FindPeaks(Box, mask=Mask, map=Map, nmax=nmax, flat=flat)
 INPUTS:
	Box			2D array, any type
 OPTIONAL INPUT PARAMETERS:
	mask=Mask	1D or 2D array, type integer, default: no mask (includes all elements)
					Elements outside the mask are ignored
					1D array: list of indices defining the area in Box to be searched
					for maxima.
						!!! A 1-element mask MUST be entered as an array of 1-element.
							A scalar is ignored, so put brackets around the input
							argument if necessary)
					2D array: array of same dimensions as Box with value 1 defining
						the mask and value 0 outside the mask.
	fraction=fraction
				scalar; same type as input array; default: 1.0
					fraction between 0 and 1. Only this fraction of the image inside
					the mask is searched for local maxima.
	mindist=mindist
				scalar; type: any; default: 0
					minimum distance between local maxima. Local maxima closer then
					mindist to a higher local maximum are included with the higher
					maximum.
	npeak=npeak	scalar; type: integer
					Maximum number of local maxima to be detected. By default the
					whole array is searched for all maxima. If npeak is set then the
					search is interrupted when npeak local maxima have been found.
					In this case the 'map' array will be partially filled with the
					value returned in 'untested' to indicate that this part of Box
					has not been searched for maxima.
	flat=flat	scalar; same type as input array.
					In determing whether neigbour pixels are above/at/below the
					central pixel of a 3x3 group of pixels, above/at/below are defined
					as follows:
						below:	Vneighbour < Vcenter-flat
						at   :  Vcenter-flat <= Vneigbour <= Vcenter+flat
						above:  Vneighbour > Vcenter+flat
					In a 'noisy' map setting flat to a positive value, suppresses the
					detection of lots of unwanted local maxima. (Probably the same can be
					accomplished by applying the IDL smooth function to the input
					argument Box before calling this function.)
 OUTPUTS:
	Peaks		1D array, type integer
					Indices of local maxima inside area defined by mask
 OPTIONAL OUTPUT PARAMETERS:
	map=Map		2D array, type long integer, same dimension as Box
					Provisionally divides Box into areas associated with each
					local maxima. The index from the Peaks array is used
					in Map to indicate the associated maximum
	untested=untested
				value used to indicate untested areas in Box (see npeak keyword)
 CALLS: ***
	InitVar, IsType, boost, where_common
 PROCEDURE:
	The entire input image is searched for local maxima. This very quickly
	takes and intolarably long time. Usually keywords fraction and/or npeak need
	to be used to get results reasonably quick.
 MODIFICATION HISTORY:
	OCT-1998, Paul Hick (UCSD/CASS)
	JAN-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Fixed problems with local maxima of equal height. Added keywords npeak,
		untested and flat. Significant speedup by processing groups of up to
		nine pixels (3x3 group) instead of only single pixels.

 NAME:
	FishEye
 PURPOSE:
	Converts spherical angles to coordinates for a 'fish-eye' plot
 CATEGORY:
	Math: projections
 CALLING SEQUENCE:
	xy = FishEye(Pos, /degrees, dabg=dabg)
 INPUTS:
	Pos				array[2,*]; type: float
						pos[0,*]: phase angle, longitudes
						pos[1,*]: latitude
 OPTIONAL INPUT PARAMETERS:
	/degrees		if set, all angles are in degrees (default: radians)
	maxelo=maxelo	scalar; type: float; default: !pi
						elongation 'maxelo' is scaled to 2*sqrt(2)
	dabg=dabg		array[3]; type: float; default: [0,0,0]
						Euler angles to be added to the rotation
						discussed in PROCEDURE.
	zero_phase		scalar; type: float; default: none
						Additional offset applied to phase angle
						i.e. adds Euler triplet [zero_phase,0,0] to
						the rotation discussed in PROCEDURE.
 OUTPUTS:
	xy				array[2,*]; type: float
						x and y coordinates in fish-eye plot
 OPTIONAL OUTPUT PARAMETERS:
	polar=polar		array[2,*]; type: float
						polar coordinates in fish-eye plot
 INCLUDE:
	@compile_opt.pro			; On error, return to caller
 CALLS: ***
	EulerRotate, IsType, SyncDims, ToRadians
 CALLED BY:
	ColorSkybox, PlotEarthSkymap, PlotPolarSkymap, nagoya_glevel
 PROCEDURE:
 >	The input angles are usually celestial spherical coordinates, e.g.
	ecliptic longitude and latitude, or right ascension and declination.
 >	The fish-eye plot uses phase and polar angles relative to a coordinate
	system with the z-axis along longitude=0,latitude=0, and the x-axis along
	longitude=90, latitude=0. The transformation to this coordinate system
	takes Euler angles E=[0,90,90] degrees.
 >	The Euler angle triplet specified in keyword dabg will be added to E,
	i.e. the total rotation applied to the input coordinates is E+dabg.
	dabg is used to change the direction for the center of the fish-eye plot.
	E.g. if the input angles are ecliptic coordinates and the ecliptic
	coordinates of the Sun are [l,d], then dabg = [l,-d,0] would put the Sun
	in the center of the fish-eye.	
 >	In the fish-eye coordinate system the following transformation is used:
		x = polar*cos( phase )*(2*sqrt(2.)/maxelo)
		y = polar*sin( phase )*(2*sqrt(2.)/maxelo)
	i.e. the maximum polar angle 'maxelo' is scaled to 2*sqrt(2)
 MODIFICATION HISTORY:
	SEP-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	flat_centerofmass
 PURPOSE:
	Calculations related to the centroid of a flat density distribution
 CATEGORY:
	gen/idl/toolbox
 CALLING SEQUENCE:
	R = flat_centerofmass(box [, /polar, /degrees])
			Returns centroid of 'box'
	R = flat_centerofmass(box ,/shift_origin [, /polar, /degrees])
			Returns coordinate of 'box' relative to its centroid
	R = flat_centerofmass(box , centroid [, /polar, /degrees])
			Positions box with its centroid matching 'centroid'
 INPUTS:
	If /polar NOT set:
	box			array[2,2]; type: integer
					defines two corners of box in the form [ [x1,y1], [x2,y2] ]

	If /polar set:
	box			array[2,2]; type: float
					limiting values in phase angle and radius of the wedge
					in the form [[angle1,radius1],[angle2,radius2]].
					Angle1 and angle2 are in radians between [-!pi,+!pi].
					The wedge runs counterclockwise from 'angle1' to 'angle2'
					over less than 180 degrees: either angle2 > angle1 with
					angle2-angle1 < !pi or angle2 < angle1 with
					angle2+2*!pi-angle1 < !pi. Always radius1 < radius2.
 OPTIONAL INPUT PARAMETERS:
	centroid	array[2]; type: float or integer
					position of centroid in rectangular (if /polar NOT set)
					or polar (if /polar set) coordinates. If this argument is specified
					then box is positioned with its centroid on this point.
	/polar		if set, box and centroid is specified in polar coordinates
					(default: rectangular coordinates)
	/shift_origin
				if set, then the centroid of 'box' is calculated. Then the coordinates
					of 'box' relative to this center are returned.
	/degrees	if set, in- and output angles are in degrees (default: radians)
 OUTPUTS:
	R			array[2]
				array[2,2]
 CALLS: ***
	AngleRange, InitVar, IsType, ToRadians
 CALLED BY:
	even_light, qImage_TrackPeak, qView_TrackPeak
 PROCEDURE:
	For a rectangular, constant density distribution the centroid is the
	geometric center of the box (the mean of the x and y coordinates of the corners).

	For a wedge shaped box the phase angle of the centroid is the geometric mean
	of the phase angles of the corners: phi(centroid) = (phi1+phi2)/2.
	For the radius, r(centroid)^2 = (r1^2+r2^)/2.

	If /shift_origin is set then the return values are the coordinates
	of 'box' relative to the centroid (i.e. the centroid coordinates are
	subtracted from the box coordinates

	If argument 'centroid' is specified then the centroid of 'box' is calculated.
	Then the box is positioned on 'centroid' such that the box centroid coincides
	with 'centroid'.
 MODIFICATION HISTORY:
	MAR-2000, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	FLL_GRID


 PURPOSE:
	Ad a latitude/longitude grid to a fish-eye image


 CATEGORY:
	Utils


 CALLING SEQUENCE:
	fll_grid[, dlong, dlat]


 OPTIONAL INPUTS:
	dlong	int	The step in longitude
	dlat	int	The step in latitude


 KEYWORD PARAMETERS:
	/label			If set, then label the grid.
	charsize	Float	Set a size for the labels (ignored if
				label is not set.
	max_elongation	float	Set the largest elongation to show
				(default=135)
	Any key accepted by PLOTS will be passed through.


 CALLS: ***
	WCSSPH2XY
 RESTRICTIONS:
	Steps will be rounded to the nearest whole degree


 MODIFICATION HISTORY:
	Original: 13/2/04; SJT
	Add labelling: 16/2/04; SJT

 NAME:
	flt_clean
 PURPOSE:
	Check a specified format against a specified string.
 CALLING SEQUENCE:
	flt_clean, StrIn, FmtIn, StrOut, FmtOut, /nocheck
 INPUTS:
	StrIn		character string (usually a record read from file)
	FmtIn		format to be matched against string
 OPTIONAL INPUTS:
	/nocheck	see procedure
 OUTPUTS:
	StrOut		reduced character string (see procedure)
	FmtOut		reduced format; = '()' if the input format does not
			match the input string
 OPTIONAL OUTPUTS:
	StrCrumbs	string array containing the discarded portions of the
			input string
	NumCrumbs	# elements in StrCrumbs
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	InitVar
 CALLED BY:
	flt_read
 PROCEDURE:
	The input format is searched for the character descriptor 'A'. All 'A'
	occurrences are removed from the format, and the corresponding
	substrings are removed from the input string.
	The reduced output format will contain only numeric format desciptors
	(I,F,D,E).
	If the input string does not adequately match the format,
	string '()' is returned as output format. This occurs if:
 >	If the string is longer or shorter than the length implied by the
	input format, i.e. the lengths must match exactly
 >	(Only if the keyword NoCheck is not set)
	If the substring for an 'A' descriptor contains a numerical digit (0..9)
 MODIFICATION HISTORY:
	MAY-1994, Paul Hick (ARC)
	SEP-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Bug fix. If format would end with a string (e.g. A3) then this would not
		be cleaned up properly.

 NAME:
	flt_format
 PURPOSE:
	Simplifies a format specication as produced by flt_format
 CATEGORY:
	gen/idl/util
 CALLING SEQUENCE:
	out_ftm = flt_format( in_fmt )
 INPUTS:
	in_fmt		scalar; type: string
					any comma-separated list of format specifiers
					(the outer enclosing brackets are optional, but
					there should be no internal brackets)
 OUTPUTS:
	out_fmt 	scalar; type: string
					more compact list of format specifiers
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	where_common
 CALLED BY:
	flt_string
 RESTRICTIONS:
	The algorithm used tries to find recurring groups of format
	elements, but is somewhat heuristic.
 PROCEDURE:
	The format spec set up by flt_string only takes into account
	immediately neighbouring format specifies, i.e. instead
	of I4,I4,I4 the format will say 3I4. This function looks for
	more complicated repetitions in the flt_string format, e.g
		str = 'I4,I2,F6.2,I2,F6.2,I3,I4,I2,F6.2,I2,F6.2,I3,I6,I1,I1'
		print, flt_format(str)
		2(I4,2(I2,F6.2),I3),I6,2I1
 MODIFICATION HISTORY:
	SEP-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	flt_read
 PURPOSE:
	Read 2D float array from ASCII file
 CATEGORY:
	I/O
 CALLING SEQUENCE:
	FUNCTION flt_read, InFile, Array		, $
		nx				= NX				, $
		ny				= NY				, $
		exponent		= exponent			, $
		stopboost		= stopboost 		, $
		header			= header			, $
		atleast 		= atleast			, $
		silent			= silent			, $
		NoCheck 		= NoCheck			, $
		timer			= timer 			, $
		fmts			= fmts				, $
		errormessage	= errormessage		, $
		crumbs			= Crumbs			, $
		skipfmt 		= skipfmt			, $
		comments		= Comments			, $
		usefstat		= UseFSTAT			, $
		double_p		= double_p			, $
		delay			= delay 			, $
		padvalue		= padvalue			, $
		xfora			= xfora 			, $
		bad 			= bad				, $
		modify_format	= modify_format 	, $
		mask_string 	= mask_string
 INPUTS:
	FILE		char	name of ASCII file
 OPTIONAL INPUTS:
	nx=NX		1st dimension of output array Array (if omitted
				the number of elements in the 1st record is used)
	ny=NY		2nd dimension of output array Array (if omitted NY is
				set to the numbers of records in the file)
	atleast=atleast	only records with at least 'atleast' numbers in them are
				accepted
	/exponent	the records read from FILE are checked for exponents
				(see flt_string procedure)
	/stopboost	only the first NY records are read
	/nocheck	reduces double-checking in flt_clean
	/skipfmt	analyze each record with flt_string, i.e. do NOT try
				the accumulated formats used to read previous records
	mask_string=mask_string
				scalar; type: string
					see flt_string.
	/modify_format
				activates a call to flt_format in all calls to
				flt_string. This shortens the format specifiers returned
				in keyword fmts.

				The reason for introducing this keyword is that there
				apparently is a limit on the length of format statements.
				E.g. if a file was written with format
					(I1,4F7.2,I4,183(I8,F7.2))
				then flt_read without the /modify_format keyword will try
				to read it with a really long format with 183 pairs of
				I8,F7.2 in it. The long version of the format causes an
				error when it is used in a read/write statement.
				However the short version also has a problem when it is
				used to read the whole file with a single read statement.

				While
					readf, iu, format='(F6.1,F10.1,F7.2,F10.1,F7.2)', tmp
				works correctly, the shorter version
					readf, iu, format='(F6.1,2(F10.1,F7.2))', tmp
				results in an error (IDL 6.0 and 6.1beta on Linux).
				This change in format is exactly what /modify_format
				accomplishes. No error occurs when the latter format is
				used to read the file record by record. 
	silent=silent
				scalar; type: integer; default: 0
				controls display of informational messages.
				Set silent=-1 to generate lots of messages
	/timer		displays timer information (testing purposes only)
	/double_p	if set then a double precision array is returned
					(default: single precision)
 OUTPUTS:
	RtnVal		0: some error occurred (check 'errormessage')
				1: file properly read
	Array		array[n,m]; type: float or double
				2D array of floating point numbers
				if something goes wrong Array = -1 is returned
	Crumbs		string	2D array containing the character substrings
				not converted into numbers
				This array will be complete only if /skipfmt is set
				(processing all records separately). If skipfmt is not
				set only then usually only the crumbs for the first
				record is returned.
	errormessage	= '' (null string) if the file is properly read
				= string describing error is something goes wrong
 OPTIONAL OUTPUT PARAMETERS:
	NX,NY		dimensions of Array
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	BadValue, InitVar, IsType, boost, destroyvar, do_file, flt_clean, flt_string
	gunzip_file, hide_env, stopwatch
 CALLED BY:
	InsituTimeSeries, ReadSynopticMap, RemoteView_CMEDensity, RemoteView_Colors
	RemoteView_rgbo, even_light_figures, img_read, jpl_test, mpc_eph, nso_fe_read
	nso_fe_start, smei_frm_drive, smei_frm_path, smeidb_mounted, vu_header
	vu_planarcut, vu_read, wso_read
 COMMON BLOCKS:
	common flt_read_common, old_time
 RESTRICTIONS:
	For each record in the file all formats are tried that were established
	from preceding records. If the record can be read successfully with
	one of these formats than the result is accepted and flt_string is not called
	to analyze the record. This depends on IDL returning an error when a
	record does not fit the record. However, IDL is too tolerant about matching
	formats to strings resulting in wrong results, e.g.
		x = fltarr(2)
		reads, '123,456', format='(I2,1X,I3)', x
		print, x
			12.0000  0.00000
	I.e. no error is generated !!! For uniformly formatted files this is
	usually not a problem. But for irregularly formatted files this pitfall is
	best avoided by setting the /skipfmt keyword.
 PROCEDURE:
 >	Empty records and records starting with a semi-colon (;) are ignored
 >	The function flt_string is used to convert a record read from FILE as
	a string into a floating point array
 >	Only the first NX numbers of each record are stored in subsequent rows
	of Array. NX is explicitly given as input or, if omitted, is set equal
	to the number of elements in the first record of FILE
 >	If less than NX numbers are found in a record, the corresponding
	row in Array is padded with zeros.
 >	A buffer array of size NX by NY is initialized before reading
	the file, where NY is explicitly input or set to # records in the file.
	If FILE contains more than NY records, records following record NY are
	appended to Array by the 'boost' procedure (this is slow for big arrays)
	unless the keyword /stopboost is set.
 MODIFICATION HISTORY:
	OCT-1992, Paul Hick (UCSD/CASS)
	FEB-1995, Paul Hick (UCSD/CASS), added the 'crumbs' option
	MAR-2000, Paul Hick (UCSD/CASS), added /double_p keyword
	JAN-2002, Paul Hick (UCSD/CASS), added /status keyword
	NOV-2002, Paul Hick (UCSD/CASS), added padvalue keyword
	MAY-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		More strict interpretation of /skipfmt: if set then every record
		is processed separately by flt_string. No attempt is made anymore to read
		read more than one record at a time with a single format.
	JUN-2003, Paul Hick (UCSD/CASS)
		Added option to process .gz files transparently
	OCT-2003, Paul Hick (UCSD/CASS)
		Added 'bad' keyword.
	SEP-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added /modify_format keyword.

 NAME:
	flt_string
 PURPOSE:
	Extract numbers from string and put them in floating point array
 CATEGORY:
	String processing
 CALLING SEQUENCE:
	FUNCTION flt_string, INPUT				, $ 
		exponent		= exponent			, $ 
		xfora			= xfora 			, $ 
		double_p		= double_p			, $
		strvec			= StrVEC			, $ 
		fmt 			= FMT				, $ 
		numfmt			= NumFMT			, $ 
		lenfmt			= LenFMT			, $
		strcrumbs		= StrCRUMBS 		, $ 
		numcrumbs		= NumCRUMBS 		, $ 
		lencrumbs		= LenCRUMBS 		, $
		modify_format	= modify_format 	, $
		mask_string 	= mask_string
 INPUTS:
	INPUT			string (e.g. 89/1/12)
	/exponent		if set and nonzero, exponentials of type 'D' and 'E' are
					also interpreted
	/double_p		if set then a double precision array is returned
					(default: single precision)
	/xfora
 OPTIONAL INPUTS:
	/modify_format	if set, the format returned in 'fmt' is run
					through the function flt_format to
					shorten the format string.
	mask_string=mask_string
					scalar; type: string
						string of '0' and '1' with '1' in chars that
						are explicitly NOT part of a number.
						(the char will be part of an A or X format in the
						resulting format specifier returned in 'fmt')
 OUTPUTS:
	RtnVal			floating array (e.g. [89,1,12])
	StrVEC			string array (array FltVEC before conversion to float)
	FMT				format string matching the input string
	NumFMT			# valid numbers located in the input string
	LenFMT			# chars taken up by the NumFMT numbers in the input string
	StrCRUMBS		string array with part of input string not translated
					into numbers
	NumCRUMBS		# elements in StrCRUMBS
	LenCRUMBS		# total length of all elements in StrCRUMBS summed
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	BadValue, InitVar, boost, flt_format
 CALLED BY:
	flt_read, grd_read, htmd_cat, nagoya_glevel, nso_fe_read, qImage_cw_smei_frm
	qsmei_sky_Pick, smei_base_testcase, smei_frm_drive, smei_orbits_stat
	smei_sky_get, smei_sky_read, smei_time, smeidb_mounted, vox_read, vu_check
	vu_header, vu_quick_movie, vu_set_header_entry, vu_set_time_entry, vu_vox_read
	wso_write
 PROCEDURE:
	Checks each character against a list of valid characters. Processing
	characters sequentially going from first to last, the largest possible
	substrings representing valid numbers are extracted. Only integer
	exponents are accepted (if the keyword /exponent is set).
 MODIFICATION HISTORY:
	Written Jan 1989 by DMZ (ARC)
	Converted to V2 Dec 1990 by DMZ (ARC)
	OCT-1990, Paul Hick (ARC), Expanded to accept exponentials,
	?-1993, Paul Hick (UCSD), Added construction of format specifiers
	FEB-1995, Paul Hick (UCSD/CASS), Added option to pull out the substrings
		not translated into numbers
	MAR-2000, Paul Hick (UCSD/CASS), added /double_p keyword
	JUL-2002, Paul Hick (UCSD/CASS)
		Fixed problem for dealing with formatting of peculiar exponents.
		E.g. '(1.dat)' would return format '(D2.-4,A3)'. Now it returns '(D3.0,A2)'
	MAY-2004, Paul Hick (UCSD/CASS)
		Changed strmid(var,2,999) to strmid(var,2)
		(extracts to end of string 'var')
	SEP-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added call to flt_format to shorten the format specifier returned in FMT

 NAME:
	FPE_GRID


 PURPOSE:
	Add a grid of elongation and position-angle to a SMEI Fisheye
	plot.


 CATEGORY:
	utils


 CALLING SEQUENCE:
	fpe_grid[, delong, dpa]


 OPTIONAL INPUTS:
	delong	int	The step in elongation angle.
	dpa	int	The step in position angle.


 KEYWORD PARAMETERS:
	/label			If set, then label the grid.
	charsize	Float	Set a size for the labels (ignored if
				label is not set.
	max_elongation	float	Set the largest elongation to show
				(default=135)
	Any key accepted by PLOTS will be passed through.


 RESTRICTIONS:
	Steps will be rounded to the nearest whole degree


 MODIFICATION HISTORY:
	Original: 13/2/04; SJT
	Add labelling support: 16/2/04; SJT

 NAME:
	FrameMoments
 PURPOSE:
	Calculate average and standard deviations sigma
 CATEGORY:
	Statistics
 CALLING SEQUENCE:
	FrameMoments, Frames, sumwidth=SumWidth, Average, Sigma
 INPUTS:
	Frames		3D-array, any type, but should be float to use !VALUES.F_NAN
					to indicate missing pixels.
					stack of 2D frames combined in 3D array; the last dimension counts
					the number of frames
					Frame elements set to the value !VALUES.F_NAN are ignored
 OPTIONAL INPUT PARAMETERS:
	sumWidth	scalar, type integer, default: 3. (single frame) or 1. (multiple frames)
					defines a box of sumwidth by sumwidth pixels
					(should be ODD; argument is passed to the IDL 'smooth' function).
	/exclude	if set, the statistical moment for each pixel in the Frames
					array is calculating, excluding the pixel itself
 OUTPUTS:
	Average, Sigma
				arrays of same structure as Frames, type float
					mean, standard deviation
					If /exclude is not set all frames in the Average and Sigma
					arrays will be identical
 CALLS: ***
	ArrayLocation, SuperArray
 CALLED BY:
	Find2DGlitch
 PROCEDURE:
	For each pixel the statistical moments are calculated by summing over
	sumwidth^2 x (# frames) pixels.
	The summing needed to calculate the statistical moments is done using
	'total' (to sum over frames) and 'smooth' (to sum over sumwidth^2 pixels in each frame)
 MODIFICATION HISTORY:
	OCT-1998, Paul Hick (UCSD/CASS; pphick@ucsd.edu)