The main command line interface to the HESSI imaging software is the routine
hessi_image.pro.  At the IDL command line, one can create an image simply by
typing:

IDL> hessi_image,im

With this call, the software will simulate HESSI data using a default model
and then analyze the data using the HESSI imaging software.  The resulting
image is displayed to the screen and is also returned in the return variable
im.  The command can also be given without the return variable, im, in which
case the resulting image is only displayed to the screen.  Real HESSI
telemetry data will reside in FITS files.  An image can be constructed from
such FITS files by specifying a filename in the call to hessi_image.  For
example, if HESSI telemetry data resides in the file telemetry.fits (in the
current working directory), this data can be analyzed with the call:

IDL> hessi_image,im,filename='telemetry.fits'

Examples of simulated HESSI telemetry data files are available on the web at
http://hessi.ssl.berkeley.edu/data/archive.html, under
the heading Test Data.  It is important to note that the HESSI imaging
software has memory.  Once invoked, repeated calls to hessi_image will only
redisplay the current image to the screen unless something (parameter,
filename, etc.) is explicitly changed.

The current imaging parameters can be examined at any time by typing:

IDL> hessi_image,im,image_control=image_control
IDL> help,/structure,image_control

An example of the resulting help display is:

** Structure HSI_IMAGE_CONTROL, 20 tags, length=304:
UT_REF                                     DOUBLE             6.7867200e+008
TIME_RANGE                         DOUBLE             Array[2]
TIME_UNIT                              INT                      1
ENERGY_BAND                      DOUBLE             Array[2]
SASZERO                                  BYTE                   0
A2D_INDEX_MASK                BYTE                   Array[27]
TIME_BIN_DEF                       LONG                 Array[9]
TIME_BIN_MIN                      INT                      512
XYOFFSET                                FLOAT                Array[2]
HARMONIC_MAX                  BYTE                  1
HARMONIC_MASK                BYTE                  Array[27, 5]
IMAGE_DIM                            INT                      Array[2]
PIXEL_SIZE                              FLOAT                Array[2]
VRATE                                       POINTER           <NullPointer>
VIMAGE                                    POINTER           <NullPointer>
LONGSCALE                            BYTE                   0
XYPSF                                        LONG                  2048
IMAGE_ALGORITHM           STRING              'back projection'
CLEAN                                       BYTE                   0
IN_IMGALG_PARS                POINTER            <NullPointer>
 

Each of these structure tags can be altered to change how the image is
reconstructed.  For example, suppose you wanted to use the mem sato image
reconstruction method.  Once the structure image_control has been defined
using the call given above, one would then type:

IDL> image_control.image_algorithm='mem sato'
IDL> hessi_image,im,image_control=image_control

Each of the structure tags can also be given as a keyword directly on the
command line to effect the same result.  Again, the mem sato imaging
algorithm could be invoked simply by typing:

IDL> hessi_image,im,image_algorithm='mem sato'

without ever having to define the structure image_control.  It is also
important to note that the software remembers any changes made to the
imaging control parameters in all subsequent usage.  In the examples given
above, the mem sato algortihm will continue to be used for each new image
until it is explicitly changed, perhaps with the call:

IDL> hessi_image,im,image_algorithm='back projection'

Note, due to the way IDL works, the first time the image_control keyword is
given with an output name that is not defined, the current imaging control
parameters are loaded into the structure name.  When the call is given again
with the same structure name which is now defined on the main level, it is
taken as an argument for setting the imaging control parameters.  Therefore,
if a new IDL session is started with the following commands:

IDL> hessi_image,im,image_control=image_control
IDL> hessi_image,im,image_algorithm='mem_sato'
IDL> hessi_image,im,image_control=image_control

The result of the 3rd call to hessi_image will be to analyze the simulated
data using the back projection imaging algorithm.  If it is desired to load
the new imaging parameters into a structure for viewing, one must either
first execute:

IDL> delvar,image_control

before typing the 3rd line abaove, or to give the return variable a new
name:

IDL> hessi_image,im,image_control=image_control2

HESSI Imaging Control Keywords (Tags)

Here, a description is given of each of the imaging control keywords, along
with their default values.

ut_ref - double precision number - The UT given in milliseconds from the
beginning of the year.  This is the start time taken from the data file on
disk or is assigned a default value of 6.7867200e+008 for simulated data.

time_range - double precision 2 element array - Controls the time range for
the data used to construct the image.  Units are in seconds from the start
time of the data file.  The default is [0.,4.], ideally corresponding to one
full rotation of the spacecraft.  In reality, the spacecraft spin period is
likely to be slightly different, requiring a setting like [0.,3.943] to
specify one full rotation.

time_unit - integer - Default value is 1.

