CApphot:GetImageParams

The GetImageParams method fetches instrumental parameters from the specified image and saves their values in class properties. The following FITS keywords are read: GAIN, RDNOISE, EXPTIME, ZERO-PT, and ZEROPERR. Call this method once for each new image before objects are measured.

Syntax

bSuccess = CApphot:GetImageParams( CImage )

CImage refers to an image object of class CImage.
If all 5 keywords are fetched, true is returned and GetStatusCode returns 0.

If one or more keywords is not found, false is returned and GetStatusCode returns a bit-wise OR of flags for all errors that occured (see table below). Error codes thrown by GetImageParams are positive numbers. An error message can be retrieved using GetErrMsg.

Remarks

The values of the instrumental gain, readout noise, and exposure time are required for the measurement, and the values of the zero point and the zero point error are needed if the zero point is applied to the raw measurements. These values are normally obtained from the image header using the FITS keywords GAIN, RDNOISE, EXPTIME, ZERO-PT, and ZEROPERR. These values can also be fetched separately using the CImage class keyword methods such as KwdGetNumEx and then manually assigned to each of the properties. You will have to use the manual method if a value is not in the image header, they are in the header but use a different keyword, or you want to assign them to other values. The next section describes how to test for invalid keyword values and handle them.

Detecting and Handling Keyword Errors

What happens if one or more of the keywords is not found? There are a couple of ways to handle this. First, you could ignore the failure and let the default values be used (note that, for measuring multiple images, some of the default values may have already been updated by handling the first image of the set). Another option is to decode which keyword(s) failed and then force the class members to specified values as shown in the Example below. The GetStatusCode method returns a value that is the bit-wise OR of error flags. Using this technique allows multiple errors to be stored in a single return value. The table below describes the error flags. These can be parsed as shown in the Example, below. A value of zero indicates that there is no error. The bit number is referenced to bit position 1 being the lowest order bit.

Status Code Bit Flags for Keyword Errors
Bit	Value	Description of error
1	1	GAIN keyword was invalid. The camera gain was not updated for the image.
2	2	RDNOISE keyword was invalid. The camera read noise was not updated for the image.
3	4	EXPTIME keyword was invalid. The exposure time was not updated for the image.
4	8	ZERO-PT keyword was invalid. The photometric zero point was not updated for the image.
5	16	ZEROPERR keyword was invalid. The error in the photometric zero point was not updated for the image.

To parse out the individual errors, first test if the value returned by GetImageParams is 0. if not zero, then it indicates an error with one or more keywords in the image header, which can be sorted out by testing the returned value of nStatusCode against the bit values shown in the table above. This is conventiently handled using the BitTest method. You also could use the BitAnd function to test against flag values 1, 2, 4, 8, and 16 but BitTest is probably easier. When multiple keyword errors are present, the value of nStatusCode is a bit-wise OR of the error flags. For example, nStatusCode = 7 means that bit 1 (value 1), bit 2 (value 2), and bit 3 (value 4) were set, indicating that GAIN, RDNOISE, and EXPTIME were not found in the image header. You can determine this using BitTest for bit positions 1, 2, and 3.

To decode the error flags returned by GetStatusCode, use BitTest to test the return value against the error bits. For example, suppose a CApphot object A is defined and A:GetImageParams(I) returns false, indicating a keyword error. Then the following script fragment checks if the errors are caused by the GAIN and EXPTIME keywords:

if ( BitTest( A.nSatusCode, 1 ) ) then	-- check bit 1 (value 1) for GAIN
...	-- take some action
elseif ( BitTest( A.nSatusCode and 3 ) ) then	-- check bit 3 (value 4) for EXPTIME
...	-- take some action
end

You might modify this code fragment in the following way to force values for the gain and readnoise:

if ( BitTest( A.nSatusCode, 1 ) ) then	-- check bit 1 (value 1) for GAIN
A.nGain = 2.3	-- set the camera gain
elseif ( BitTest( A.nSatusCode, 3 ) ) then	-- check bit 3 (value 4) for EXPTIME
A.nReadNoise = 14	-- set the readout noise
end

Example

The following script fragment fetches the essential keywords from the image header. The imageI of class CImage is assumed to already exist and be loaded. This script shows how to use the value of GetStatusCode ro determine which keyword failed.

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("WARNING: %s\n", A.sErrMsg )	-- print a warning message
if ( BitTest( A:GetStatusCode(), 2 ) ) then	-- if readout was noise not found
Printf("Bad Readout noise keyword\n")	-- print a message and continue
end
end

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