Skip to the navigation links
Last modified: December 2009

AHELP for CIAO 4.2


Context: tools


Rebin a stack of 2-dimensional images.


dmregrid  infile outfile bin rotangle rotxcenter rotycenter xoffset
yoffset npts [coord_sys] [clobber] [verbose]


This tool regrids each input image within the input dataset based on the binning specification, offsets, minimum and maximum channels, rotation angle, and center of rotation. For a stack of input files, the output file is the sum of the regridded images. The rotation and offset parameters may be specified as a stack in order to apply different values to each of the input file. However, the same binning is applied to all input files; it cannot be given as a stack. Physical and world coordinate systems (containing the transformation given by the first regridding specification) are attached to the output image axes.

If the parameter npts=0, the exact algorithm is used in which for each unit pixel overlapping a regridded pixel, a polygon is created that is the intersection of the two pixels. The area of this polygon is calculated and used to weight the number of counts within the unit pixel to be allocated to the regridded pixel.

If npts is given a positive value, the approximate regridding algorithm is used in which npts*npts uniformly spaced points within a regridded pixel are sampled; the appropriate fraction of the number of counts within the unit pixel encompassing each sampling point is then allocated to the regridded pixel.

The approximate algorithm is faster than the exact algorithm by a factor dependent on the value of npts, the binning scales, and the fraction of the input which is non-zero. The speed scales approximately as N-squared, so npts=2 will be about 4x slower than npts=1. For example, for npts=10 and the binning scales=1, the approximate algorithm is about 10 to 50 times faster. For larger binning scales, the factor is greater due to fewer points being sampled.

Example 1

dmregrid image.fits newimage.fits "20:50:1,30:60:1" rotangle=0
rotxcenter=0 rotycenter=0 xoffset=0 yoffset=0 npts=0 clobber=yes

Regrid a single image by binning a subset of the image with unit bin factors, no rotation and no offsets, clobbering the previous output file, using the exact algorithm, minimum verbosity.

Example 2

dmregrid image.fits newimage.fits "20:100:5,30:110:10" rotangle=10
rotxcenter=25 rotycenter=40 xoffset=15 yoffset=20 npts=10 verbose=5

Regrid an image by binning a subset of the image with bin factors of 5 and 10, rotating about (25,40) by 10 degrees, with an offset of (15,20), clobbering the previous output file, maximum verbosity. The approximate algorithm is used, with 100 points within each regridded pixel sampled.

Example 3

dmregrid @inlist.txt newimage.fits "1:100:1,1:300:3" rotangle=@rotlist
rotxcenter=@xrotlist rotycenter=@yrotlist xoffset=@xofflist
yoffset=@yoffset npts=0

Regrid the images im1.fits and im2.fits listed in the ASCII file inlist.txt by binning from 1:100:1 in x and 1:300:3 in y, rotation angles listed in the file rotlist, offsets listed in the files xofflist and yofflist, rotation center coordinates listed in the files xrotlist and yrotlist, and clobbering the previous output file, summing the images to be output using the exact algorithm.

Example 4

dmregrid @inlist.txt newimage.fits "1:100:1,1:300:3" rotangle=25
rotxcenter=30 rotycenter=40 xoffset=@xofflist yoffset=@yoffset npts=0

Identical to example 3, except perform both rotations about (30,40) by 25 degrees.


name type ftype def min max units reqd stacks
infile file input         yes yes
outfile file output         yes  
bin string           yes no
rotangle string   0     degrees yes yes
rotxcenter string   0       yes yes
rotycenter string   0       yes yes
xoffset string   0       yes yes
yoffset string   0       yes yes
npts integer   0 0 999   yes  
coord_sys string   logical          
clobber boolean   no          
verbose integer   0 0 5      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

The input dataset or stack.

Input images to rebin. If more than 1 image is input, the output will be the sum (co-added) of the rebinned input images.

Parameter=outfile (file required filetype=output)

The output file name.

Parameter=bin (string required stacks=no)

The binning specification.

The binning specification which consists of the minimum channel number for x, the maximum channel number for x, the bin factor for x, and the analogous parameters for y. The same binning is used for all input files. The binning may be given in either image or physical coordinates; the coordinate system of the bin parameter is defined by the `coords_sys' parameter.

Parameter=rotangle (string required default=0 units=degrees stacks=yes)

The CCW rotation angle in degrees of the regridded image in degrees about the rotation center (the location about which the regridded image is to be rotated).

The datatype is listed as "string" because this parameter can accept a stack. Each value in the stack is converted to a floating point value.

Parameter=rotxcenter (string required default=0 stacks=yes)

The x-coordinate of the rotation center.

The datatype is listed as "string" because this parameter can accept a stack. Each value in the stack is converted to a floating point value.

Parameter=rotycenter (string required default=0 stacks=yes)

The y-coordinate of the rotation center.

The datatype is listed as "string" because this parameter can accept a stack. Each value in the stack is converted to a floating point value.

Parameter=xoffset (string required default=0 stacks=yes)

The x-offset of the regridded image.

Parameter=yoffset (string required default=0 stacks=yes)

The y-offset of the regridded image.

Parameter=npts (integer required default=0 min=0 max=999)

If positive, the number of points sampled along a subgrid in each regridded pixel calculated using the approximate algorithm. If 0, the exact algorithm is used.

It's an n-squared kind of cpu performance change ( npts=2 will be about 4x slower than npts=1).

Parameter=coord_sys (string default=logical)

Controls whether the 'bin' parameter is interpreted as 'logical' or 'physical' pixels.

Parameter=clobber (boolean default=no)

Specifies if an existing output file should be overwritten.

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

Specifies the level of verbosity in displaying diagnostic messages (0-5).


See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

dmbinning, dmfiltering
aconvolve, acrosscorr, arestore, dmappend, dmcontour, dmcoords, dmcopy, dmellipse, dmextract, dmfilth, dmgroup, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgfilt, dmimghist, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmregrid2, dmstat, evalpos, get_sky_limits, mkpsf, pileup_map, psf_project_ray, tgextract, tgextract2

Last modified: December 2009