Skip to the navigation links
Last modified: June 2010

AHELP for CIAO 4.2


Context: tools


Find the region covered by an image in sky coordinates


get_sky_limits  image [precision] [dmfilter] [xygrid] [verbose]


There are a number of times when you want to create an image - e.g. by filtering an event file or running mkexpmap - that covers the same region of sky as an existing image. Given the image, this script returns the correct expressions to use as a DM filter (see 'ahelp dmsyntax') and for the xygrid parameter of mkexpmap.

The script produces screen output describing the size of the supplied image and the sky limits (as long as the verbose parameter is not 0). The results can be read from the screen, but they are also stored in the "dmfilter" and "xygrid" parameters of the parameter file (whatever the verbose setting). These can then be accessed using the pget tool ("ahelp tools pget") or parameter library functions ("ahelp paramio").

See the Match the Binning of an Image thread on the CIAO web site for more information.

Example 1

get_sky_limits source.fits

Here we run get_sky_limits with the source.fits file as input (which should be an image file). With the default verbose level (of 1), the following output will be displayed to the screen (the values depend on the input file):

unix% get_sky_limits source.img verbose=1
Checking binning of image: source.img
  Image has 1232 x 1237 pixels
  Pixel size is 1.0 by 1.0
  Lower left (0.5,0.5) corner is X,Y= 3721.5, 3037.5
  Upper right (1232.5,1237.5) corner is X,Y= 4953.5, 4274.5
  DM filter is:
  mkexpmap xygrid value is:

The output information is contained in the last four lines, and is also stored in the parameter file in the "dmfilter" and "xygrid" parameters:

unix% pget get_sky_limits dmfilter
unix% pget get_sky_limits xygrid

You can store these values in shell variables - e.g. for csh/tcsh users:

unix% set dmf = `pget get_sky_limits dmfilter`
unix% dmcopy "evt2.fits[energy=500:2000][bin $dmf]" img.500-2000

- or by using the redirection capabilities of the parameter interface -

unix% mkexpmap xygrid=")get_sky_limits.xygrid" ...other parameters..

See "ahelp parameter" for more information on the capabilities of the parameter interface.

Example 2

get_sky_limits "evt2.fits[sky=region(src.reg)][bin sky=1]"

You can still use the DM virtual file syntax to filter an events file - you just need to make sure that you end up with a binning specification too.

Here we have split the filtering step from the binning one since saying

[bin sky=circle(4023,4100,54)]

would result in an 8192x8192 image (for an ACIS observation), which is unlikely to be the desired result.


name type ftype def min max reqd
image string input       yes
precision real   1 0    
dmfilter string          
xygrid string          
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=image (string required filetype=input)

Image for which you want to know the binning

The name of the image (or if an event file it must contain a DM binning specification) for which you want to know the sky limits.

Parameter=precision (real default=1 min=0)

Precision [# decimal points] for output numbers

The number of decimal places to use when calculating the sky limits. So, if the x limits were 1023.45 and 1439.204 then the output would be:

Precision X min X max
0 1023 1439
1 1023.5 1439.2
2 1023.45 1439.20
3 1023.450 1439.204

It is unlikely that you need to change this parameter from its default value of 1. Although you can set the value to 0, it is not guaranteed that any filters calculated at this precision will be correct.

This parameter was not available in versions of the script prior to CIAO 3.0 (it was hard-coded to the value of 1).

Parameter=dmfilter (string)

DM filter syntax to match image

When the script has finished this parameter will contain the DM filter expression (see "ahelp dmsyntax") needed to filter an events file (or image) to match the input image.

An example of its use would be (using csh/tcsh syntax):

unix% get_sky_limits emap.img ver=0
unix% set filt = `pget get_sky_limits dmfilter`
unix% echo $filt
unix% dmcopy "evt2.fits[bin $filt]" match.img

Here we run the script to find out the limits of emap.img, with verbose set to 0 to avoid any screen output, and then store the DM filter expression in the shell variable filt. This is then used in the dmcopy call to bin an event file, creating the file match.img.

This expression can be used to filter images as well as event files. However note that it will not be correct if the binning of the image being filtered does not match that of the original image.

Parameter=xygrid (string)

xygrid parameter for mkexpmap to match image

Set the xygrid parameter of mkexpmap to this value so as to create an exposure map that covers the same area of sky as the input image.

An example of its use would be:

unix% get_sky_limits src.img ver=0
unix% pset mkexpmap xygrid=")get_sky_limits.xygrid"


unix% get_sky_limits src.img ver=0
unix% set xyg = `pget get_sky_limits xygrid`
unix% pset mkexpmap xygrid=$xyg

In the first example we use paramater indirection (see "ahelp parameter") to set the xygrid parameter of mkexpmap equal to that of get_sky_limits. This requires that mkexpmap is run before the get_sky_limits parameter file is changed; a safer alternative is shown in the second example (using csh/tcsh syntax).

Parameter=verbose (integer default=0 min=0 max=5)

Verbose level

If set to a non-zero value then the tool will print information to the screen when it is run. The extra information prduced when verbose is greater than 1 is only likely to be useful when debugging the script.

The script version is displayed when the verbose parameter is set to 2 or higher.


Version numbering

The version scheme has changed to a date-based system.

Bin sizes are now displayed as floats rather than integers

The screen output when verbose is not 0 now displays the pixel size as a float rather than an integer - e.g.

  Pixel size is 4.0 by 4.0

rather than

  Pixel size is 4 by 4

This does not change the values of the dmfilter and xygrid parameters.

Change to the dmfilter and xygrid parameters

The two "output" parameters of the tool, namely dmfilter and xygrid, have been changed to have a parameter type of "l" rather than "h". This should not change how the tool behaves, but plist will now display these two parameters without a surrounding pair of brackets.


The script now uses the cxcdm module to inspect the input file. This uncovered a few bugs for images with no physical or world-coordinate systems. It also means that the case of the axis names, as reported on-screen and saved to the dmfilter parameter, may change.

Revision 1.13

Revision 1.13 of the script - released in October 2008 - fixes a rare segmentation fault and adds the pixel size (in sky coordinates) to the screen output. The script revision can be found by setting the verbose parameter to 2 or higher.


New parameter: precision

A new parameter called precision has been added. This determines the number of decimal places used when writing out the sky limits: it is a hidden parameter and the default value of 1 (which is what was used in previous versions) should be sufficient for essentially all users.


This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions - such as how to ensure that the parameter file is available.


Using the dmfilter parameter value to filter images

The dmfilter parameter value can be used to filter images as well as event files. However note that it will not be correct if the binning of the image being filtered does not match that of the original image.

Setting precision to 0

When the precision parameter is set to 0 there is no guarantee that the resulting filters will be correct.

See Also

dmbinning, dmfiltering
dmappend, dmcontour, dmcopy, dmellipse, dmextract, dmfilth, dmgroup, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgfilt, dmimghist, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmregrid, dmregrid2, dmstat, evalpos, pileup_map, tgextract, tgextract2

Last modified: June 2010