reproject_image

Synopsis

Projects image from one WCS to another

reproject_image  infile matchfile outfile [resolution] [method]
[coord_sys] [lookupTab] [clobber] [verbose]

Description

`reproject_image' maps an image (or stack of images) in one WCS reference frame to match the WCS for a reference image. If you do not have a reference image, use the reproject_image_grid tool instead; it allows you to specify the output WCS grid.

The tool can be used to project an image with one tangent point to another tangent point, as is useful when merging multiple observations or when matching data across missions. For each output pixel in the matchfile, 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.

Any Null/NaN pixels, pixels outside the data subspace, or pixels outside the input image are assigned a value of 0.

The method Parameter

The method parameter applies only to the regridding of the pixels, not how the images are combined. After regridding, the images are always added together. If reproject_image is being used to combine images without changing the resolution, the average and sum methods will yield identical results (with reasonable statistical noise).

NOTES:

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

Examples

Example 1

reproject_image img.fits matchfile=new_tan.fits outfile=reproject.fits

The output image will have the same size and WCS as the 'matchfile' file. Each pixel in 'matchfile' will be mapped to pixels in the 'infile. The pixel resolution isn't changed, so the method parameter setting doesn't apply.

Example 2

reproject_image @img.lis matchfile=new_tan.fits outfile=reproject.fits
method=sum resolution=2

Reproject a stack of counts images, changing the resolution. The output will contain the summed counts for each pixel, after regridding.

Example 3

reproject_image infile=@expmaps.lis matchfile=sn1006_image.fits
outfile=sn1006_expmap.fits method=average

Combine a stack of exposure maps with the average method. The output will contain the average exposure value for each pixel, not the sum of all of them

Example 4

reproject_image XMM.fits matchfile=Chandra.fits outfile=myout.fits

Projects an XMM file to the same WCS (tangent point) as a Chandra image.

Parameters

Detailed Parameter Descriptions

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

The input image(s).

The input 2D image or a stack of images. If more than one image is input, the reprojected images are summed into a single output file.

Parameter=matchfile (file required filetype=input)

The reference image.

The 'infile' image is mapped to the same WCS as this image. The 'outfile' will have the same dimensions and WCS as this image.

Parameter=outfile (file required filetype=output)

The output file name

Contains the reprojected image.

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)

Method for regridding the pixels

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). The method parameter applies only to the regridding of the pixels, not how the images are combined. After regridding, the images are always added together.

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.

Bugs

reproject_image will produced incorrect results if the WCS in the file is defined as (DEC,RA) instead of (RA,DEC).

This is the case for some HST data.

The infile and matchfile must be in the same epoch  (19 Aug 2011)

There is no handling of different celestial coord systems in reproject_image. If one file, for instance if B1950 and the other is J2000, the results will be obviously incorrect (e.g. negative axis ranges in the image).

See Also

concept

merging_rules

tools::coordinates

reproject_image_grid, sky2tdet

tools::hrc

hrc_dtfstats

tools::image

dmimgcalc, dmimgfilt, dmregrid2

tools::region

skyfov

tools::response

addresp

tools::table

dmmerge