energy_band - double precision 2 element array - Controls the energy band
used to construct the image.  Units are in keV, with defaults of [6.,100.].

saszero - byte - Used in currently available simulation mode.  Default is 0,
which means no aspect solution is used, and assumes the spin axis is aligned
with Sun center.   When real data becomes available, the SAS solution will
be taken from it.

a2d_index_mask - 27 element byte array - Controls which collimator's data is
used in the image reconstruction.  A value of 1 indicates the collimator
will be used, and a value of 0 indicates that it will not.  The first 9
elements refer to the front segments of collimators 1-9, the next 9 elements
of the array refer to the low energy portion of the rear segments of
collimators 1-9, and the last 9 elements refer to the high energy portion of
the rear segments for collimators 1-9.  The energy at which the changeover
occurs in the rear segments is not yet known.  As an example, to contstruct
an image using only the front segments of collimators 3,4,5, and 6,
a2d_index_mask should be set equal to
[0,0,1,1,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0].  The default is to
use the front segements of all 9 collimators in the first harmonic: that is
the first 9 elements are set to 1 and all others are set to 0.

time_bin_def - a 9 element long integer array - the time bins used for each
collimator.  Units are in milliseconds.

time_bin_min - integer - the minimum allowed time bin for any collimator, in
units of milliseconds.  Default is 512.

xyoffset - a 2 element floating point array - Sets the center of the region
to be imaged.  Units are in arcseconds from the telescope axis, which is
nominally supposed to be pointing at the disk center of the Sun.  The
default pointing is [600.,200.].

harmonic_max - byte - maximum harmonic to be used in the constructing the
image.  Default is 1, maximum is 5.

harmonic_mask - a 27 X 5 byte array - an array giving the mask for the
harmonics to be used.  The 27 elements reference the a2d indices (see
a2d_index_mask).  The 5 elements reference the 5 potential harmonics that
can be used: element 0 is the 1st harmonic, element 1 is the 2nd harmonic,
and so on.  A value of 1 in the mask will use the given harmonic for the
given collimator, and a value of 0 will force the given collimator/harmonic
combination to not be used in the image reconstruction.  The default is to
use only the 1st harmonic in collimators 1-9, so the mask has elements
[0:8,0] = 1, while all other elements are set to 0.

image_dim - a 2 element integer array - Sets the size of the image to
construct.  Units are in pixels, and it is generally recommended to use
square images in the reconstruction.  The total size (in arcseconds) of the
resulting image is then the size of the image given by image_dim multiplied
by the pixel_size described below.  The default for image_dim is [64,64].

pixel_size - a 2 element floating point array - Sets the size of the pixels
used in the image reconstruction.  Both an x- and y-size are specified
(hence the two elements, x- first), allowing for the use of non-square
pixels.  Units are in arcseconds and the default is [1.,1.].

vrate - pointer - mainly used for internal testing.  Is set only if for some
reason a photon rate other than that observed is to be used?  This keyword
will not generally be set by the user.

vimage - pointer - can be used to return an estimated count rate from a
specified image?  Again, not generally set by the user.

longscale - byte -

xypsf - a longword integer -

image_algorithm - a string variable - Is used to set what imaging algorithm
is to be used in the image reconstruction.  The default is 'back
projection'.  The two currently available algorithms are 'back projection'
and 'mem sato', with 'pixons'  and 'forward fitting' to be available soon.
When using the 'mem sato' algorithm, substantial improvements in speed
result if the first 2 elements of the a2d_index_mask are set to 0.

clean - byte - I think this is redundant with clean_alg given below, and may
not survive.  See clean_alg for a description of what it is supposed to do.

in_imgalg_pars - pointer -

In addition to these imaging control structure tagnames (which can also be
referenced as individual keywords), the following additional keywords can be
used with the routine hessi_image:

clean_alg - byte - Controls whether clean is performed on images produced
using 'back projection' and does nothing when other imaging algorithms are
used.  Default value is 0, corresponding to no cleaning, while 1 turns clean
on.

clean_parameters -

filename - string - Is used to specify the filename containing the HESSI
telemetry data which will be used to construct the image.

lightcurve - probably will not survive as a keyword to hessi_image, but will
become its own module.

noclean - Can be given to turn off cleaning.  Is redundant with setting
clean_alg  = 0.

out_imgalg_pars

spectrum - probably will not survive as a keyword to hessi_image, but will
become its own module.

xaxis - not really working at this point, but could perhaps be used to
return the X-axis of the resulting image.

yaxis - not really working at this point, but could perhaps be used to
return the X-axis of the resulting image.

Simulating HESSI Data

