/ ciao4.17 / ahelp / dmregrid.html

Jump to: Description · Examples · Parameters · Bugs · See Also

AHELP for CIAO 4.17

dmregrid

Synopsis

Rebin a stack of 2-dimensional images.

Syntax

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

Description

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.

dmregrid vs dmregrid2

dmregrid and dmregrid2 perform the same basic operation in somewhat the same way. The dmregrid npts=0 "exact" algorithm is equivalent to the dmregrid2 resolution=1 method; and dmregrid npts=1 is equivalent to dmregrid2 resolution=0 "quick" method. Most users will find the dmregrid2 tool easier to use as it requires fewer parameters to be specified and generally runs much faster and requires less memory. However, users who want to adjust (especially increase) the size of the image will want to continue to use dmregrid.

Examples

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
verbose=0

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:1,30:110:1" rotangle=10
rotxcenter=25 rotycenter=40 xoffset=15 yoffset=20 npts=10 verbose=5

Regrid an image by binning a subset of the image, 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:1" 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:1 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:1" 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.

Parameters

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.

The lower limits must be set to 1 - i.e. xlo:xhi:xbin,ylo:yhi:ybin where xlo and/or ylo equal 1 - otherwise dmregrid fails to update the physical-to-logical coordinate system, which causes both physical and world coordinates to be incorrect in the output file.

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).

Bugs

Incorrect physical and world coordinates in the output

If the lower limits in the bin parameter are set to anything other than 1 - i.e. xlo:xhi:xbin,ylo:yhi:ybin where xlo and/or ylo do not equal 1 - dmregrid fails to update the physical-to-logical coordinate system, which causes both physical and world coordinates to be incorrect in the output file.

Open-ended binning intervals do not work. (28 Dec 2009)

The tool will fail if you provide open-ended intervals for the x binning, e.g. "::5,::5".

# dmregrid (CIAO): ERROR: Could not parse maxx string ':5,'

If the x-binning endpoints are provided but y endpoints are left open-ended, e.g. "1:1000:5,::5", the tool fails silently. The output file has no y-dimension:

% dmlist ytest.fits blocks

--------------------------------------------------------------------------------
Dataset: ytest.fits
--------------------------------------------------------------------------------

     Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: ytest.fits Image Real4(200x0)