How to work with the image object
Last update: July 29, 2005
This document describes how to use the RHESSI image object software. It focuses on the new image cube capabilities introduced in March 2005. Image cubes are 4-dimensional arrays containing images in multiple time and energy intervals (in fact 4-dimensional cubes are called tesseracts). The new image object can generate single images or image cubes, and can read and write the image(s) and their associated parameters in an image FITS file. A powerful feature of the new software is that all of the image cube information is stored in the image object; when you generate images or read an image cube FITS file, you can retrieve any or all of the images and associated parameters for viewing, analysis, or movie-making.
There are several new image object parameters to handle image cube features. The new parameters should be used for both single or multi-image cubes, however the old parameters will continue to work for single images. Also, the format of the image FITS file written by the new image object was improved. The files are now more compact and can be read faster. The new image object can also read the old version of the FITS files.
The RHESSI GUI was modified to take advantage of the new image cube capabilities of the image object. This document explains how to use the IDL command line to generate images and read and write image FITS files; refer to Changes in the RHESSI GUI and RHESSI Imaging Widget for updated documentation on the Image GUI.
Contents:
1. Create an image object
2. Generate a single image
3. Generate an image cube
a. Set time intervals
b. Set energy bands
c. Check settings
d. Generate images
4. Read the image data
5. Write and read RHESSI image FITS files
a. Writing an image cube FITS file
b. Reading an image cube FITS file
6. Read the control and info parameters
7. Plot the images
8. Show a movie of the images
9. Display all images at once
10. Summary of new image parameters and methods
Note: the parameter values shown on the right side of the equal sign below are examples used to illustrate the input formats. Replace the values by whatever your own values are.
Many parameters control the generation of images by hsi_image(). There is a
comprehensive list in the
HESSI
Data Object Parameter Table. In this document we focus on the
discussion of the time interval and energy binning parameters. The main
parameters that control the image generation in time and energy are:
im_time_interval
im_energy_binning
These parameters are used for generating single images as well as image
cubes. To generate a single image, follow this example:
o=hsi_image()
o->set, im_time_interval='2004/08/02
'+['04:54:52','04:55:08']
o->set,
im_energy_binning=[12,25]
(set any other image parameters you want here)
data=o->getdata()
1st method: Specify the contiguous time intervals
for each image. The following will do five images in 4-second intervals:
o->set,
im_time_interval='20-feb-02
11:06:'+ $
['00','04','08','12','16','20']
2nd method:
Specify the overall time interval, and the time binning (duration in seconds)
per image. In this method, im_time_interval must be a 2-element array;
im_time_bin has no effect if im_time_interval has more than two elements. The following will divide im_time_interval
into as many 4-second bins as fit (in this case four).
o->set,
im_time_interval='20-feb-02 11:'+ $
['06:00','06:18']
o->set,
im_time_bin = 4
3rd method: Specify the time interval for
each individual image. This is an extension of the first method.
Note that the time intervals don't have to be contiguous. The following
will do three images in non-contiguous intervals:
o->set,
im_time_interval='20-feb-02
11:06:'+ $
[['00','04'],
$
['08','12'], $
['16','20'] ]
b. Then set the energy intervals for
the images:
Use any of these three methods:
1st method: Specify
the contiguous energy bands for each image. The following will do three
images in energy bands 10-20, 20-30, and 30-40 keV.
o->set,
im_energy_binning =
[10,20,30,40]
2nd method: Specify the
energy band for each individual image. This is an extension of the first
method. Note that the energy bands don't have to be contiguous. The
following will do three images. The energy bands 6-10 and 15-20 keV are
omitted.
o->set,
im_energy_binning=[[3, 6],
$
[10, 15], $
[20, 25] ]
3rd method: Use the
energy binning codes to reference the predefined energy binning schemes.
The following uses binning code 2, which is 20-30, 30-40, 40-50, 50-100, 100-200 keV. The list of
available predefined energy binning schemes can be found here
o->set,
im_energy_binning = 2
c. Check the values of the parameters:
You can check your time and energy binning input with:
ptim,
o->get(
/im_time_interval )
print,
o->get(
/im_energy_bin )
The values shown here are the values that have been
entered. This might not correspond to the values that are used to
generate the images, for instance when im_energy_binning is set to a scalar (predefined energy bins), or when im_time_bin is
used. To check the actual values that will be used to generate the images, you can
use the getaxis function:
ptim,
o->getaxis( /ut, /edges_2 )
print,
o->getaxis( /energy, /edges_2 )
Alternatively, you can also use the energy_band and time_range
parameters to read the used ranges. If the parameter use_single_return_mode
(discussed in more details later) is set to
1 then you will get the time and energy intervals for the single image at time
index t_idx, and energy index e_idx. For example, to see the times and
energies for time index 1 and energy index 2:
o->set,
t_idx = 1, e_idx =2
ptim,
o->get( /time_range )
print,
o->get( /energy_band )
If use_single_return_mode
is set to 0, the result will be the intervals for all images, which will be
identical to what getaxis returns.
There are many control and info parameters associated with an
image cube. Check below in "Read the info parameters" to see how to get
parameter values for each image in the cube.
After setting any other image generation parameters you want (e.g. image_dim, pixel_size, image_algorithm), use getdata to generate the images:
data = o->getdata()To monitor the progress of the image cube generation, you can set the following: progress_bar (displays a progress bar that allows you to cancel the cube generation), verbose (prints additional text in the IDL output log), and/or show_images (shows each image as it's generated in a small plot window) before calling getdata:
o->set, /progress_bar, /verbose, /show_images
Note about compatibility with
previous versions of hsi_image:
The previous version of hsi_image, which could not generate image cubes, used the following parameters:
obs_time_interval
time_range
energy_band
The parameters obs_time_interval
and time_range are
replaced by the
single parameter im_time_interval.
The latter allows you to define multiple time intervals, and, obs_time_interval
becomes the minimum and
maximum values of im_time_interval.
The parameter time_range allowed
you to define the time range within
an obs_time_interval. This is
simplified now since im_time_interval
is
used for both.
The parameter energy_band
is replaced by the parameter im_energy_binning,
which allows you to define multiple energy bins.
The new parameter names were designed to be similar to the equivalent parameters
of the light curve and spectrum objects (e.g. sp_energy_binning,
sp_time_interval). To generate image cubes, you must use the new parameter
names. To generate single images, you can use either the old parameter
names or the new ones, however we recommend switching to the new parameter names
for everything. The old names are preserved mainly so that old scripts
will continue to work.
Note: Even if you use the new parameter names, the parameters time_range and energy_band can still be used to retrieve time and energy bin information as described below.
To check the current values of the energy index and time index (note - you cannot combine the two gets in one call):
print, o->get(/e_idx), o->get(/t_idx)
To retrieve the entire image cube at once, change the return mode
before
retrieving the data:
o->set,
use_single_return_mode = 0
data =
o->getdata()
o->fitswrite
If the image cube has already been generated, the images will be written to the FITS file. Otherwise this command will generate the image cube and write the file. You will be prompted for the name of the output file.
Alternatively, you can specify the output file name before calling fitswrite
or GetData by setting the im_out_fits_filename parameter.
o->set, im_out_fits_filename= 'yourfile.fits'
If im_out_fits_filename is defined to a non-blank string before you call GetData, the
o->GetData() call will automatically write the FITS file while generating the
cube.
The im_out_fits_filename parameter persists once it's set. To unset it, set it to a
blank string. If you want to specify an output file name that applies to
just one call to fitswrite, use:
o->fitswrite, this_out_filename='yourfile.fits'
By default, the CLEAN algorithm info maps (clean_residual_map, clean_component_map, etc) are not stored in the FITS file because they significantly increase the size of the file and the time it takes to read it. However if you want the maps to be stored, you can set the full_info parameter to 1:
o->set, /full_info
b. To read an image cube FITS file:
o->set,
im_input_fits =
'yourfile.fits'
data =
o->GetData()
This will read an image cube FITS file generated
by the
fitswrite method of the hsi_image object. It will set all the control
parameters and info (not quite all, but the key ones) parameters into the object
as though we had just created the image cube. As described above, use the
use_single_return_mode parameter and t_idx, e_idx to control whether calls to
get and getdata return information for a single image or all images.
As long as im_input_fits is set to 'yourfile.fits', everything retrieved by calls to get and getdata is information that was stored in the file. You may not change any control parameters or do any reprocessing. To convert back to 'raw' mode (i.e. using the Level-0 raw files as input, and being able to change control parameters) set im_imput_fits to a blank string:
o->set, im_input_fits = ''
Note that all of the control parameters that were set when you read the FITS file are still set. However, now you are allowed to change control parameters, and a getdata will reprocess the images from the Level-0 data files. If you want to reinitialize the control parameters to default values, destroy the object and start with a fresh object.
print, o->get( /pixel_size )
print, o->get( /xyoffset )
The time and energy binning control parameters can be retrieved in the same way, but you must remember that they define the time and energy binning, but are not necessarily the times and energies actually used (e.g., if you used im_time_bin, then im_time_interval shows the limits of the time, not the intervals themselves):
ptim, o->get( /im_time_interval )
print, o->get( /im_time_bin )
print, o->get( /im_energy_binning)
Unlike the control parameters, many of the info parameters are different for
every image. Some of the obvious examples are the time interval and
energy band, attenuator state, total number of counts, and output parameters
from the image cleaning algorithms. By default, the object returns
information for a single image. You select which image by setting the
energy and time indices (e_idx, t_idx) before retrieving information. For
example, to print the time range, energy band, and number of counts for the
image with energy index 2 and time index 3:
o->set,
e_idx =2, t_idx=3
ptim,
o->get( /time_range )
print,o->get( /energy_band )
print, o->get( /binned_n_event )
To retrieve info parameters for all images in the cube, change the return mode
as we did for the getdata call. For example, to print the attenuator state
for every image in the cube:
o->set,
use_single_return_mode = 0
print,
o->get( /image_atten_state )
In that example, if the parameter you're retrieving had the same value for every image, the get will return a single instance of the parameter (e.g. if the attenuator state for all images in the cube was 0, the example would print a single 0). If the parameter value is not the same for every image in the cube, then the get will return an array of values, one for each time/energy bin in the cube.
The getaxis function always returns all time intervals and energy bands for the entire cube, regardless of the value of use_single_return_mode:
ptim, o->getaxis( /ut, /edges_2)
print, o->getaxis(/energy, /edges_2)
Note the following
difference when reading info
parameters from a FITS file:
When retrieving information from an image cube FITS file, there is one
additional complication. When the FITS file was being written, all info parameters associated with
the images were available and were written to the file. However, the
complete set of info parameters for all images represents a large amount of
information. Reading the entire file can be time-consuming, and most of
the info parameters are not needed for most applications. For this reason,
a summary of the primary info parameters is included in the FITS file.
This summary info extension can be read quickly and provides the info parameters
which are sufficient for most applications. By default, only the summary
info extension is read. You can see what parameters are in the summary
info extension by:
help, o->get( /summary_info), /struct
or you can retrieve any of those parameters for a single image or for
all images as described above.
If you want to force reading all of the info parameter extensions so that all
the info parameters for all images will be available, set the
use_all_info_params keyword:
o->set,
use_all_info_params = 1
To plot the image that is currently selected with e_idx and t_idx in a simple plot window or in a plotman window:
o->plot
o->plotman
Or to plot a specific image without changing e_idx and t_idx, in this case energy index 3, time index 2:
o->plot, 3, 2
o->plotman, 3, 2
Or to choose which energy band and time interval to plot from a list widget:
o->plot, /choose
o->plotman, /choose
Many additional plot keywords can be used, e.g., log, limb_plot, xrange, yrange, legend_loc, positive_only, negative_only, drange.
To show a movie in time for the energy band currently selected with e_idx:
o->movie, /time
o->movie,
/time, e_idx = 2
or set e_idx to the index wanted before starting the movie:
o->set, e_idx = 2
o->movie, /time
To show a movie in time integrated over all energies:
o->movie,
/time, /integrate
Or to show a movie in time for the time intervals 4, 5, 6, and 7 integrated over energy bands 2, 3, and 4:
o->movie, /time, t_idx=[4,5,6,7],
e_idx=[2,3,4]
Similarly, to show a movie in energy, make the same calls to movie, but use the
/energy keyword. For example, to show a movie in energy integrated over
time intervals 1, 2, and 3:
o->movie,
/energy, t_idx=[1,2,3]
The default movie style is xinteranimate (the IDL interactive image animator). You can also select /java or /mpeg to generate Javascript or MPEG movies. Use the size keyword to specify the size of the movie in screen pixels, and the table keyword to select the IDL color table to use. Setting /noscale will disable scaling each image to the minimum/maximum of the entire movie.
Java example, using color table 5, movie size of [400,400] (JPEG files and Javascript HTML file will be written in the directory specified by dir_java under the current directory, default for dir_java is 'java_dir'):
o->movie, /energy, /java, dir_java='myflare_java', size=[400,400], table=5
MPEG example (output file name can be specified by file_mpeg keyword), don't scale images:
o->movie, /time, /mpeg, file_mpeg='mymovie.mpeg',
/noscale
You can also use the movie GUI, to make it easier to set these options:
o->movie_gui
o->panel_display
To exit this panel
display, click either mouse button in the window. You can specify the size of
the images with the single_im
keyword (the size of each little image will be single_im x single_im pixels). The panel display can also be used interactively to zoom into
single images:
o->panel_display,
single_im=100, /zoom
When /zoom is set, clicking the left mouse button on an image will display a
larger plot of that image.
To exit the panel display, click the right mouse button.
To send the single image to a plotman window instead of simple plot window, use the /plotman keyword with /zoom:
o->panel_display, /zoom, /plotman
And to return the indices of the image you've zoomed in on, use the e_idx, t_idx output keywords:
o->panel_display, /zoom,
/plotman, e_idx=e_idx, t_idx=t_idx
print, e_idx, t_idx
Parameters:
| im_time_interval | Defines time interval(s) for image(s) |
| im_time_bin | Divides im_time_interval into bins of this width (optional) |
| im_energy_binning | Defines energy band(s) for image(s) |
| t_idx | Current time index (starting from 0) |
| e_idx | Current energy index (starting from 0) |
| im_input_fits | Input image FITS file name |
| im_out_fits_filename | Output image FITS file name |
| full_info | Set to 1 to write CLEAN intermediate info arrays in FITS file (default is 0) |
| use_single_return_mode | Set to 0 to return data or params for all images (default is 1) |
| use_all_info_params | Set to 1 to read all info params from image FITS file (default is 0) |
| progress_bar | Set to 1 to see progress bar while making images (default is 0) |
| verbose | Set to 1 to see more text in IDL output log (default is 0) |
| show_images | Set to 1 to plot each image as it's generated (default is 0) |
Methods:
o -> plot [,e_idx, t_idx, /choose ]
o -> plotman [, e_idx, t_idx, /choose ]
o -> movie [, /energy, /time, t_idx=t_idx,
e_idx=e_idx, /integrate, $
/mpeg, file_mpeg=file_mpeg, $
/java, dir_java=dir_java, $
/noscale, size=size, table=table ]
o -> panel_display [, single_im=single_im, /zoom,
/plotman, $
e_idx=e_idx, t_idx=t_idx ]
o -> fitswrite [,
this_out_filename=this_out_filename ]
o -> chooser, energy_indices, time_indices
André
Csillaghy
andre.csillaghy@fhnw.ch
and Kim Tolbert kim.tolbert@nasa.gov
July 2005