NAME:
	AlignHeliosphere
 PURPOSE:
	For a given set of 3D heliospheric matrices covering different ranges of
	heliographic longitudes (or, equivalently, Carrington variables) 'align'
	all matrices so they start and end at the same heliographic longitude,
	interpolating linearly where necessary.
 CATEGORY:
	sat/idl/util
 CALLING SEQUENCE:
	result = AlignHeliosphere(ff, dOff)
 INPUTS:
	ff			array[n,l,m,k] or array[n,l,m,d,k]; type: float
					3D heliospheric matrix specified on a heliographic grid
					n: # heliographic longitudes (can cover more than one rotation)
					l: # latitudes
					m: # heliocentric distances
					d: (optional) # data types (e.g. k=2 if velocity and density
						are stored in one array)
					k: # matrices to be aligned (usually this represents time)

	dOff		array[k]; type: float
					offset between k matrices in grid spacings
 OPTIONAL INPUT PARAMETERS:
	aligneps=aligneps
				scalar; type: float
					if dOff is less than eps from an integer number of grid spacings
					than it is rounded to the nearest integer. This reduces the
					alignment to a cyclic shift (bypassing the call to the IDL
					interpolate function). This should be faster.
	/nowrap 	by default the alignment is done by applying a mod 360 operation.
					If /nowrap is set this is suppressed and the missing part of a
					map after alignment is set to BadValue(0.0)
 OUTPUTS:
	result		same as input 'ff', but now aligned
 INCLUDE:
	@compile_opt.pro			; On error, return to caller
 CALLS: ***
	BadValue, InitVar, destroyvar
 CALLED BY:
	RemoteView_Init_FOV, vu_mean
 PROCEDURE:
	This procedure was written to deal with (a sequence of) 3D matrices (longitude, latitude,
	radial distance). For a matrix with only longitude, or only longitude and latitude, this
	procedure can be used after inserting a dummy dimension of 1 for the missing coordinate(s).
 MODIFICATION HISTORY:
	APR-2001, Paul Hick (UCSD/CASS)
	JUL-2002, Paul Hick (UCSD/CASS)
		Allowed for special case of 3D array ff[n,l,m] (i.e. k=1 but without degenerate dimension)
	NOV-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added /nowrap keyword

 NAME:
	AngleRange
 PURPOSE:
	Map angles into the range [0,360) or (-180,+180]
 CATEGORY:
	sat/idl/toolbox/math
 CALLING SEQUENCE:
	R = AngleRange(A, [/pi, /degrees])
 INPUTS:
	Angles			scalar or array; type: any
						angles
 OPTIONAL INPUT PARAMETERS:
	/pi				by default the angles are mapped to [0,360)
					if /pi is set then the angles are mapped to (-180,+180]
	/degrees		if set then in- and output angles are in degrees (default: radians)
 OUTPUTS:
	R				same size and type as input array
						angles mapped to specified range
 INCLUDE:
	@compile_opt.pro					; On error, return to caller
 CALLS: ***
	InitVar, IsType, ToRadians
 CALLED BY:
	AngleUnits, CarringtonT, CarringtonT0, CarringtonVar, ColorSkybox, CvRotation
	EarthSky3DLoc, GeographicInfo, HammerAitoff, MercatorProj, PlotEarthSkymap
	PlotPolarSkymap, RemoteView_CurrentSheet, RemoteView_FOV_Cube
	RemoteView_Init_Matrix, RemoteView_Init_View, big_eph, flat_centerofmass
	jpl_eph, jpl_test, mpc_eph, qvu_draw, smei_ccd2sky, smei_cv, smei_frm_cvhdr
	smei_frm_summary, smei_frm_where, smei_hdr_plot, smei_orient_test, smei_star_fit
	smei_star_stdmaps, smei_zodiac_model, usno_eph, vu_RemoteView, vu_planarcut
	vu_solardisk, vu_vox_write, wso_write
 PROCEDURE:
	The output interval is open on the right side for mapping to [0,360)
	(i.e. 360 is not included).
	The output interval is open on the left side for mapping to (-180,+180]
	(i.e. -180 is not included)
 MODIFICATION HISTORY:
	MAR-2000, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	AngleUnits
 PURPOSE:
	Convert units of angle between radians, degrees, hours, sexagesimal units
	(degrees,arcmin, arcsec, milli-arcsec), and time units (hours,
	min, sec, milli-sec).
 CATEGORY:
	smei/gen/idl/toolbox
 CALLING SEQUENCE:
	FUNCTION AngleUnits,	$
		from_angle		= from_angle 	,	$
		from_radians	= from_radians	,	$
		from_degrees	= from_degrees	,	$
		from_hours		= from_hours	,	$
		from_time		= from_time		,	$
		from_sexagesimal= from_sexagesimal, $
		from_almanac 	= from_almanac	,	$
		to_angle 		= to_angle		,	$
		to_radians		= to_radians	,	$
		to_degrees		= to_degrees	,	$
		to_hours		= to_hours		,	$
		to_time			= to_time		,	$
		to_sexagesimal	= to_sexagesimal ,	$
		to_almanac		= to_almanac 	,	$
		degrees 		= degrees		,	$
		singlesign		= singlesign	,	$
		strings 		= strings		,	$
		html			= html

 OPTIONAL INPUT PARAMETERS:
	from_angle=from_angle
		array; type: any
			units of angles are determined by setting of /degrees
	from_radians=from_radians
		array; type: any
			angles in radians
	from_degrees=from_degrees
		array; type: any
			angles in degrees
	from_hours=from_hours
		array; type: any
			angles in hours
	from_sexagesimal=from_sexagesimal
		array[4,*]; type: any
			angles in degrees, arcminutes, arcseconds, milli-arcseconds
	from_time=from_time
		array[4,*]; type: any
			angles in time measure: hours, minutes, seconds, milliseconds
	from_almanac=from_almanac
		array[4,2,*]; type: any
			array[*,0,*] is angle in time measure (as in from_time)
			array[*,1,*] is angle in sexagesimal units (as in
				from_sexagesimal) in single sign convention (see /singlesign)
	/to_angle
	/to_radians
	/to_degrees
	/to_hours
	/to_sexagesimal
	/to_time
	/to_almanac
			convert input angles to specified units (see from* keywords)
			(for /to_angle the units are determined from the setting of /degrees)

	/singlesign		when angles are input as sexagesimal (usually latitudes)
					or time units (usually right ascensions) then negative
					angles are usually specified with all components negative,
					i.e.
						 AngleUnits(from_sexa=[-10,-30], /to_deg) = -10.5
					Setting /singlesign is used to convert positions from an
					almanac, e.g.
						AngleUnits(from_sexa=[-10,30],/to_deg,/singlesign) = -10.5
					i.e. the sign of the first non-zero entry is applied to
					all subsequent components.

					!!  Note that almanacs may specify a small negative
					!!  latitude as '-0 30 30'. When this string is naively
					!!  read with an I format specifier, then the minus sign
					!!  gets lost and a small positive latitude would be
					!!  obtained. To obtain correct results using this function
					!!  the minus sign must be transferred to the first
					!!	non-zero component, i.e. '-0 30 30' should be entered
					!!  as [0,-30,30]
 OUTPUTS:
	A	array[*] or array[4,*] or array[4,2,*]; type: same as input
			angles converted to requested units
 INCLUDE:
	@compile_opt.pro			; On error, return to caller
 CALLS: ***
	AngleRange, InitVar, IsType, SubArray, SuperArray, ToDegrees
 CALLED BY:
	jpl_test, mpc_eph, qEphem_State, smei_frm_where, smei_star_fit, smei_star_info
	smei_zodiac_model
 PROCEDURE:
 MODIFICATION HISTORY:
	DEC-2002, Paul Hick (UCSD/CASS)
	MAR-2003, Paul Hick (UCSD/CASS)
		Fixed bug in processing of /singlesign keyword
	JUN-2003, Paul Hick (UCSD/CASS)
		Added /fromalmanac and /toalmanac keywords
	OCT-2004, Paul Hick (UCSD/CASS)
		Added /strings keyword. Fixed bug in /totime conversion.
	SEP-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added underscores to from* and to* keywords

 NAME:
	anicenum
 PURPOSE:
	Returns a 'nice' round number close to the input value
 CATEGORY:
	Tricks
 CALLING SEQUENCE:
	R = anicenum(x [,/upper])
 INPUTS:
	x			scalar; type: float
					input floating value
 OPTIONAL INPUT PARAMETERS:
	/upper		if set the input value is rounded up
 OUTPUTS:
	R			scalar; type: float
					'nice' value
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	InitVar, IsType
 CALLED BY:
	PlotEarthSkymap, PlotPolarSkymap, vu_insitucurve
 PROCEDURE:
	Trivial
 MODIFICATION HISTORY:
	JUL-2001, Paul Hick (UCSD/CASS)
	AUG-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added digits and astring keyword

 NAME:
	arg_time
 PURPOSE:
	Converts a time argument to a time structure or Carrington variable
 CATEGORY:
	Tell time
 CALLING SEQUENCE:
	t = arg_time(ut [, /carrington])
 INPUTS:
	ut			array; type: time structure, float or integer
					times to be converted (UT)

					type time structure is interpreted as times in UT
					type float is interpreted as a modified Carrington variable
					type integer is also interpreted as a modified Carrington variable,
						UNLESS all values in the input array are less/equal 12. In
						that case the times are interpreted as a difference with the
						system time in hours.
					if ut is undefined then the system time is returned.
 OPTIONAL INPUT PARAMETERS:
	/carrington		by default the input is converted to a time structure.
				If /carrington is set than a modified Carrington variable is returned.
 OUTPUTS:
	ut			array; type: time structure or modified Carrington variable,
					depending on the setting of keyword /carrington
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	CarringtonT, CarringtonVar, InitVar, IsTime, IsType, TimeSystem
 CALLED BY:
	InSitu, RemoteView_Init_View, qvu_draw, vu_NagoyaSourcemap, vu_RemoteView
	vu_atlocation, vu_earthskymap, vu_filename, vu_get_page, vu_getdata, vu_gettime
	vu_image, vu_insitu, vu_insitu_raw, vu_insitucurve, vu_mean, vu_movie
	vu_nagoyaskymap, vu_new_time, vu_planarcut, vu_quick_movie, vu_set, vu_solardisk
	vu_synopticmap, vu_timeseries, vu_whatis
 PROCEDURE:
	Provides a uniform way to convert times specified as input arguments to functions
	and procedures to either time structures or modified Carrington variables.
 MODIFICATION HISTORY:
	MAR-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	ArrayLocation
 PURPOSE:
	Convert array indices from one-dimensional form (as returned by e.g.
	the IDL 'where' function) to a multi-dimensional index
 CATEGORY:
	Toolbox: generic
 CALLING SEQUENCE:
	Loc = ArrayLocation(Pos [, size=size, dim=dim, onedim=OneDim])
 INPUTS:
	Pos			array[*], array[n,*], type integer
					if /OneDim not set: 1D array of one-dimensional array indices
					if /OneDim set: 2D array of multi-dimensional indices
						each row array[*,i] specifies the values in each of the n
						dimensions for a specific array element
	sizearr=SizeArr
				array; type: long integer
					a size vector, i.e. the output of the IDL 'size' function
					using the target array as input.
	dimension=dimension
				array; type: long integer
					the dimensions of the target array
					This can be specified instead of the full size vector
 OPTIONAL INPUT PARAMETERS:
	/onedim		if set then Pos is interpreted as a multi-dimensional index
					to be converted to a one-dimensional index.
				if not set Pos is a one-dimensional index to be converted
					to a multi-dimensional index
	/zero2one	(only if /onedim NOT set)
					the output is scaled to the range [0,1] in each dimension
 OUTPUTS:
	Loc			array, type long integer
					the converted array indices
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	InitVar
 CALLED BY:
	CarringtonT0, CleanGlitchBox, Find2DGlitch, FrameMoments, GroupPixels
	RGBO_Project, RemoteView_CMEDensity, TimeLInterpol, even_light, gridfill, max_pos
	nso_fe_start, qGlitch_Show, qImage_cw_Where, sgp4_eph, sgp4_tlm, smei_frm_base
	smei_frm_hbar, smei_frm_hbar_inside, smei_frm_property, smei_frm_track
	smei_setup_roi, vu_vox_drawhcs
 EXAMPLE:
	A = indgen(5,5,5)
	L = ArrayLocation([5,6,7],size=size(A))

	results in L = [ [0,1,0],[1,1,0],[2,1,0] ].

	L = ArrayLocation([ [0,1,0],[1,1,0],[2,1,0] ], size=size(A), /onedim)

	results in L = [5,6,7]
 PROCEDURE:
	For a given array of dimension (N1,N2,..,Nn) each element can be addressed
	by specifying a 'multi-dimensional' index [i1,i2,..,in] or by specifying
	a one-dimensional index (as returned by several IDL functions such as where,
	min, max, etc.).
	The information about the target array is specified by providing the output
	of size(Array) as keyword SizeArr (SizeArr[1:n] = [N1,N2,..,Nn])
 MODIFICATION HISTORY:
	NOV-1998, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	arrow3d
 PURPOSE:
	Rudimentary way of plotting a 3D arrow
 CATEGORY:
	Tricks
 CALLING SEQUENCE:
	arrow3d, tail, tip, tiplen=tiplen, tipwid=tipwid
 INPUTS:
	tail	array[3], type: any
				x,y,z coordinates for end of arrow
	tip		array[3], type: any
				x,y,z coordinates for tip of arrow
 OPTIONAL INPUT PARAMETERS:
	tiplen=tiplen	scalar, type: float, default: 0.1*(arrow length)
					length of the arrow tip
	tipwid=tipwid	scalar, type: float, default: 0.1*(arrow length)
					thickness of the arrow tip
	color=color		scalar, type: integer
					color used to fill 'inside' of array tip
	_extra=_extra	extra keywords passed to IDL plots and xyouts command
					(linestyle, thick, charsize, etc.)

	labeltext=labeltext
				scalar; type: string
					label to plotted near axis (usually near the end r1)

	There are two keywords to determine label placement:

	labeldist=labeldist
				scalar; type: int or float
					labeldist is a distance (in data coordinates) along the line from r0 to r1 where the label
					is placed. Since this placement sometime looks messy when a strange 3D transformation
					is in effect, labeloffset
	labeloffset=labeloffset
				array[2]; type: int or float
					adjustment to the position of labeltext in x and y data coordinates
					This is usually used to manually tweak the position determined with labeldist
					(depending on the !p.t matrix the computed position can be awkward).

 OUTPUTS:
	(none)
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	IsType, coord3to2, unitvectors
 CALLED BY:
	plot3darc, plot3dline
 RESTRICTIONS:
	A valid !p.t matrix must be defined
 PROCEDURE:
	Calls to plots and polyfill
 MODIFICATION HISTORY:
	AUG-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)