euv_imtool - IMAGE EUV Image Processing Tool

Version 1.39 - June 21, 2005

Overview

euv_imtool displays and operates upon EUV skymap images. Once an image has been displayed, features such as the plasmapause may be mapped in L-shell vs. magnetic local time or magnetic longitude. Plots of the radial and azimuthal brightness profiles may also be generated. Data from both the feature mapping and brightness plots may be saved for further analysis.

Data input

The program can either read the IMAGE EUV and orbit UDF files directly or read a FITS format EUV image produced by euv_imtool itself (see Output options below). Additionally, FITS files produced by the on-line FITS data request form (http://euv.lpl.arizona.edu/euv/data) may be used as well. Note that beginning with version 1.26, euv_imtool uses revised values for the pixel overlap between cameras and camera-specific plate scales when performing line of sight calculations. If FITS images created before this revision are loaded, the program will issue a one-time warning. For best results, obtain new versions of the FITS data files for the time period of interest.

Prerequisites

The FITS file data input method requires the IDLASTRO package, available from http://idlastro.gsfc.nasa.gov, and EUV skymap FITS format images produced by program euv_imtool.

The UDF data input method requires the following:

The UDFToIDL package is now the default for euv_imtool. If you want to use the LANL udf-dlm developed by Ed Santiago, simple add '/udfdlm' to the command line when starting euv_imtool.

Output options

There are two output formats:

For each output format, there are two menu items in the File menu. The first in each pair saves the information from the image display in the main window, the second saves the contents of the full frame display window (see below for more information on this window).

Line of sight calculations

In order to perform the line of sight calculations, the Earth center position must be interactively set for each image. Automatic centering is difficult due to spin phase jitter and changes in the spacecraft spin vector over time (however, see the section entitled Auto Centering below). To set the center, click the Define Center button, position the mouse cursor at the center of the Earth and click once to set the center. A dashed circle is drawn to aid in centering, and is then left to mark the outline of the Earth for the chosen center.

Once a center is defined, it may be retained when a new image is loaded by clicking the Keep Center? button.

After defining the center, a single mouse click in the display window generates the following line of sight parameters:

Points may be deleted from the set by clicking the right mouse button in the vicinity of the point.

The line of sight calculated quantities may be recorded in an output file for a series of mouse clicks by specifying a file name in the Output file: text box and clicking the Record File button. Each line in the file contains the following items:

(All quantities refer to the point at which minimum L shell value occurred.)

If the Sort by MLT check box is checked, the output file is sorted in increasing magnetic local time, allowing the points to be defined in any order. If not checked, the points are written to the output file in the order in which they were entered. The center may be re-defined at any time before writing the output file, since all quantities are re-calculated as the output file is written. If the Append check box is checked, the points are appended to the recording file. This allows recording measurements from a number of frames into a single output file.

If the continuous check box is checked, the minimum L, magnetic local time, magnetic longitude and pixel average will be displayed continuously as the mouse cursor moves over the image.

Auto Centering

To enable auto-centering, click the auto center check box. The bias drop list adds a bias along the Sun line in the Sun direction. Units of this bias are 0.3 degree pixels corresponding to the pixel size in the main image display window. The center is determined when the data is loaded by correlating an artificial image of the bright ring around the Earth with the EUV image. Note that this is an experimental feature that is still under development.

Image processing operations

Background Subtraction

The background may be subtracted from the currnet image using the Subtract Background menu item. Parameters are entered using an interactive dialog. There are two methods of background removal, depending on the state of the de-banding subtraction check box. If unchecked, the background level is determined by averaging the counts over the rectangular portion of the image specified in the minimum and maximum X and Y input fields (Note that these are 0-based indices). This constant value is subtracted from the entire image. If the de-banding option is chosen, the minimum and maximum X values are ignored, and a background level is determined for each column in the image by averaging over the area specified by the minimum and maximum Y. This type of background subtraction may be used to remove the vertical banding sometimes seen during high noise periods.

Revert Image

The background subtraction may be undone by using the Revert Image menu item.

Dump GSM

The Dump GSM menu item enables dumping the image to a text file containing the following items for each pixel in the original (140x150) pixel image: Points less than 1.05 Earth raddi from the center of the image are omitted in this dump.

Additional Image Display Windows

Zoomed Image Display Window

The Show Zoomed Display button shows a separate window containing a larger (1.5x) version of the displayed EUV image. All operations (background subtraction, data values readouts and line of sight calculations) work the same way in the zoomed window as in the display in the main window. Note that the image center may be defined on either display; an appropriate center for the other display will be used by the program. The button at the bottom of the window toggles the displayed image size between 84x90 and 84x180 degrees. The larger size may be necessary for plasmasphere feature viewing and measurements when the spacecraft is close to the Earth.

Full Frame Image Display Window

The Show Full Frame Display button displays a separate window showing the full (360 by 84 degree) EUV camera frame. Readouts at the bottom of the frame show the data value at the cursor position and the right ascension and declination at the cursor (once the Earth center has been defined). The full frame image will appear only if the data source is UDF or a full-frame FITS image file.

Contour Map Overlays

The Overlay/Remove Contour Map button enables and disables plotting of contour maps on the image display. Currently, 8 levels are drawn, but in the future, more flexibility may be added, allowing the user more control of the contour levels.

Solar Wind Plot Window

The Show/Hide Solar Wind Plot button enables and disable plotting of selected solar wind, IMF and geomagnetic indices in a separate window, centered around the midpoint time of the EUV frame. The required data files (solarwind.dat, kp.dat and dst.dat) must be either in the current directory or in a directory pointed to by an environment variable named SWDATA. If these data files are not found, this button will remain disabled. These files may be obtained from euv.lpl.arizona.edu, in the solarwind directory.

There are a few controls at the bottom of the plot window. The slider adjusts the width (in time) of the plot. The Fixed/Auto button next to the slider toggles between pre-selected plot minima and maxima and auto-scaled plot limits, and the PNG button writes a PNG image file from the solar wind plot window.

2D radial and aziumuthal plots

After the center has been defined in either of the two image display windows, a single mouse click will produce two-dimensional plots in a separate window: an azimuthal plot of brightness vs.magnetic local time and a radial plot of brightness vs. L-shell. This feature may be turned off and on by the Enable (Disable) Radial/Azimuthal Plots button in the main window. Once plotted, the data may be dumped to a text file. Supply a base filename in the text widget at the bottom of the plot window, then press the dump data button. An output file will be generated for each of the two plots, named by appending 'azi' and 'rad' to the supplied base file name. These plots may be produced by clicking in either the main window or the zoom window, but is only supported in the non-expanded zoom window.

Batch FITS and IDL save file production

Batch mode operations enable the mass production of FITS format output files and IDL save files from the UDF data over a range in time. The Set start time... and Set stop time... menu items allow the user to set the start/stop time for the period of interest. The time of the current frame is loaded by default, but any time may be specified. Then selecting the Make FITS file menu item will cause euv_imtool to generate FITS output files for all frames in the specified time period. The Make FITS file (Full Frame) item does the same thing, except that it writes the full 84x360 degree EUV frame into the output FITS file.

IDL save files may be created in a similar fashion, using the Make IDL save file and Make IDL save file (full frame) menu items. The first saves the 140x150 image array corresponding to what is displayed in the image display window. The second saves the full frame (140x600 pixels). Within the save file, array names are based on the image midpoint time year, day of year, hour and minute in the form Eyyyydddhhmm (e.g. E20001450650). The save file itself is named after the first array it contains (e.g. e20001450650.sav).

Use of the '/batchsub' command line parameter causes the background to be subtracted before writing the FITS image or IDL array, using the current background subtraction parameters.

Saving Settings

The Save Settings menu item in the File menu saves some program settings (e.g. the UDF start time and background subtraction settings) that may be re-loaded the next time the program is run. For Mac and Windows platforms, the settings file is called 'euv_imtool.ini' and will be written to the current directory. If this file is found, it will be loaded automatically when euv_imtool starts. On Unix and Linux platforms, the settings file is named '.euv_imtool'. When euv_imtool starts, it first checks the current directory, then looks in $HOME. When the settings are saved, they are written to the current directory only if they were loaded from that directory, otherwise they are saved to $HOME/.euv_imtool.

Compiling and running euv_imtool

The compile_euv_imtool procedure is provided to make sure that all necessary euv_imtool routines are located. It may be run like: 
IDL> @compile_euv_imtool

For convenience, the compiled routines may be saved and restored in a later IDL session: 

IDL> save, /routines, filename='euvimtool138.sav'
...
IDL> restore,'euvimtool138.sav'

Also, note that euv_imtool uses some routines from the IDL examples directory tree, so the examples programs must be installed and included in the IDL search path.

Acknowledgments

Dennis Gallagher provided the original IDL routines that calculate the line of sight and minimum L-shell along that line. Bob King developed an analytic solution for finding the minimum L along the line of sight. This was ported to IDL by Tim Bavaro for inclusion in euv_imtool. Tim Bavaro also contributed the solar wind plot window introduced in version 1.25. Bill Sandel contributed a modified line of sight routine and Leonard Garcia at Goddard Space Flight Center added the contour map overlay capability. The color map selection code was originally written by Martin Wuest at Southwest Research Institute.