7 November 2000

This is the third distribution of the HENA browse tool and is obtained
free of charge by request to the author. YOU MUST CONTACT AUTHOR
BEFORE USING ANY OF THESE PRODUCTS FOR PUBLICATION!!

REQUIREMENTS
============
1. You need to have the UDF archive software and UDF dlm installed, since this
browse tool uses the UDF_KEY, UDF_OPEN, and UDF_READ routines to read
UDF data into IDL.

2. UNIX or LINUX systems.


INSTALLING
==========
In the following '$' before a command means under the linux/unix
prompt and 'IDL>' means under the IDL prompt.

1. $ tar xzfp hena.tgz 
This gunzips and extracts the directory 'hena_browse'. If your
operating system (unix/Sun) does not support the tar z option, first
do

	$ gunzip hena.tgz

then

	$ tar cfp hena.tar


2. In the shell script 'hena' replace the line

	setenv HENADIR /project/image/dacsoft/user/browse/

with the absolute path to the directory where you install this package.

3. It is assumed that all paths to the UDF data and UDF-DLM code are
set. If

	$ echo $UDF_DATA
and 
	$ echo $IDL_DLM_PATH

returns some path(s), chances are that they are already set and you
dont have to do anything. If not, it is a good idea to set those in a
file called, e.g. UDF_DEFINES, and then source that file in your
~/.cshrc or any other appropriate file. Let your system administrator
help you if uncertain.


RUNNING
=======
This browse tool is written in IDL and displays only one window that
allows the user to read UDF data from the HENA imager.

1. Once all requirements are satisfied and the installation is done you
may run the shell script that starts the program by typing

	$ ./hena

while being in the source directory.  (The best way is to put the
shell script in some designated area, such as under /usr/local/, that
you have a path to, so that you can just type 'hena' whereever you
are.)
Or start IDL and type

	IDL> dummy=hena(source=[full path to source dir of this code])

2. The widget is divided into three boxes that allows you to read the
data, browse the data in time and energy, and change the appearance by 
smoothing, setting min and max on colorbar etc.

3. Enter START and STOP times. (If you need to find available data you 
should use the dBAsk tool).

3. Hit "read".

4. The data can be browsed by dragging the sliding bar for "SPIN".

5. The "SPIN SUM" slider can be used to sum over any number of spins.

5. The lower part of the window allows you to control the image
appearance such as min and max on colorbar, log scale, smoothing, and
restricting the image to only the hemisphere. Particularly useful is
the MEDIAN filtering which removes speckled noise and outliers from
the image.

6. THE MENUBAR
	Window->New - Pops up a new window
	
	Window->Print - Allows the user to print or save to a
Postscript file. To print on you local printers YOU MUST FILL IN
CW_PS_PRINTERS.TXT with the unix name of your local printers and
restart idl.
	
	Window->GIF - Creates a GIF file of the current active
window. Produces light images suitable for attaching to emails. Yes,
it will be changed to PNG soon. (WRITE_GIF will not be available in
IDL 5.4)

	Window->Close - Closes the window and returns the user to the
IDL prompt unless this window is a child process of a parent.

	Options->Color table - Launches the XLOADCT to be able to
select from the IDL default colortables.


DESCRIPTION OF IMAGE
====================

Projection - The image is displayed in an azimuthal equidistant
projection. This means that it takes a matrix and wraps it onto a
sphere of the sky (onto surface of a planet is the same but
reflected). The observer is in the center of this sphere looking
outward. The 'poles' (+90 and -90 deg lat) of the grid represent the
spin axis of HENA. The longitudinal direction of the grid is the spin
angle of HENA. This projection corresponds to what a human eye would
see.

Annotation - Limb of the earth with the terminator is drawn. The
dipole field lines for L=4-8 are also visible and are good for
orientating the image on the SM coordinate system. The "S" and the "A" 
represent the sunward and anti-sunward direction in the observer's
frame of reference. The "M" is likewise the direction of the dipole
vector of the Earth.

COMMENTS AND TIPS - Use of the MEDIAN and SMOOTH keywords are
recommend, keeping in mind the coarse resolution of the
instrument. Otherwise the eye tend to project the pixels onto a
plane. The emissions seen are NOT from the equator, solely. It is a 3D 
'glowing' distribution that is dependent on viewing direction. For
example, some emission seem to be originating from inside L=2-3, but
may in fact be emissions from high latitudes.
	
	Low-altitude emissions are the very intense ENA emissions seen
coming off the footprints of the fieldlines of the Earth
sometimes. Especially when the IMAGE is at low angle to the dipole
vector. These are caused by the nearly mirroring
ring-current/plasma-sheet ions charge exchanging with the upper
atmosphere. The neutral exospheric density at these low altitudes
appear almost wall-like to incoming ion that spirals down along the
magnetic field lines. Therefore the ENA intensity will increase almost
as suddenly with decreasing altitude. This low-altitude is also the
lowest point where ions mirror, since it is the charge-exchange
process that determines the altitude when the ions inside the
loss-cone is totally attenuated by the atmosphere. Therefore, the
intensity is also maximized when the line of sight (LOS) cuts the
field lines around 90 deg angle.

	Sometimes, intense emissions are seen when the LOS cuts inside
the loss-cone, i.e. at angles <90 deg. This is an effect from having a
filled, or partially filled, loss cone. For example, when IMAGE is
almost exactly above the north pole, looking down, low-altitude
emissions are sometimes observed to come from the footprints of the
field lines. They then constitute the fraction of PRECIPITATING ions
that have mirrored, coming back up again, and have charge exchanged
with the upper atmosphere.

	The low-altitude emissions are NOT there because they "spend
most time at the mirror points".

	Higher altitude ring-current emissions typically show up
during substorms and storms and start out at the nightside drifting
around, duskward, to the dayside, where they mostly are lost to the
magnetopause.

	Note that a drifting ion population does NOT maintain its
energy, but constant magnetic moment to a fair degree of
approximation. The HENA imager, unfortunately, does not image at
constant magnetic moment, but at constant energy windows. What this
means is that you should not be surprised if you see "localized"
structures being perfectly happy just sitting around, doing nothing,
at some MLT, or, structures appearing and dissappearing. It is all
dependent on the configuration of the magentospheric electric field. A 
good reference is M. Ejiri [JGR, Vol. 83, No. A10, p. 5798, 1978].

	Last comment, BEWARE OF PITCH-ANGLE EFFECTS!

KNOWN PROBLEMS AND RESTRICTIONS
===============================
Please report any problems and SUGGESTIONS to

	pontus.brandt@jhuapl.edu

Mark the subject with "HENA BROWSE TOOL".

1. Have only been tested for linux and unix.

2. Reads maximum 200 spins (400 minutes of data) at a time.

3. Utilizes only HENA 6x6 deg resolution and 6 energy steps. This is
the microchannel plate part of HENA.
