Cameras¶

Applications to control cameras have many common features. Most of them are implemented in the standard camera interface, but will only be enabled if a particular model of camera supports them.

Driver details: ocam2KCtrl | baslerCtrl | …

Standard Camera Interface¶

All camera controllers implement the standard camera interface (source code) and expose the subset of those properties that their hardware and driver support.

Modes¶

Modes are pre-defined hardware configurations, which include the size and binning of the readout. They are defined in the configuration file with sections, where the section name is the name of the mode. Example:

[mode_name]
configFile=/path/to/EDT-config #this is required
serialCommand=(string) #optional
centerX=(float) #optional
centerY=(float) #optional
sizeX=(int) #optional
sizeY=(int) #optional
binning=(int) #optional
maxFPS=(float) #optional

If configFile is not found, the section will not be treated as a mode.

Modes are controlled through INDI with the following properties:

Property	Element	Type	Description
`.mode`	`.{names}`	selection switch	A list of modes by name. Selecting one will cause the camera to be configured for that mode
`.reconfigure`	`.request`	request switch	Pressing this switch will cause the current mode to be re-loaded.

The following configuration options affect modes:

Short	Long	Config-File	Type	Description
	`--camera.startupMode`	`camera.startupMode`	string	The mode to set upon power on or application startup.

Regions of Interest¶

If the camera supports reading out only a region of interest (ROI), you can use INDI properties to define it. An ROI is specified by its (x,y) center coordinate and its width and height, and optionally binning in each direction. All coordinates and dimensions are in pixels. We use the convention that the center of the lower-left pixel of the full array is (0,0). The center coordinate of the full array is then (0.5*(max_width-1), 0.5*(max_height-1)). Widths and heights are integer values, and coordinates are floats which can have values of 0.5.

Not all values are valid, as some cameras restrict the increments (steps of 4, for example) of some of the values, or otherwise set limits.

To change ROI, you set the .target elements to define the ROI, and then use the .roi_set.request switch to configure the camera. The following INDI properties pertain to ROIs:

Property	Element	Type	Description
`.roi_full_region`	.x	float	(READ ONLY) The x coordinate of the denter of the full region.
`.roi_full_region`	.y	float	(READ ONLY) The y coordinate of the center of the full region.
`.roi_full_region`	.w	int	(READ ONLY) The width of the full region.
`.roi_full_region`	.h	int	(READ ONLY) The height of the full region.
`.roi_region_bin_x`	`.current`	int	The current value of the ROI region binning in the x direction.
	`.target`	int	The target value of the ROI region binning in the x direction. Not laoded until the roi_set.request switch is pressed.
`.roi_region_bin_y`	`.current`	int	The current value of the ROI region binning in the y direction.
	`.target`	int	The target value of the ROI region binning in the y direction. Not laoded until the roi_set.request switch is pressed.
`.roi_region_h`	`.current`	int	The current value of the ROI region height.
	`.target`	int	The target value of the ROI region height. Not laoded until the roi_set.request switch is pressed.
`.roi_region_w`	`.current`	int	The current value of the ROI region width.
	`.target`	int	The target value of the ROI region width. Not laoded until the roi_set.request switch is pressed.
`.roi_region_x`	`.current`	float	The current value of the ROI region center x coordinate.
	`.target`	float	The target value of the ROI region center x coordinate. Not laoded until the roi_set.request switch is pressed.
`.roi_region_y`	`.current`	float	The current value of the ROI region center y coordinate.
	`.target`	float	The target value of the ROI region center y coordinate. Not laoded until the roi_set.request switch is pressed.
`.roi_set`	`.request`	switch	Press this switch to configure with the target values of the .roi_region*`.target` elements above.
`.roi_set_full`	`.request`	switch	Press this switch to configure with the full ROI of the camera.
`.roi_set_last`	`.request`	switch	Press this switch to configure with the previously set ROI.
`.roi_set_startup`	`.request`	switch	Press this switch to configure with the startup ROI (see options below).

The default ROI can be configured with the following options. This ROI will be set each time the camera software is re-started or the camera is powered-on.

Long	Config-File	Type	Description
--camera.startup_x	camera.startup_x	float	The default ROI x position.
--camera.startup_y	camera.startup_y	float	The default ROI y position.
--camera.startup_w	camera.startup_w	int	The default ROI width.
--camera.startup_h	camera.startup_h	int	The default ROI height.
--camera.startup_bin_x	camera.startup_bin_x	int	The default ROI x binning.
--camera.startup_bin_y	camera.startup_bin_y	int	The default ROI y binning.

Exposure Control¶

All MagAO-X cameras operate in free-run, meaning images are taken continuously with no user intervention needed. The exposure time is either set directly, or by setting the frame rate, or both. In cases where both options are given, see the camera specific documentation for details of how they are related. The INDI properties for controlling exposure time and frame rate are:

Property	Element	Type	Description
.exptime	`.current`	float	the current exposure time, in seconds.
	`.target`	float	the target exposure time, in second.
.fps	`.current`	float	the current framerate, in frames per second.
	`.target`	float	the target frame rate, in frames per second.

Shutters¶

If the camera has an associated shutter, it is controlled with the following properties

