How to work with the image object

Last 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.

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.


1. Create an image object:

o = hsi_image()

With this object, you can either generate new images starting from the telemetry data or an eventlist file, or read from an image cube FITS file, containing previously generated images.


2. Generate a single image

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()

 

3. Generate an image cube

The main parameters that control the image cube generation in time and energy are the same as for a single image:
im_time_interval
im_energy_binning

a.  First set the time intervals for the images:
Use either of these two methods:

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 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'] ]

NOTES:


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 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:
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.

 

4. Read the image data

data = o->getdata()

If not yet generated, this will generate the image cube.  Each image in the cube has a time index and an energy index. The time index varies from 0 to the number of time intervals minus 1, and the energy index varies from 0 to the number of energy bins minus 1. By default the variable data will contain the first image in the cube, that is, the image with time index 0 and energy index 0.  The time index and energy index can be changed using the variables e_idx and t_idx.  For example, to retrieve the image with time index 3 and energy index 2:

o->set, e_idx = 2, t_idx = 3
data = o->getdata()

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()

 

5. Write and read RHESSI image FITS files:

a.  To write an image cube fits file:

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.


6.  Read the control and info parameters describing the images

Except for time and energy binning parameters, all control parameters (e.g. pixel_size, xyoffset) are the same for every image in the cube and can be retrieved as they were with the old hsi_image object.  For example:

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 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 )
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, /edges_2)
print, o->getaxis(/energy, /edges_2)

You can also get the array of x and y values for each pixel:

print, o->getaxis(/x)
print, o->getaxis(/y)
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.

o->set, use_single_return_mode=0
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 :

chi2 = o->get(/clean_chi_sq_tot)

 

7.  Plot the images

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.

 

8.  Show a movie of the images

To show a movie in time for the energy band currently selected with e_idx:

o->movie, /time

To specify another energy band:

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]

To scale each image to itself, rather than to all the images in the movie, use the /noscale keyword:

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

 

9.  Display all images at once:

To display thumbnails of all images in the cube in a single window:

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 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:

o->panel_display, /zoom, /plotman, e_idx=e_idx, t_idx=t_idx
print, e_idx, t_idx

 

10. Summary of new image parameters and methods:

Parameters:

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)

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
March 2017