exposure.c File Reference

AzCam Exposure Control Functions. More...

#include "azcam.h"

Functions
int	ClearArray (azcam_t *cam, char *reply)
	Clear (erase) the detector array.
int	StartExposure (azcam_t *cam, int wait, char *reply)
	Start an exposure (integration).
int	SetExposure (azcam_t *cam, float exptime, char *reply)
	Set the exposure (integration) time.
int	ReadExposure (azcam_t *cam, char *reply)
	Query the AzCam server for the current elapsed exposure time.
int	AbortExposure (azcam_t *cam, char *reply)
	Abort an exposure in progress.
int	PauseExposure (azcam_t *cam, char *reply)
	Pause an exposure in progress.
int	ResumeExposure (azcam_t *cam, char *reply)
	Resume a paused exposure.
int	SetFormat (azcam_t *cam, char *reply)
	Define the detector format in unbinned pixels.
int	SetConfiguration (azcam_t *cam, char *reply)
	Define the detector readout configuration.
int	SetROI (azcam_t *cam, char *reply)
	Define the detector region of interest for the next readout.
int	OpenShutter (azcam_t *cam, char *reply)
	Open the Shutter.
int	CloseShutter (azcam_t *cam, char *reply)
	Close the Shutter.
int	RowShift (azcam_t *cam, int nrows, char *reply)
	Shift the image on the array by a given number of rows.
int	GetDetPars (azcam_t *cam, char *reply)
	Query the AzCam server for the current image size.
int	GetPixelCount (azcam_t *cam, char *reply)
	Query the AzCam server for the number of pixels readout.
int	SetShutterMode (azcam_t *cam, int mode, char *reply)
	Set the shutter mode.
int	SetReadoutMode (azcam_t *cam, int mode, char *reply)
	Set the detector readout mode.

---

Detailed Description

AzCam Exposure Control Functions.

The following are a suite of interface functions that provide access to all of the AzCam server exposure control functions.

Most function names recapitulate the analogous AzCam server commands, while others serve as interface functions that provide access to server commands that provide more than one function (e.g., SetMode)

All routines call the communication layer routines in iosubs.c to take care of common handling of timeout, errors, and reply processing.

