Skip to the navigation links
Last modified: December 2009

AHELP for CIAO 4.2


Context: tools


Projects image from one WCS to another


reproject_image_grid  infile outfile xsize ysize xcenter ycenter theta
pixelsize projection [resolution] [method] [coord_sys] [lookupTab]
[clobber] [verbose]


`reproject_image_grid' maps an image in one WCS reference frame to another. For each output pixel, it maps an n-point polygon onto the input image via the WCS transforms. The area of each pixel covered in the input image is then used to compute the output pixel value.

`reproject_image_grid' can be used to project an image with one tanget point to another tanget point as is useful when merging multiple observations or when matching data across missions.

Any Null/NaN valued pixels or pixels outside the data-subspace or pixels outside the input image are assigned a value = 0.


  • The regridded output is not good to be run through the detect tools. The detect tools expect integer counts and so cast the input image to integer. This truncates/floors the values, which can cause a significant amount of flux to be lost.

Example 1

reproject_image_grid infile=img.fits outfile=new.fits
xcenter="12:32:54.334" ycenter="+54:45:23.996" xsize=512 ysize=512
pixelsize=0.5\" theta=0 projection=tan resolution=1 coord_sys=world

Create a new image using the xcenter, ycenter, xsize, ysize, pixelsize, theta, and projection parameters. In this example the infile image is reprojected to a tangent point specified by the xcenter and ycenter values.

Note: the \ before the " is to escape the " (for arcsecond) from getting interprested by the user shell (eg (ba)sh, (t)csh). If prompted for the value the \ should not be included.

Example 2

reproject_image_grid infile=@images.lis outfile=sn1006_image.fits
xsize=1500 ysize=1500 xcenter="225.7" ycenter="-41.9" theta="0"

Reproject a stack of counts images to a new x and y center. The output will contain the summed counts for each pixel.


name type ftype def min max units reqd
infile file input         yes
outfile file output         yes
xsize integer   1 1   pixels yes
ysize integer   1 1   pixels yes
xcenter string         degrees yes
ycenter string         degrees yes
theta real   0 0 360 degrees yes
pixelsize string         degrees/pixel yes
projection string   tan       yes
resolution integer   1 0      
method string   sum        
coord_sys string   world        
lookupTab string           no
clobber boolean   no        
verbose integer   0 0 5    

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input image.

The input 2D image.

Parameter=outfile (file required filetype=output)

The output file name

Contains the reprojected image.

Parameter=xsize (integer required default=1 min=1 units=pixels)

Image size in X direction

Size is in pixels

Parameter=ysize (integer required default=1 min=1 units=pixels)

Image size in Y direction

Size is in pixels

Parameter=xcenter (string required units=degrees)

X-Center of image in world coordinates

The center of the image. This is where the tangent point is located and will be placed at the center of the image (eg at xsize/2).

This may be entered either in degrees, 210.4568777, or in sexagesimal format, 14:59:32.998 (values not intended to be equal).

Parameter=ycenter (string required units=degrees)

X-Center of image in world coordinates

The center of the image. This is where the tangent point is located and will be placed at the center of the image (eg at ysize/2).

This may be entered either in degrees, 32.998666, or in sexagesimal format, +32:59:32.312 (values not intended to be equal).

Parameter=theta (real required default=0 min=0 max=360 units=degrees)

Rotation angle (degrees)

Position angle: angle between North and +Y-axis measured counter-clockwise.

Parameter=pixelsize (string required units=degrees/pixel)

Pixel size

The size of the pixels on the sky. (Note: same value used for X and Y axes).

This value can be entered either in degrees: 1.345e-4 or 0.0001345, arcminutes: 0.00134', or in arcseconds: 0.495"

Parameter=projection (string required default=tan)

Type of world coordinate system

Currently only tangent plane projections are supported.

Parameter=resolution (integer default=1 min=0)

Controls quality of projection; number of points per side of polygon

An n-sided polygon that outlines the output pixel is mapped to input image via the WCS transforms. The number of points along each side of the pixel is the resolution parameter. A value of '1' indicated that just the corners of the pixel will be used. A value of '2' indicates that the corner and the middle of the pixel-edge line segments will be use. And so on. The more points on the polygon, the better the polygon will approximate the possibly non-linear transform between the images. However, the more points on the polygon, the longer the run-time of the tool.

A value of '0' can also be used. This is a special quick mode that simply maps the center output pixel to a single input pixel and uses that value in the output image. This can be done very quickly; however, when something other than a simple shift of the images is need this can result in image artifacts (for example aliasing or 'dead' regions). Also the 'method' is not applicable in this useage. The output image is essentially "interpolated", so if the pixel scales are different the flux will not be preserved.

Parameter=method (string default=sum)

Controls output normalization

The output image can either represent a conservation of "sum" (integral over an aperture on the input and output image would give same value) or it can represent an "average" (the output pixel value represents an average input value).

Typically users will use "sum" to reproject the COUNTS image and will use "average" to reproject the EXPOSURE image when making fluxed images.

For example, suppose that the match image is blocked by 4 relative to the input exposure map, so that a 4x4 pixel area in the input corresponds to 1 pixel in the output. Then if the typical input exposure pixel has a value of 1000, the typical output exposure pixel in the intermediate map would have a value of 1000 too, rather than 16000 as would be the case if you used method=sum.

This is the desired results, since the exposure is an absolute value and not an integral over area; the flux-conserving method=sum, which is appropriate for the image counts, is not appropriate for the exposure maps. If there are three such maps in the input stack, the typical pixel in the final output will then be 3000 (summing the regridded inputs) rather than 48000 (both summing during the regridding and then summing the results).

Parameter=coord_sys (string default=world)

Coordinate system to do the pixel mapping in

Currently only "world" coordinate system is supported. Logical pixels in the output image are mapped to physical pixels which are then mapped to world coordinate (RA,Dec). These are then mapped back to physical pixels in the input image and then back to image pixels in the input image.

Parameter=lookupTab (string not required)

The header merging table

Rules to merge the headers when more than one file supplied. If set to NONE or a blank string then the header from the first file is used.

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

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.


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

See Also

reproject_image, skyfov

Last modified: December 2009