NAME

cutout -- extract FITS cutout images from a survey using world coordinate information

USAGE

cutout output ra dec

PARAMETERS

output

The output image cutout list. The output images are always FITS images. If output is "default", the cutout image names have the form "imroot_coords_filter.fits", where imroot is the root image name, coords is an IAU-like field center designation, and filter is the filter id. If output is not "default" the image names in output are used. If there are more output images than output image names in output, default names are assigned to the "extra" images.

ra

The right ascension of the center of the region to be extracted in sexigesimal or decimal hours.

dec

The declination of the center of the region to be extracted in sexigesimal or decimal degrees.

rawidth = "10.0", decwidth = "10.0"

The extraction region right ascension and declination widths in arcminutes or x and y widths in pixels. If the radwidth or decwidth value includes a trailing 'p' character, e.g. '600p', then both widths are interpreted as pixels. If the decwidth value is "INDEF", decwidth defaults to the value of rawidth.

fcsystem = "ICRS"

The coordinate system of the center of the region to be extracted. At present only equatorial coordinate systems are supported. The current options are "J2000", "ICRS", and "B1950".

filters = "Bw,R,I"

The filter extraction list. If filters is "all" or "" then data in all filters is extracted, otherwise only data whose filter ids match the ids in filters is extracted. The filter ids must be separated by commas and there must be no internal blanks in the filter list.

regions = "none"

A text file listing the regions to be extracted. The regions file format is described in detail in the description section. If regions is "none" the parameters ra, dec, rawidth, decwidth, fcsystem, and filters define the region to be extracted.

cutmode = "largest"

The data extraction mode. The options are:

largest

Use data from the survey image with the largest area of overlap with the extraction region.

collage

Use data from all the survey images which overlap the extraction region and collage the images into the cutout region in order of increasing area of overlap.

trim = no

Remove undefined rows and columns from around the edge of the cutout image ?

blank = 0.0

The value assigned to undefined pixels in the cutout image.

opmode

The cutout task mode. The options are:

scan

Create or update the image survey database file.

list

List the survey images which overlap the user specified extraction region.

cutout

Create cutout image(s) of the user specified extraction region.

dbfile

The image survey database file. Database contains a simple description of each survey image. If opmode is "scan" the database file is created or updated, otherwise it is searched.

input

The list of survey images. If opmode is "scan" the survey image list is scanned and a description of each image is written to dbfile.

kwfilter = "FILTER"

The survey images header keyword containing the filter id.

imroot = "NDWFS"

The default root output image name or prefix.

update = yes

Rewrite the entire the database file if opmode = "scan" ? If update = no then records for new images are appended to the end of the database file.

listout = no

List the names of the created cutout images if opmode = "cutout". If listout = yes then verbose is automatically set to no.

verbose = yes

Print detailed messages about the progress of the task ?

DESCRIPTION

The CUTOUT task extracts FITS cutout images from a list of survey images input and writes the output images to output. The survey images are described in the database file dbfile which is created or updated when CUTOUT is run with opmode ="scan".

The database file contains a description of every survey image. At present this description includes the name of the image, the filter id, the right ascension and declination of the image center in hours and degrees, the coordinate system of the image, the size of the image in pixels, the image projection type, the coordinates of the projection reference point in degrees and degrees, the coordinates of the reference point in pixels and pixels, the x and y image scale in "/pixel, the x and y axes rotation in degrees, and the image extent in ra and dec in degrees and degrees. The database filter ids are read from the image keyword defined by the kwfilter parameter.

A single cutout region is specified by the ra, dec, rawidth, decwidth, fcsystem, and filters parameters. Multiple cutout regions may be defined in the regions file regions which has the following format.

ra1 dec1 ra/xwidth1 [dec/ywidth1 [fcsystem1 [filters1]]]
ra2 dec2 ra/xwidth2 [dec/ywidth2 [fcsystem2 [filters2]]]
raN decN ra/xwidthN [dec/ywidthN [fcsystemN [filtersN]]]

The right ascension and declination values define the center of the extraction region and must be hours and degrees. The right ascension and declination widths must be in arcminutes. The x and y widths must be in pixels. X and Y pixel width values are distinguished from ra and dec width values by a trailing 'p' character. The decwidth / ywidth, coordinate system, and filter id values are optional, and default to the value of rawidth, and the values of the fcsystem and filters parameters respectively.

If opmode = "list" then the names, offsets from the extraction region center in arcminutes or pixels, and filter ids are printed on the screen.

If opmode = "cutout" the FITS image cutouts output are created, one cutout for each filter in filters. If cutmode = "largest" the cutout is extracted from the survey image which has the largest overlap with the extraction region. If cutmode is "collage" then the cutouts are created from all the images which overlap the extraction regions, with images with larger overlap regions taking precedence over those with smaller overlap regions. The survey images are assumed to have a common projection system and cutouts are aligned to the nearest pixel. Undefined pixels in the cutouts are assigned the value blank. If trim = yes then undefined pixels around the edges of the cutout images are removed.

By default the cutout image names are of the form "imroot_coords_filter.fits" where imroot is the values of the parameter imroot, coords is an IAU-like coordinate designation, and filter is the filter id. Users can also specify their own output image names in output. If there are more output images than output image names then default output image names are constructed for the "extra" images.

EXAMPLES

1. Create an image database for the survey images in the subdirectory data.

cl> cutout opmode="scan" dbfile=imdb.dat input=data/*.fits

2. Update the previous database after some new images are added to the survey directory. The entire database will be rewritten.

cl> cutout opmode="scan" dbfile=imdb.dat input=data/*.fits

3. List all the images in the survey which overlap the 20 arcminute region around position ra = 13:29:56.232, dec = +47:11:38.19, fcsystem = J2000.

cl> cutout "default" 13:29:56.232 +47:11:38.19 rawidth=20.0 decwidth=20.0 \

filters="" opmode=list dbfile=imdb.dat

4. Repeat example 3 but specify x and y widths in pixels instead of ra and dec widths in arcminutes assuming that the scale is 1 " / pixel.

cl> cutout "default" 13:29:56.232 +47:11:38.19 rawidth=1200p \

decwidth=1200p filters="" opmode=list dbfile=imdb.dat

5. Make B and R band cutouts of the above region from the images which have the largest area of overlap with the extraction region. Do not trim the images.

cl> cutout "default" 13:29:56.232 +47:11:38.19 rawidth=20.0 decwidth=20.0 \

filters="B,R" dbfile=imdb.dat

6. Repeat example 5 but create a collage of all the survey images which overlap the extraction region.

cl> cutout "default" 13:29:56.232 +47:11:38.19 rawidth=20.0 decwidth=20.0 \

filters="B,R" cutmode=collage dbfile=imdb.dat