[Last Change: 08 Mar 2012 (rev 11)]

image Source Extent Function

A complex distribution of flux across a source may be simulated using a two-dimensional image, where the relative pixel values are used to determine how much flux is emitted by each pixel.

The image function is a simplified SAOTrace source extent interface function which simulates a source using an image. The flux distribution follows the intensity of the pixels in the image.

Parameters

image() takes a single argument, a table, with the following recognized named entries:

name	type	description	default
position	position specification	source position	on optical axis
spectrum	spectrum specification	source spectrum
file	string	filename of image
rotate	angle (default unit degrees)	rotation of the image about its fiducial point	0
clip	non-negative number	Pixel values below this are ignored	0
flip	string; one of x, y, xy, or none	which if any axes should be flipped	none
format	string; one of ascii, double, fits, float, pbm, pgm.	format of the image. See Image Extent Function#Image Formats.	guessed at
pixsz	angular size (default unit arcseconds) pixsz = 0.2 If the pixel is not square, specify a table: pixsz = { x = 0.1, y = 0.2 }	angular size of a pixel	Determined from the image data if possible, else it defaults to 0.5"
size	a table with elements x and y size = { x = 1024, y = 1024 }	The pixel extent of the image	Only required if the image data do not include the image size.
point_idx	a table with elements x and y point_idx = { x = 4096, y = 4096 }	The location of the image fiducial point in pixels. Excludes point_wcs, ref_wcs, ref_idx	Defaults to the center of the image
point_wcs	a table with elements x and y point_wcs = { x = 16536, y = 16536 }	The location of the image fiducial point in world coordinates. Excludes point_idx, requires both ref_wcs and ref_idx.
ref_wcs	a table with elements x and y ref_wcs = { x = 4096, y = 4096 }	The location of the image fiducial point reference point in world coordinates. Used with point_wcs.
ref_idx	a table with elements x and y ref_idx = { x = 4096, y = 4096 }	The location of the image fiducial point reference point in pixel indices. Used with point_wcs.

Image fiducial point

The fiducial point is the point on the image which is placed at the location specified by the position parameter. By default it is the center of the image. To specify an alternate point you may specify either the exact pixel indices or a position in world coordinates.

To specify pixel indices, use the point_idx parameter, which takes a table of pixel indices:

point_idx = { x = 33, y = 22.2}

To specify the fiducial point in world coordinates, three pieces of information are required:

1. the point's position in world coordinates via the point_wcs parameter

   point_wcs = { x = 4096, y = 4096 }

2. a reference point in the image in world coordinates via the ref_wcs parameter;

   ref_wcs = { x = 4096, y = 4096 }

3. the pixel index of the reference point via ref_idx

   ref_idx = { x = 1, y = 1 }

The world coordinates must be in the same units (e.g. degrees, not hours RA and degrees Dec).

Image Formats

Several image formats are recognized; not all of the formats provide sufficient metadata to describe the image parameters, so additional information will need to be provided.

FITS

The following FITS header keywords are used to determine the image and pixel sizes:

CUNIT1, CUNIT2, CDELT1, CDELT2

If the CDELTn keywords are not present, the pixel size is set to 0.5 arcseconds. Otherwise, if the CUNITn keywords are not present, the units for CDELTn are assumed to be degrees.

CRPIX1, CRPIX2, CRVAL1, CRVAL2

If present, CRPIXn indicates the pixel indices for a reference pixel and CRVALn indicates the world coordinate system values at those indices.

CTYPE1, CTYPE2

These are used to determine if the coordinate axes are in celestial coordinates (in order to set the axis flip parameter).

The pixsz parameter may be used to override the pixel size.

PBM/PGM

The PBM and PGM data formats include image size metadata, but do not include pixel size metadata. Those must be provided with the pixsz parameter.

ASCII

The data are free-form ASCII text. The image and pixel sizes must be specified with the size and pixsz parameters. The data should be stored so that the X values vary most quickly.

Float or Double

The data are encoded as float or double binary numbers. The image and pixel sizes must be specified with the size and pixsz parameters. The data should be stored so that the X values vary most quickly.

Example

image{
   file = 'ell.fits',
   rotate = 65,
   point_idx={ x = 0, y = 0 },
   spectrum = 1.49,
}