All of the server exposure control commands documented in Section 9 of the AzCam Programmers Reference Manual have been implemented except the following:

  Expose - not implemented (doesn't work well with the OSU cameras)
  ReadImage - deprecated in recent AzCam versions
  SetSyntheticImage - future expansion
  Guide - future expansion
  

Two new functions

  SetShutterMode()
  SetReadoutMode()
  

Are defined to implement the "SetMode 1 X" and "SetMode 2 X" commands, respectively.

Finally, ParShift has been renamed RowShift in this implementation.

Author:

R. Pogge, OSU Astronomy Dept. (pogge@astronomy.ohio-state.edu)

Date:

2005 May 17

---

Function Documentation

int ClearArray (  azcam_t *  cam, char *  reply )

Clear (erase) the detector array. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Erases the detector array preparatory to starting an integration.

int StartExposure (  azcam_t *  cam, int  wait, char *  reply )

Start an exposure (integration). Parameters: cam  pointer to an azcam struct with the server parameters wait  sets whether the AzCam server waits until the exposure, is complete before replying. One of EXP_NOWAIT or EXP_WAIT. reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Starts an exposure on the detector of the current exposure time (see SetExposure()). The array is not erased first, this must be done explicitly using ClearArray(). If wait=EXP_WAIT, the AzCam server will not return status until the integration is completed. This is usually only done for zero-length (ZERO or BIAS) images, or very short integrations where the application decides not to poll the exposure progress using ReadExposure() calls. If wait=EXP_NOWAIT, the AzCam server will return status immediately after starting the integration. Integration progress can be monitored using the ReadExposure() function. IMPORTANT: if wait=EXP_WAIT, the timeout interval for the AzCam server communications (azcam::Timeout) must be set long enough as as to not timeout before the integration is complete. To ensure that this does not happen, we store the current default timeout, compute a new timeout of the exposure time + 10 seconds, and then make the call, resetting the default timeout after completion (or error). The exposure time used is the value in the azcam::ExpTime data member. See also: SetExposure()

int SetExposure (  azcam_t *  cam, float  exptime, char *  reply )

Set the exposure (integration) time. Parameters: cam  pointer to an azcam struct with the server parameters exptime  exposure time in decimal seconds reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the exposure time for subsequent integrations. The user provides the exposure time in seconds and this function converts it to milliseconds for the AzCamServer. This function also sets the value of the azcam::ExpTime data member.

int ReadExposure (  azcam_t *  cam, char *  reply )

Query the AzCam server for the current elapsed exposure time. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: elapsed exposure time in milliseconds, or -1 if errors, with error text in reply Query the AzCam server and return the elapsed exposure (integration) time in milliseconds. Note In some AzCam server implementions (i.e., every one we've encountered or heard about so far), if you send a ReadExposure command to the AzCam server while a readout is in progress, the server will crash after readout is done, rebooting the machine (meaning total system crash). We avoid this by not allowing the user to send this directive during readout by checking the value of the azcam::State data member.

int AbortExposure (  azcam_t *  cam, char *  reply )

Abort an exposure in progress. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Issues an AbortExposure command to the AzCam server and sets the API's ABORT flag (kept in the azcam::Abort data member). It also sets the server state flag to IDLE (azcam::State data member). Because of some odd hardware interactions that we have observed, an AbortExposure() command must be preceeded by PauseExposure(). We do not know if this is generic to all ARC controllers or just the ones we're working with at OSU. Applications calling this API should call AbortExposure() with some circumspection.

int PauseExposure (  azcam_t *  cam, char *  reply )

Pause an exposure in progress. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Issues a PauseExposure command to the AzCam server. Sets the azcam::State flag to PAUSE on success. If it fails, the azcam::State flag is left unchanged. A PauseExposure should be followed by either AbortExposure() or ResumeExposure(). We test the value of the azcam::State flag and only send a PauseExposure command if EXPOSING. Sending a PauseExposure directive otherwise may be unpredictable. See also: AbortExposure(), ResumeExposure()

int ResumeExposure (  azcam_t *  cam, char *  reply )

Resume a paused exposure. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Issues a ResumeExposure command to the AzCam server. Sets the azcam::State flag to EXPOSING on success. If it fails, the azcam::State flag is left unchanged. Does not send ResumeExposure if the controller is not in a PAUSE state. If you send a ResumeExposure() command when the AzCam server is not actually in a paused state, very bad things can happen (e.g., it crashes and reboots its host computer). See also: PauseExposure()

int SetFormat (  azcam_t *  cam, char *  reply )

Define the detector format in unbinned pixels. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Defines the detector format in unbinned pixels. Since this function is very complicated and important, involving 9 parameters, we do this by using the relevant data members of the azcam struct to define the parameters, rather than having a lot of function arguments. The relevant data members are: azcam::NCtotal - Total number of columns (serial pixels) azcam::NCpredark - Number of physical dark prescan columns azcam::NCunderscan - Number of underscan columns to read azcam::NCoverscan - Number of overscan columns to read azcam::NRtotal - Total number of rows (lines) azcam::NRpredark - Number of physical dark prescan rows azcam::NRunderscan - Number of underscan rows to read azcam::NRoverscan - Number of overscan rows to read azcam::NRframexfer - Number of rows to shift for frame transfer mode A calling application would first set the various parameters in the azcam struct and then call this function to send them to the AzCam server. See also: SetROI(), SetConfiguration()

int SetConfiguration (  azcam_t *  cam, char *  reply )

Define the detector readout configuration. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Defines the readout configuration of the camera. Since this function is complicated and important, involving 5+ parameters, we do this by using the relevant data members of the azcam struct to define the parameters, rather than having a lot of function arguments. The relevant data members are: azcam::ReadMode - Readout Mode, one of SINGLE_AMP, TWO_AMP_PARALLEL, TWO_AMP_SERIAL, FOUR_AMP_QUAD, or MOSAIC azcam::Splits - Split register flag, one of NO_SPLIT, SPLIT_SERIAL, SPLIT_PARALLEL, or SPLIT_QUAD azcam::NumDetX - Number of X (columns) direction detectors in a multi-detector mosaic azcam::NumDetY - Number of Y (rows) direction detectors in a multi-detector mosaic azcam::AmpConfig - Amplifier configuration string, one parameter per amp, 0=no flip, 1=flip cols, 2=flip rows, 3=flip both A calling application would first set the various parameters in the azcam struct and then call this function to send them to the AzCam server. Note, if the ReadMode is changed, you must call SetROI immediately after, or bad things will happen. See also: SetROI(), SetFormat()

int SetROI (  azcam_t *  cam, char *  reply )

Define the detector region of interest for the next readout. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the region of interest for the next detector readout in units of unbinned pixels. Since this is complicated and would involve a lot of arguments, we set this by using the relevant data members of the azcam struct to define the parameters: azcam::FirstCol - first column to read in unbinned pixels azcam::LastCol - last column to read in unbinned pixels azcam::ColBin - column-axis binning factor azcam::FirstRow - first row to read in unbinned pixels azcam::LastRow - last row to read in unbinned pixels azcam::RowBin - row-axis binning factor Note that regions of interest that are smaller than the physical size of the device in unbinned pixels are only supported for single-amplifier readout modes.

int OpenShutter (  azcam_t *  cam, char *  reply )

Open the Shutter. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Instructs the AzCam server to open the shutter. See also: CloseShutter()

int CloseShutter (  azcam_t *  cam, char *  reply )

Close the Shutter. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Instructs the AzCam server to close the shutter. See also: OpenShutter()

int RowShift (  azcam_t *  cam, int  nrows, char *  reply )

Shift the image on the array by a given number of rows. Parameters: cam  pointer to an azcam struct with the server parameters nrows  number of rows to shift reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Shift charges on the CCD vertically by nrows, moving the image "up" towards the readout register if positive, "down" away from the readout register if negative. We allow nrows=0 as a way to take repeated images without row shifts (commonly done for shutter shading correction images). If nrows=0, it returns success rather than sending "ParShift 0" to the server. This function implements the ParShift server command. We elected to call it RowShift since that syntax is closer to what we do in other OSU instruments (ParShift stands for "PARallel SHIFT": the ITL folks use "Parallel" and "Serial" the same way OSU folks use "Vertical" and "Horizontal").

int GetDetPars (  azcam_t *  cam, char *  reply )

Query the AzCam server for the current image size. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: the total number of pixels in the image if successful, -1 if errors. Queries the AzCam server for the current total image size in pixels (including effects of binning, overscan regions, etc). It also sets the azcam::Ncols, azcam::Nrows, and azcam::Npixels data members in the cam struct for the convenience of the calling application.

int GetPixelCount (  azcam_t *  cam, char *  reply )

Query the AzCam server for the number of pixels readout. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: Count of the number of pixels readout if successful, -1 on errors, with error text in reply Queries the AzCam server and returns the number of pixels readout from the detector array. Repeated calls to GetPixelCount() are often used by applications to monitor readout progress. When the array is finished reading out, the pixel count returned should equal the total pixel size returned by GetDetPars(). After each call to GetPixelCount(), it stores the current number of pixels read in azcam::Nread. Note that unlike ReadExposure(), experiments have so far shown that calling GetPixelCount() is benign in all circumstances. See also: GetDetPars()

int SetShutterMode (  azcam_t *  cam, int  mode, char *  reply )

Set the shutter mode. Parameters: cam  pointer to an azcam struct with the server parameters mode  shutter mode, one of DARK_IMAGE, LIGHT_IMAGE, TDI reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the shutter mode to be used during subsequent exposures. The options are: DARK_IMAGE: shutter kept closed during integration LIGHT_IMAGE: shutter is opened during integration TDI: shutter open during readout (currently unsupported) Shutter mode settings stay in force for the rest of the AzCam session unless changed. This function implements the "SetMode 1 X" server command. See also: SetReadoutMode()

int SetReadoutMode (  azcam_t *  cam, int  mode, char *  reply )

Set the detector readout mode. Parameters: cam  pointer to an azcam struct with the server parameters mode  detector readout mode, one of IMMEDIATE or DEFERRED reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the readout behavior for exposures. There are two options: IMMEDIATE: readout is initiated immediately after integration DEFERRED: readout is deferred until an explicit readout is requested IMMEDIATE mode should be used for all normal exposures, whereas DEFERRED is used for custom multiple exposures like focus plates, nod-and-shuffle, shutter shading calibrations, etc. This function implements the "SetMode 2 X" server command, where we have introduced the "immediate" and "deferred" mode names. See also: SetShutterMode()

---