How to work with the image objectLast update: March 31, 2017
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.
1. Create an image
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:
These parameters are used for generating single images as well as image cubes. To generate a single image, follow this example:
o->set, im_time_interval='2004/08/02 '+['04:54:52','04:55:08']
(set any other image parameters you want here)
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:'+ $
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
o->set, im_time_interval='20-feb-02 11:06:'+ $
b. Then set the energy intervals for the images:
Use any of these three methods:
Specify the contiguous energy bands for each image. The
following will do three images in energy bands 10-20, 20-30, and 30-40
o->set, im_energy_binning = [10,20,30,40]
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 these five
bins: 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 by those commands 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). 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 )
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.
d. Generate the images
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 that the default is that, although all the images were computed, the data variable will now contain the first image in the cube. See Section 4. below for retrieving all images in the cube.)
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:
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()
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:
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:
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 as you set them.
ptim, o->get( /im_time_interval )
print, o->get( /im_energy_binning)
Unlike the control parameters, most 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
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 )
print, o->get( /binned_n_event )
The get for image_atten_state will
return an array of values, one for each time/energy bin in the cube. The
get for binned_n_event will return an array for 9 values (for each
detector) 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,
print, o->getaxis(/energy, /edges_2)
You can also get the array of x and y
values for each pixel:
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
This returns an array of structures, one for each image in the cube. Or you can retrieve any of those parameters for a single image or for all images as described above. e.g.
energy_bands_used = o->get(/im_eband_used)
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
For example after setting
use_single_return_mod=0 and use_all_info_params=1, you can retrieve the
chi square value for each CLEAN image from a FITS :
To plot the image that is currently selected with e_idx and t_idx in a simple plot window or in a plotman window:
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:
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
/time, e_idx = 2
or set e_idx to the index wanted before starting the movie:
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:
/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]
To scale each image to itself, rather than to all the images in the movie, use the /noscale keyword:
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,
You can also use the movie GUI, to make it easier to set these options:
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 square 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 in a new window. 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:
/zoom, /plotman, e_idx=e_idx, t_idx=t_idx
print, e_idx, t_idx
|im_time_interval||Defines time interval(s) for image(s)|
|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)|
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,
André Csillaghy email@example.com and Kim Tolbert firstname.lastname@example.org