;+
; NAME:
;	ZA2DIST
; PURPOSE:
;       Calculation of horizontal distance from zenith at an assumed
;	height, given observed zenith angle.
; CATEGORY:
;
; CALLING SEQUENCE:
;	RESULT = ZA2DIST( ZA, H [, /DEGREES] [, RADIUS=radius] )
; INPUTS:
;       ZA:     Zenith angle of something, e.g., an emission feature 
;               (defaults to radians).
;	H:	Assumed emission height in km.
; OPTIONAL INPUTS:
;	None.
; KEYWORD PARAMETERS:
;	/DEGREES: If set, ZA is entered in degrees.
;       RADIUS: If specified, gives the local Earth radius (default
;		= 6371.2 km).
; OUTPUTS:
;       RESULT: Horizontal distance (in km) of emission feature
;               from local zenith.  Has the same sign as the input
;		zenith angle.
; OPTIONAL OUTPUTS:
;	None.
; COMMON BLOCKS:
;	None.
; SIDE EFFECTS:
;	None.
; RESTRICTIONS:
;       ZA must be between -pi/2 radians and +pi/2 radians.  H must
;	be positive.
; PROCEDURE:
;	Sine law.
; EXAMPLE:
;	erad=6357.39		; Earth radius appropriate to Eureka, NWT.
;	h=250.			; 250 km assumed emission height
;	za=FINDGEN(141)-70	; Zenith angles from -70 deg to +70 deg.
;       zd=ZA2DIST(za,h,/deg,rad=erad)  ; Calculate the corresponding
;					; off-zenith distances.
; SEE ALSO:
;	DIST2ZA.PRO, RELC.PRO
; MODIFICATION HISTORY:
; 	Written by:	D P Steele, ISR, 12 Oct 1994.
;       Renamed ZA2DIST.PRO on 13 Oct 1994, replacing previous
;	version of so-named .pro.
;-
FUNCTION za2dist,za,h,degrees=degrees,radius=radius

IF N_PARAMS() EQ 0 THEN BEGIN
	doc_library,'za2dist'
	RETURN,-1
	ENDIF

IF N_PARAMS() EQ 1 THEN BEGIN
	MESSAGE,'Supply an assumed height (km).'
	RETURN,-1
	ENDIF

IF MIN([h]) LT 0 THEN BEGIN
    MESSAGE,'Assumed height(s) must be positive.'
    RETURN,-1
    ENDIF

IF KEYWORD_SET(degrees) THEN zar=!DTOR*za ELSE zar=za

IF (MIN(zar,MAX=mxz) LT -!PI/2.) OR (!PI/2. LT mxz) THEN BEGIN
    MESSAGE,'-!PI/2 < zenith angle < !PI/2.'
    RETURN,-1
    ENDIF

IF N_ELEMENTS(radius) GT 1 THEN rad=radius ELSE rad=6371.2

radp=rad+h
ratio=rad/radp
RETURN,radp*(zar-ASIN(ratio*SIN(zar)))
END