CApphot:Measure

The Measure method performs an aperture photometry measurement of the object in an image at pixel coordinates (x,y). The aperture parameters and instrumental parameters are specified by several class properties. The measurement results are returned in class properties and can be fetched using the properties or Accessor Methods.

Syntax

bSuccess = CApphot:Measure( CImage, x, y )

where

CImage contains the image to be measured.

x is the exact column coordinate, measured in pixels.

y is the exact row coordinate, measured in pixels.

bSuccess is the returned success code. If the measurement is successful, true is returned. If not successful, false is returned and the error code can be fetched using GetStatusCode. An error message can be fetched using GetErrMsg. See "Error Messages", below.

This method makes a photometric measurement at pixel coordinate (x,y) of an image. To measure an object at a world coordinate, use CImage:WcsToXy to convert the world coordinates to pixel coordinates in the current image. It also is a good idea to test whether the pixel coordinates are actually inside the image before you attempt to measure something. For an example of an easy way to do this, see the second example under the CRect:PtInside method.

The parameters needed to made the measurements are taken from the class Properties. These parameters include the aperture description (e.g., radii, angle, and ellipticity) as well as instrumental parameters (e.g., gain and exposure time) and measurement parameters (e.g., whether to apply the zero point value). Reasonable defaults are provided but you should set these parameters to "food" values before making any measurements. Before the first measurement, the following parameters should be set with values that pertain to that image: nGain, nReadNoise, nExptime, nZeroPt, nZeroPtErr. These values can be acquired from the image and placed in the class data table using GetImageParams or by reading the appropriate header keywords using CImage class methods.

Error Messages

The Measure method returns true on success or false if an error occurred. If an error occurred then the error can be fetched using GetStatusCode and GetErrMsg. The status codes and and messages are given in the table below.

Error Codes for the Measure Method

Status Code	Error (from GetErrMsg)
-1	Target coordinate is outside the image.
-2	Object aperture extends outside the image.
-3	Object has zero net flux. (Note: The magnitude is set to -99.9)
-4	Object has negative net flux. (Note: The magnitude is set to -89.9)
-5	Internal memory error (nonexistent image?).
other values < 0	An undefined error occurred.

Example

The following script measures an object at coordinate (430.235, 329.368). These are passed as variables but could also be specified literally in the call to Measure. The default background method ("mode" and "positive" skew) is used. The CImage object I is assumed to exist and the image is already loaded.

A = CApphot:new()	-- create a CApphot object
A.nRadius1 = 4.5	-- Set the value of nRadius1
A.nRadius2 = 12	-- Set the value of nRadius2
A.nRadius3 = 16	-- Set the value of nRadius3

if A:GetImageParams( I ) == false then	-- Fetch the image parameters, check them
Printf("Error: %s\r\n", A:GetErrMsg() )	-- print the error message
end

x = 430.235; y = 329.368	-- set the object coordinates
bSuccess = A:Measure( I, x, y )	-- Measure object at (x,y) in CImage I
Printf("Mag = %lg", A.nMag )	-- result: Mag = 15.256