`dmimgcalc' is used to combine multiple images using
a wide range of mathematical operations. Rather than being
restricted to simple operations, (almost) arbitrarily complex
expressions can be used. The tool can also
be used to compare two images on a pixel-by-pixel basis.
The input images must have the same sizes and are combined
using logical coordinates (see "ahelp dmimages" for information
on image coordinate systems).
Using the operation, weight, and weight2 parameters,
one or two images can be combined - using
addition, subtraction, multiplication, or division -
with optional weights.
The output image is defined as
image1*weight <operation> image2*weight2
when <operation> is one of "add", "sub", "mul", or "div".
The data type of the output image will be set to double
if weighting is used (either weight or weight2 is not equal to 1),
one integer image is dividing another integer image,
or the two images have different data types, otherwise the
data type will match that of the input images.
If operation is set to "tst" then
the two images are checked for equality - i.e. that matching pixels
in the two images are the same - and the exit status value
set accordingly (0 if equal, 1 if not). Note that in this case
there is no output image so outfile can be set to "none".
If infile2 is set to "none", there is only one file in the infile
parameter (so it is not a stack),
and the operation parameter is
set to one of "add", "sub", "mul", or "div" then the output
image will the input image multiplied by the value of the
weight parameter.
This functionality is superceeded by the ability to use
complex mathematical expressions for the operation
parameter, as discussed below.
The previous syntax is adequate for simple image combinations.
More complex operations - such as combining more than two images,
converting the data type of an image, or applying mathematical
functions to images - can also be specified.
In this case the list of input images is given as a stack to
the infile parameter (see "ahelp stack") and the individual
images are referenced by the labels "img<n>", where
"img1" refers to the first image and
"imgn" the nth image in the stack.
In this mode the operation parameter is set to
where the allowed syntax for everything to the right of
"imgout=" is described in "ahelp syntax".
As an example, setting
imgout=(sqrt(img1)+sqrt(img2))/img3
will set the output image to be the sum of the square roots
of the first two images divided by the third image.
Further examples are given in the Examples section below.
In this mode the weight and weight2 parameters are ignored.
The tool will operate on corresponding pixels from
the two images regardless of any (conflicting) WCS information in the header.
Thus the user must ensure that the two images must be aligned in logical
array coordinates prior to using the tool.
If infile has WCS information, that information will be propagated
to the output file. If the WCS in infile does not match the WCS
in infile2, a warning will be printed.
When images are combined the header keywords from the different files to be
merged together following the rules given in the
file pointed to in the lookupTab parameter.
The rules for the merging - and the syntax for this file - are
given in "ahelp merging_rules".
One common occurrence - when using the default set of rules - is
for the DETNAM keyword to be changed to the value "Merged",
which may cause issues when processing the resulting image
with other tools.
This tends to happen when combining an observation with
an exposure map since the data will likely have a DETNAM field
that is set to the value from the event file - e.g. "ACIS-012367" -
whilst the exposure map just has the individual chipe name - e.g. "ACIS-7".
Since the two values are different the output is set to "Merged".
You can set the lookupTab parameter to "NONE" to
avoid this merging - in which case the header is taken from the
first input file,
use a modified copy of the table used to define the merging
rules,
or use dmhedit to manually set the
header keyword to the desired value.
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}