Property	Element	Type	Description
`.shutter_status`	`.status`	string	Status of the shutter, e.g. POWEROFF, READY, etc.
`.shutter`	`.toggle`	toggle switch	Current state of the shutter: ON = SHUT (\|X\|), OFF = OPEN (\|O\|). Toggling the switch changes state.

Uniblitz DSS Shutters¶

The cameras which use the Uniblitz DSS shutter control have the following additional configuration options

Long	Config-File	Type	Description
`--shutter.powerDevice`	`shutter.powerDevice`	string	The device controlling this shutter's power
`--shutter.powerChannel`	`shutter.powerChannel`	string	The channel controlling this shutter's power
`--shutter.dioDevice`	`shutter.dioDevice`	string	The device controlling this shutter's digital I/O.
`--shutter.sensorChannel`	`shutter.sensorChannel`	string	The channel reading this shutter's sensor.
`--shutter.wait`	`shutter.wait`	int	The time to pause between checks of the sensor state during open/shut [msec]. Default is 100.
`--shutter.timeout`	`shutter.timeout`	int	Total time to wait for sensor to change state before timing out [msec]. Default is 2000.

Temperature¶

All current cameras provide a measurement of the detector temperature. Most provide a way to control the temperature based on a set point.

Property	Element	Type	Description
`.temp_ccd`	`.current`	float	the current detector temperature, in C.
	`.target`	float	only if temperature control is offered, the target temperature to set.
`.temp_controller`	`.toggle`	toggle switch	switch to turn on/off the temperature control system for this camera.
`.temp_control`	`.status`	string	the state of the temperature control, indicating whether it is on target, etc.

The following configuration options also affect temperature:

Short	Long	Config-File	Type	Description
	`--camera.startupTemp`	`camera.startupTemp`	float	the temperature setpoint to set at startup

Framegrabber Interface¶

The standard MagAO-X framegrabber system is used by any application which collects images from hardware and writes them to a shared memory stream. All cameras are framegrabbers. The following INDI properties provide details about the framegrabber:

Property	Element	Type	Description
`.fg_shmimname`	`.name`	string	The name of the ImageStreamIO shared memory image. Will be seen as /milk/shm/.im.shm.
`.fg_framesize`	`.width`	int	The width of the frame in memory.
	`.height`	int	The height of the frame in memory.

The following configuration options will be available in any application which is a framegrabber:

Long	Config-File	Type	Description
--framegrabber.threadPrio	framegrabber.threadPrio	int	The real-time priority of the framegrabber thread.
--framegrabber.shmimName	framegrabber.shmimName	string	The name of the ImageStreamIO shared memory image. Will be used as /milk/shm/.im.shm.
--framegrabber.circBuffLength	framegrabber.circBuffLength	int	The length of the circular buffer. Sets m_circBuffLength, default is 1.

EDT Framegrabbers¶

A camera which uses an EDT framegrabber (PCIe card) will have the following additional configuration options:

Long	Config-File	Type	Description
--framegrabber.pdv_unit	framegrabber.pdv_unit	int	The EDT PDV framegrabber unit number. Default is 0.
--framegrabber.pdv_channel	framegrabber.pdv_channel	int	The EDT PDV framegrabber channel number. Default is 0.
--framegrabber.numBuffs	framegrabber.numBuffs	int	The EDT PDV framegrabber DMA buffer size [images]. Default is 4.

baslerCtrl¶

baslerCtrl controls a Basler camera. It monitors and logs temperatures, configures the camera for the desired mode of operation, and manages the grabbing and processing of frames. It is a MagAO-X standard camera and a standard framegrabber.

Exposure Control¶

The basler cameras use exposure time. Acquisition FPS can be set as an upper limit. As long as exposure time and ROI can support the set FPS, then it will be the framerate of the camera but actual exposure time will not change. Setting {name}.fps.target=0 causes the camera to run at its maximum possible FPS for its configuration.

Regions of Interest¶

Basler cameras support ROIs. Note that there are restrictions on possible settings, which depend on camera model. For instance, the width or height may only be settable in multiples of 2 or 4.

Temperature¶

Temperature is passively monitored only.

Options¶

Basler specific configuration options are:

Short	Long	Config-File	Type	Description
	`--camera.serialNumber`	`camera.serialNumber`	string	The identifying serial number of the camera. This is required to connect.
	`--camera.bits`	`camera.bits`	int	The number of bits used by the camera. Default is 10.

ocam2KCtrl¶

ocam2KCtrl controls the OCAM 2K EMCCD, which serves as the pyramid wavefront sensor detector in MagAO-X. It monitors and logs temperatures, configures the camera for the desired mode of operation, and manages the grabbing and processing of frames. It is a MagAO-X standard camera and a standard framegrabber using the EDT interface.

Options¶

OCAM specific configuration options are:

Short	Long	Config-File	Type	Description
	`--camera.ocamDescrambleFile`	`camera.ocamDescrambleFile`	string	The path of the OCAM descramble file, relative to MagAOX/config.
	`--camera.maxEMGain`	`camera.maxEMGain`	unsigned int	The maximum EM gain which can be set by user. Default is 600. Min is 1, max is 600.