Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2013

URL: http://cxc.harvard.edu/ciao/ahelp/dmimgpick.html
AHELP for CIAO 4.9

dmimgpick

Context: tools

Synopsis

Maps image values to rows in a table

Syntax

dmimgpick  infile imgfile outfile method [clobber] [verbose]

Description

'dmimgpick' will map values from an image to rows in a table. Typical kinds of uses include getting background values for source postions, exposure values for sources, etc.

The input image must have axis names that map to columns in the input table. An error will be generated if the tool cannot find the axes names. For each row in the table, the columns that correspond to the image axes are mapped into the image coordinates. The values closest to the location are extracted and then interpolated based on the user selected criteria. The name of the input image block is used as the column name in the output file.

If the table columns are arrays then the output column will also be an array.

Example 1

dmimgpick mysrc.fits expmap.fits srcexp.fits method=minimum

For each source in the source list, find the value of the exposure map and get the minimum value (useful for edge detections). The values are stored in a column named EXPMAP (the default exposure map image block name) in srcexp.fits.

Example 2

dmimgpick contour.fits temperature_map.fits out.fits meth=closest

Supposing that 'contour.fits' is for example the output of dmcontour, the (X,Y) columns will be an arrarys. In this case, the output file will have an array column for the temperature map in the output, that is the same length as the X and Y.

Parameters

name type ftype def min max reqd
infile file input       yes
imgfile file input       yes
outfile file output       yes
method string   weight     yes
clobber boolean   no      
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input table name

The input table. There must be columns with the same name as the axes in the 'imgfile' parameter.

Parameter=imgfile (file required filetype=input)

The input image file

The input image file. The axes names need to match the columns in the 'infile' parameter. The output column in the 'outfile' will be the name of the input image block and will have the same units as the image.

Parameter=outfile (file required filetype=output)

The output file name

A copy of the input file with a new column (double data type) containing the interpolated image values.

Parameter=method (string required default=weight)

Interpolation method

The column values in the table are mapped to the image and the 4 closest pixel values (and their locations) are returned. The user can select from the following interpolation methods:

  • weight - a weighted average. The weight is the distance from the image pixels to the location mapped onto the image.
  • average - a simple average of the 4 pixel values.
  • mininum - the minimum of the 4 pixel values
  • maximum - the maximum of the 4 pixel values
  • closest - the value of the pixel closest to the mapped location
  • furthest - the value of the pixel furthest from the mapped location

Parameter=clobber (boolean default=no)

Remove output if it exists?

Used to specify whether or not to clobber existing file that has the same name as the specified output file (only DM dataset will be clobbered).

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

The tool chatter level

Verbose can be from 0 to 5, generating different amounts of debugging output.

Bugs

[New] (16 May 2017)Locations picked just outside the image boundary may return incorrect values with method=closest

The wrong value is returned when using method=closest for locations outside the image boundary but within 0.5 of a pixel of the bottom and left side of the image.

All locations outside the image should return a NaN; however, for these locations the closest edge pixel location is returned.

See Also

dm
dmfiltering
tools
dmappend, dmcontour, dmellipse, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmregrid, dmregrid2, dmstat, evalpos, imgmoment, mean_energy_map, pileup_map

Last modified: December 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.