As described above, images can be constructed from HESSI telemetry data
files, or the user can use hessi_image to actually simulate HESSI data and
then analyze it.  A more sophisticated simulation tool is under development;
however, much can be done with hessi_image.  The default model consists of
two point sources (one centered, one in the lower left portion of the
image), assuming a photon rate of 1000 photons per second per collimator.
The simulation control keywords all have the prefix sim_ to set them
apart.   Most models of HESSI data use Gaussian sources of various sizes and
aspect ratios.  The suite of HESSI software has a convenient means built in
to simulate Gaussian sources.  One must specify the source amplitude
(normalized to unit maximum - the overall flux normalazation is handled in
the number of photons specified), location with respect to the center of the
simulation box, width in the X and Y directions, and the tilt angle.  This
information is entered into a source structure for use by the software.  For
example, suppose you wish to specify a single Gaussian source offset +10
arcseconds in the X-direction and +2 arcseconds in the Y-direction from the
center of the image, with a X width (sigma) of  5.0 arcseconds and a Y width
of 2.0 arcseconds, and a tilt angle of 45.0 degrees, the following commands
should be entered:

IDL> hsi_struct_def

(note: if you have already run hessi_image, you do not need to type the
above command)

IDL> gg = {gaussian_source_str}
IDL> gg.amplitude = 1.0
IDL> gg.xysigma = [5.,2.]
IDL> gg.xypos = [10.,2.]
IDL> gg.tilt_angle_deg = 45.
IDL> hessi_image,im,model=gg

Note that the keyword specifying the model does not have the leading sim_ in
it.  This is a bug and will hopefully be fixed soon.

You can specify multiple Gaussian sources as well.  Suppose you wish to
specify 2 sources, both with widths of [5.0,2.0], with one located at an
offset [20.0,-3.0] and one half as strong as this at [-5.0,15.0], both with
0.0 tilt angles, you would type:

IDL> gg1 = {gaussian_source_str}
IDL> gg1.amplitude = 1.0
IDL> gg1.xysigma = [5.,2.]
IDL> gg1.xypos = [20.,-3.]
IDL> gg1.tilt_angle_deg = 0.
IDL> gg2 = {gaussian_source_str}
IDL> gg2.amplitude = 0.5
IDL> gg2.xysigma = [5.,2.]
IDL> gg2.xypos = [20.,-3.]
IDL> gg2.tilt_angle_deg = 0.
IDL> model = [gg1,gg2]
IDL> hessi_image,im,model=model

Another means of specifying point sources is to simply create a model image
loaded with 0s everywhere except for the locations
of the point sources, which should be loaded with a normalized intensity.
For example, to create a 64 X 64 image with 3 point
equal strength point sources at positions [10,20], [30,12], and [15,40] the
following syntax can be used:

IDL> model=fltarr(64,64)
IDL> model[10,20]=1.0
IDL> model[30,12]=1.0
IDL> model[15,40]=1.0
IDL> hessi_image,im,sim_model=model

The strength of the point sources again is given in normailized units, while
the overall flux level is given by the keyword sim_photons.  In the above
example, all three point source are of equal strength.  If you wanted to
make the one at [30,12] equal to 1/4 of the other two, you would have typed:

IDL> model[30,12]=0.25

instead.  The simulated data will be constructed assuming the default of
1000 photons per second per collimator incident on the spacecraft, which is
not particularly good statistics, especially when spread over 3 sources.
The overall flux level in the simulation could be increased with the call:

IDL> hessi_image,im,sim_model=model,sim_photons=5000

HESSI Simulation Keywords

The following is a list of keywords that can be specified to control the
simulated data to be produced.

sim_model - typically given as an array with zeroes everywhere except at the
location of point sources.  The non zero values should be specified in
normalized units, with a maximum of 1.0.  Alternatively, one can use the
keyword model (without the leading sim_) to specify single Gaussian
components, controlling the amplitude, x and y standard deviations, and the
tilt angle of the Gaussian.

model - Can be used to pass in a structure (labelled gaussian_source_str)
which specifies a 2d Gaussian source.  The Gaussian is specified by its
amplitude, x and y standard deviation (in arcseconds), its position relative
to the center of the image (in arcseconds), and its tilt angle.  See above
for examples.

I

The result will show the image of this Gaussian source and load it into the
variable im.

sim_photons - floating point number - Is used to control the overall flux
level of the simulated data.  The units are in photons per second per
collimator incident on the spacecraft, with a default value of 1000.

sim_a2d_index_mask

sim_pixel_size - Is used to set the size of the pixels when using a model
image of some size (e.g. 64 X 64).  The default sim_pixel_size is 2.0
arcseconds, which is different from the default imaging pixel_size.

sim_xyoffset

sim_time_range

sim_time_unit

sim_ut_ref

sim_background

sim_energy_band

This site last updated November 10, 2008.