reproject_image_grid

Synopsis

Projects image(s) from one WCS to another

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

Description

`reproject_image_grid' maps an image in one WCS reference frame to a specified WCS grid. It can be used to combine multiple images, in which case the input images need not cover the same area of the sky but must all use the same projection type. If you have an reference image and want to match its WCS, use the reproject_image tool instead.

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

Any Null/NaN valued pixels or pixels outside the data-subspace or pixels outside the input image are assigned a value = 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_grid 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 should not be used as input the 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_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
clob+

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"
method=sum

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

Parameters

Detailed Parameter Descriptions

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

The input image(s).

The input 2D image or images. If multiple images are used then the World-Coordinate Systems do not have to match (so the images can be different sizes or cover differnt parts of the sky), but they must all use the same type of projection.

Parameter=outfile (file required filetype=output)

The output file name

Contains the reprojected image.

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

The output image size in the X direction

The size is in pixels.

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

The output image size in the Y direction

The size is in pixels.

Parameter=xcenter (string required units=degrees)

The X coordinate of the image center.

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). The coordinate system is controlled by the coord_sys parameter.

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)

The Y coordinate of the image center.

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). The coordinate system is controlled by the coord_sys parameter.

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. The same value is used for both 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 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)

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.

Changes in CIAO 4.15

A problem handling negative declinations when given in sexagesimal format has been fixed.

Changes in CIAO 4.16

• Corrected the units from "degrees" to "deg" as per the FITS standard.

Bugs

Caveats

Setting the pixelsize to a value in arcseconds

If you are setting the reproject_image_grid pixelsize parameter to a value in arcseconds, you have to specify it when the tool is run, not via pset.

A feature in the CIAO parameter interface causes double quotes (") to be converted to single quotes (') when they are written to the parameter file:

unix% pset reproject_image_grid pixelsize='1"' 
unix% pget reproject_image_grid pixelsize
1'

Supplying the pixelsize on the command line when the tool is run ensures that the value will be correctly interpreted as arcsec, e.g.

unix% reproject_image_grid pixelsize='1"' 
Input image file name (@expmaps.lis): 
.. etc. ..

The value is also correctly recorded in the history of the output file:

unix% dmhistory sn1006_expmap.fits reproject_image_grid
reproject_image_grid infile="@list_of_expmaps.lis" outfile="sn1006_expmap.fits"
xsize="2500" ysize="2500" xcenter="225.7" ycenter="-41.9" theta="0" pixelsize="1""  
projection="tan" resolution="1" method="average" coord_sys="world"  
lookupTab="/soft/ciao/data/dmmerge_header_lookup.txt" clobber="yes" verbose="0" 

See Also

concept

merging_rules

tools::coordinates

reproject_image, sky2tdet

tools::hrc

hrc_dtfstats

tools::image

dmimgcalc, dmimgfilt, dmregrid2

tools::region

skyfov

tools::response

addresp

tools::table

dmmerge