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).
Changes in CIAO 4.16
-
Some error handling cleanup
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)
See Also
- dm
- dmbinning, dmfiltering
- tools::aspect
- asp_offaxis_corr
- tools::coordinates
- dmcoords
- tools::core
- dmappend, dmcopy, dmextract
- tools::download
- install_marx
- tools::gratings
- tgextract, tgextract2
- tools::image
- aconvolve, acrosscorr, arestore, centroid_map, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmradar, dmregrid2, energy_hue_map, evalpos, hexgrid, map2reg, merge_too_small, mkregmap, pathfinder, vtbin
- tools::region
- dmcontour, dmellipse, dmimghull, dmimglasso, psfsize_srcs
- tools::response
- arfcorr, make_psf_asymmetry_region, mean_energy_map, pileup_map, psf_project_ray, simulate_psf, src_psffrac
- tools::statistics
- dmstat, imgmoment, statmap
- tools::table
- dmgroup
- tools::utilities
- apply_fov_limits, get_fov_limits, get_sky_limits