_images/Bug72.jpg

ICameraV4 Interface

class Camera

Bases: ASCOM.DeviceInterface

ASCOM Standard ICamera V4 Interface

Methods

Camera.AbortExposure()

Abort the current exposure, if any, and returns the camera to Idle state.

Returns:

Nothing

Raises:

Attention

May throw a MethodNotImplementedException if CanAbortExposure is false.

Note

  • Unlike StopExposure() this method simply discards any partially-acquired image data and returns the camera to idle.

  • Must throw an InvalidOperationException if camera is not idle and abort is unsuccessful (or not possible, e.g. during download).

  • Must throw a DriverException if hardware or communications error occurs.

  • Must not throw an exception if the camera is already idle.

Camera.Action(ActionName: str, ActionParameters)

Added in version 2: Recommended over (now) deprecated CommandBlind(), CommandBool(), and CommandString() as more flexible extension mechanic.

Invoke the specified device-specific custom action

Parameters:

  • ActionName (str) – A name from SupportedActions that represents the action to be carried out.

  • ActionParameters (str) – List of required arguments or empty string if none are required.

Returns:

Action response. The meaning of returned strings is set by the driver author. See notes below.

Return type:

string

Raises:

Important

Note

  • Action names must be case insensitive, so for example SelectWheel, selectwheel and SELECTWHEEL all refer to the same action.

  • An example of a string response: Suppose filter wheels start to appear with automatic wheel changers; new actions could be QueryWheels and SelectWheel. The former returning a formatted list of wheel names and the second taking a wheel name and making the change, returning appropriate values to indicate success or failure.

Camera.CommandBlind(Command: str, Raw: bool)

Added in version 2: Member added as part of common interface elements.

Deprecated since version 4: Use the more flexible Action() and SupportedActions mechanic. See Notes below.

Transmit an arbitrary string to the device and does not wait for a response.

Parameters:

  • Command (str) – The literal command string to be transmitted.

  • Raw (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Deprecated, may result in MethodNotImplementedException

Note

The CommandXXX methods are a historic mechanic that provides clients with direct and unimpeded access to change device hardware configuration. While highly enabling for clients, this mechanic is inherently risky because clients can fundamentally change hardware operation without the driver being aware that a change is taking / has taken place.

The newer Action and SupportedActions mechanic provides discrete, named, functions that can deliver any functionality required.They do need driver authors to make provision for them within the driver, but this approach is much lower risk than using the CommandXXX methods because it enables the driver to resolve conflicts between standard device interface commands and extended commandsprovided as Actions.The driver is always aware of what is happening and can adapt more effectively to client needs.

Camera.CommandBool(Command: str, Raw: bool)

Added in version 2: Member added as part of common interface elements.

Deprecated since version 4: Use the more flexible Action() and SupportedActions mechanic. See Notes below.

Transmit an arbitrary string to the device and wait for a boolean response.

Parameters:

  • Command (str) – The literal command string to be transmitted.

  • Raw (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

True/False response from the command

Return type:

boolean

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Deprecated, may result in MethodNotImplementedException

Note

The CommandXXX methods are a historic mechanic that provides clients with direct and unimpeded access to change device hardware configuration. While highly enabling for clients, this mechanic is inherently risky because clients can fundamentally change hardware operation without the driver being aware that a change is taking / has taken place.

The newer Action and SupportedActions mechanic provides discrete, named, functions that can deliver any functionality required.They do need driver authors to make provision for them within the driver, but this approach is much lower risk than using the CommandXXX methods because it enables the driver to resolve conflicts between standard device interface commands and extended commandsprovided as Actions.The driver is always aware of what is happening and can adapt more effectively to client needs.

Camera.CommandString(Command: str, Raw: bool)

Added in version 2: Member added as part of common interface elements.

Deprecated since version 4: Use the more flexible Action() and SupportedActions mechanic. See Notes below.

Transmit an arbitrary string to the device and wait for a string response.

Parameters:

  • Command (str) – The literal command string to be transmitted.

  • Raw (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

String response from the command

Return type:

string

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Deprecated, may result in MethodNotImplementedException

Note

The CommandXXX methods are a historic mechanic that provides clients with direct and unimpeded access to change device hardware configuration. While highly enabling for clients, this mechanic is inherently risky because clients can fundamentally change hardware operation without the driver being aware that a change is taking / has taken place.

The newer Action and SupportedActions mechanic provides discrete, named, functions that can deliver any functionality required.They do need driver authors to make provision for them within the driver, but this approach is much lower risk than using the CommandXXX methods because it enables the driver to resolve conflicts between standard device interface commands and extended commandsprovided as Actions.The driver is always aware of what is happening and can adapt more effectively to client needs.

async Camera.Connect()

Added in version 4: Preferred asynchronous connection mechanic. See Important section below.

Connect to the device asynchronously. Use this to connect to a device rather than setting Connected to True.

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

  • Non-Blocking. On return, Connecting must be True unless already connected. Connection has successfully completed when Connecting becomes (or is) False.

  • This is a mandatory method and must not throw a MethodNotConnectedException.

  • Use this to connect to a device rather than setting Connected to True.

async Camera.Disconnect()

Added in version 4: Preferred asynchronous connection mechanic. See Important section below.

Disconnect from the device asynchronously. Use this to disconnect from a device rather than setting Connected to False.

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

  • Non-Blocking. On return, Connecting must be True unless already disconnected. Disconnect has successfully completed when Connecting becomes (or is) False.

  • This is a mandatory method and must not throw a MethodNotImplementedException.

  • Use this to disconnect from a device rather than setting Connected to False.

async Camera.PulseGuide(Direction: GuideDirections, Duration: int)

Activates the Camera’s guiding signals, via physical cable(s) connected to the mount, to instruct the mount to move in a particular direction for a given period of time. This duplicates the function of Telescope.PulseGuide(). See What Does PulseGuide() Do? I’m Confused..

Non-blocking: Returns with IsPulseGuiding False. See Notes.

Parameters:

  • Direction (enum) – The direction of the move. See GuideDirections and Notes on meaning of direction.

  • Duration (int) – duration of the guide move, milliseconds

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If the camera does not support pulse guiding (CanPulseGuide property is False)

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

May throw a MethodNotImplemented exception if the camera does not support pulse guiding (CanPulseGuide property is False)

Note

  • Asynchronous: The method returns as soon pulse-guiding operation has been successfully started with IsPulseGuiding property True. However, you may find that IsPulseGuiding is False when you get around to checking it if the ‘pulse’ is short. This is still a success if you get False back and not an exception.

  • Some older cameras have implemented this as a Synchronous (blocking) operation.

  • Directions are nominal and may depend on exact mount wiring. guideNorth must be opposite guideSouth, and guideEast must be opposite guideWest.

  • In addition, GuideDirections for North and South have varying interpretations by German Equatorial mounts. Some GEM mounts interpret North to be the same rotation direction of the declination axis regardless of their pointing state (“side of the pier”). Others truly implement North and South by reversing the dec-axis rotation depending on their pointing state. Apps must be prepared for either behavior.

  • This duplicates the function of Telescope.PulseGuide() but with physical connections (“guider cables”). See What Does PulseGuide() Do? I’m Confused.

Camera.SetupDialog()

Launches a configuration dialogue box for the driver. The call will not return until the user clicks OK or cancels manually.

Please note that this method is only valid for COM drivers. Alpaca devices should provide configuration through the Alpaca HTML endpoints and should not implement a SetupDialog endpoint.

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a MethodNotImplementedException

Note

  • Blocking It is permissible that the configuration dialog is modal, and for the driver not to respond to other calls while this dialog is open.

async Camera.StartExposure(Duration: float, Light: bool)

Start an exposure. Non-blocking: Returns with ImageReady = False if exposure has successfully been started. Use ImageReady to check when the exposure is complete and ready for access via ImageArray. See Note.

Parameters:

  • Duration (float) – The duration of exposure in seconds.

  • Light (bool) – True for light frame, False for dark frame (ignored if no shutter)

Returns:

Nothing

Raises:

  • InvalidValueException – If Duration parameter, or any of BinX, BinY, StartX, StartY, NumX, and NumY have invalid or incompatible combinations of values.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

If your device throws an InvalidValueException here, it is vital that the error message explains which of the binning, subframe, or SubExposureDuration values are illegal or combine to produce an illegal combination. Help your user solve the problem!

Attention

Must be implemented, must not throw a MethodNotImplementedException.

Note

  • Asynchronous (non-blocking): Use ImageReady to determine if the exposure has been successfully completed and the image data is ready for access via via ImageArray. Refer to ImageReady for additional info.

  • The combination of values for BinX, BinY, StartX, and StartY must be checked when a call to StartExposure() is received. If any of these values is illegal, or if a limitation is imposed by CanAsymmetricBin being False. If any of these conditions exist, an appropriate exception must be thrown as described above.

  • A dark frame or bias exposure may be shorter than the ExposureMin value and for a bias frame can be zero. Check the value of Light and allow exposures down to 0 seconds if Light is false. If the hardware will not support an exposure duration of zero then, for dark and bias frames, set it to the minimum that is possible.

  • Some applications will set an exposure time of zero for bias frames so it’s important that the driver allows this.

async Camera.StopExposure()

Stop the current exposure, if any, and make available the image data already acquired. Non-blocking: Returns with ImageReady = False if and exposure is actually in progress. Use ImageReady to check when the exposure has been stopped and existing image data is ready for access via ImageArray. See Note.

Returns:

Nothing

Raises:

Attention

Optional, may throw a MethodNotImplementedException.

Note

  • Asynchronous (non-blocking): Use ImageReady to determine if the exposure has been successfully stopped and the image data is ready for access via via ImageArray. Refer to ImageReady for additional info.

  • Unlike AbortExposure() this method must cut an exposure short while preserving the image data acquired so far, making it available to the client.

  • If an exposure is in progress, the readout process is initiated. Ignored if readout is already in process.

  • Must not raise an exception if the camera is idle.

Properties

property Camera.BayerOffsetX: Integer

Added in version 2: For color imaging

Returns:

The X offset of the Bayer colour matrix, as defined in property SensorType

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If the camera is monochrome. See first Note.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented by colour cameras, monochrome cameras must throw a PropertyNotImplementedException.

Note

  • Since monochrome cameras don’t have a Bayer colour matrix by definition, such cameras must throw a PropertyNotImplementedException. Colour cameras must always return a value and must not throw a PropertyNotImplementedException.

  • The value returned will be in the range 0 to M-1 where M is the X-width of the Bayer matrix. The offset is relative to the 0,0 pixel in the sensor array, and does not change to reflect subframe settings.

property Camera.BayerOffsetY: Integer

Added in version 2: For color imaging

Returns:

The Y offset of the Bayer colour matrix, as defined in property SensorType

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If the camera is monochrome. See first Note.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented by colour cameras, monochrome cameras must throw a PropertyNotImplementedException.

Note

  • Since monochrome cameras don’t have a Bayer colour matrix by definition, such cameras must throw a PropertyNotImplementedException. Colour cameras must always return a value and must not throw a PropertyNotImplementedException.

  • The value returned will be in the range 0 to M-1 where M is the Y-width of the Bayer matrix. The offset is relative to the 0,0 pixel in the sensor array, and does not change to reflect subframe settings.

property Camera.BinX: Integer

Read/Write Gets or sets the binning factor for the X axis, also returns the current value.

Returns:

The binning factor for the X axis.

Return type:

Integer

Raises:

  • InvalidValueException – An invalid binning value is written to the property See Notes.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • Should default to 1 when the camera connection is established.

  • If CanAsymmetricBin is False, then the binning values must be the same. Setting this property must result in BinY being the same value.

  • Camera does not check for compatible subframe values when this property is set; rather they are checked upon StartExposure().

property Camera.BinY: Integer

Read/Write Gets or sets binning factor for the Y axis, also returns the current value.

Returns:

The binning factor for the Y axis.

Return type:

Integer

Raises:

  • InvalidValueException – An invalid binning value is written to the property See Notes.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • Should default to 1 when the camera connection is established.

  • If CanAsymmetricBin is False, then the binning values must be the same. Setting this property must result in BinX being the same value.

  • Camera does not check for compatible subframe values when this property is set; rather they are checked upon StartExposure().

property Camera.CameraState: enum CameraStates

Current operational state of the camera. See State Transition Diagram for Camera.CameraState.

Returns:

The camera’s operational state

Return type:

enum CameraStates

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

property Camera.CameraXSize: Integer
Returns:

The width of the camera sensor in unbinned pixels

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

property Camera.CameraYSize: Integer
Returns:

The height of the camera sensor in unbinned pixels

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

property Camera.CanAbortExposure: Boolean
Returns:

True if the camera can abort exposures with AbortExposure(), else False. See Note.

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

Some cameras support AbortExposure(), which allows the exposure to be terminated before the exposure timer completes, with the image being discarded. Returns True if AbortExposure() is available, False if not. See also CanStopExposure and “StopExposure()

property Camera.CanAsymmetricBin: Boolean
Returns:

True if the camera supports asymmetric binning, else False. See Note.

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

If True, the camera can have different binning on the X and Y axes, as determined by BinX and BinY. If False, writing to either BinX or BinY results in the other binning value being set to the same value.

property Camera.CanFastReadout: Boolean

Added in version 2: For imaging mode support

Returns:

True if the camera supports a fast readout mode. If this is False then the camera may offer ReadoutModes.

Return type:

Boolean

Deprecation Notice

FastReadout is an obsolete mechanic for controlling camera mode(s). The ReadoutMode mechanic should be used.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • If the camera offers ReadoutMode and ReadoutModes, then this property must be False.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.CanGetCoolerPower: Boolean
Returns:

True if the camera’s cooler power level is available via CoolerPower, else False.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Camera.CanPulseGuide: Boolean
Returns:

True if the camera supports pulse guiding with electrical “guider cables” via PulseGuide(), else False.

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • Returns true if the camera can directly send auto-guider pulses to the telescope mount via an electrical connection (“guider cables”).

  • This does not provide any indication of whether the auto-guider cable is actually connected.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

  • The action is analogous to the function of Telescope.CanPulseGuide. See What Does PulseGuide() Do? I’m Confused..

property Camera.CanSetCCDTemperature: Boolean
Returns:

True if the camera’s cooler temperature can be controlled via SetCCDTemperature, else False.

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

If True, the camera’s cooler setpoint can be adjusted. If False, the camera either uses open-loop cooling or does not have the ability to adjust temperature from software, and setting the SetCCDTemperature property has no effect.

property Camera.CanStopExposure: Boolean
Returns:

True if the camera can stop exposures via StopExposure() else False.

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

Some cameras support StopExposure(), which allows the exposure to be terminated before the exposure timer completes, but will still read out the image. Returns True if StopExposure() is available, False if not. See also AbortExposure() and CanAbortExposure

property Camera.CCDTemperature: Float
Returns:

The current CCD cooler temperature in degrees Celsius.

Return type:

float

Raises:

  • InvalidOperationException – If data unavailable.

  • PropertyNotImplementedException – If not supported (can’t report cooler temperature)

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

property Camera.Connected: boolean

Changed in version 4: Writing to change connection state superseded by asynchronous Connect(), Disconnect(), and Connecting.

Read/Write Gets or sets the connected state of the device. Writing is deprecated, use the newer Connect() and Disconnect() methods, and the newer Connecting property. See Notes below.

Set True to connect to the device hardware. Set False to disconnect from the device hardware. You can also read the property to check whether it is connected. This reports the current hardware state. See Notes below.

Returns:

True if connected to the hardware, else false.

Return type:

boolean

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Deprecation Notice

Property-write is deprecated as of Camera V4. Starting with Platform 7 and the interface revisions contained therein, writing to Connected is discouraged. To connect and disconnect, use the newer non-blocking Connect() and Disconnect() methods, with the new Connecting property serving as the completion property.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • Do not use a NotConnectedException here, that exception is for use in other methods that require a connection in order to succeed.

  • The Connected property sets and reports the state of connection to the device hardware. For a hub this means that Connected will be True when the first driver connects and will only be set to False when all drivers have disconnected. A second driver may find that Connected is already True and setting Connected to False does not report Connected as False. This is not an error because the physical state is that the hardware connection is still True.

  • Multiple calls setting Connected to True or False will not cause an error.

property Camera.Connecting: Boolean

Added in version 4: Preferred asynchronous connection mechanic. See Notes below.

Returns:

Returns True while the device is undertaking an asynchronous connect or disconnect operation.

Return type:

boolean

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This is the correct property for determing when the non-blocking methods Connect() or Disconnect() have completed. Completion is when Connecting becomes False after calling either of these methods.

property Camera.CoolerOn: Boolean

Read/Write Turns the camera cooler on and off and returns the current cooler on/off state.

Returns:

The current cooler on/off state.

Return type:

Boolean

Raises:

  • PropertyNotImplementedException – If not supported (can’t report cooler temperature)

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Warning

For some cameras, turning the cooler off when the cooler is operating at high delta-T (typically >20C below ambient) may result in thermal shock. Repeated thermal shock may lead to damage to the sensor or cooler stack. Please consult the documentation supplied with the camera for further information.

property Camera.CoolerPower: Float
Returns:

The current cooler power level in percent.

Return type:

Float

Raises:

  • PropertyNotImplementedException – If not supported (can’t report cooler temperature)

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

Must return zero if CoolerOn is False.

property Camera.Description: String
Returns:

Description of the device such as manufacturer and model number. Any ASCII characters may be used.

Return type:

string

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This describes the device, not the driver. See the DriverInfo property for information on the ASCOM driver.

  • The description length must be a maximum of 64 characters so that it can be used in FITS image headers, which are limited to 80 characters including the header name.

property Camera.DeviceState: List[StateValue]

Added in version 4: To allow reduction of status polling

Returns:

List of StateValue objects representing the operational properties of this device. See What is the “read all” feature and what are its rules?.

Return type:

List

This device must return the following operational properties if they are known:

Note

property Camera.DriverInfo: String

Added in version 2: Member added.

Returns:

Descriptive and version information about the ASCOM driver

Return type:

string

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

This string may contain line endings and may be hundreds to thousands of characters long.It is intended to display detailed information on the ASCOM driver, including version and copyright data. See the Description property for information on the device itself. To get the driver version in a parse-able string, use the DriverVersion property.

property Camera.DriverVersion: String

Added in version 2: Member added.

Returns:

String containing only the major and minor version of the driver.

Return type:

string

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This must be in the form “n.n”. It should not to be confused with the InterfaceVersion property, which is the version of this specification supported by the driver.

  • On systems with a comma as the decimal point you may need to make accommodations to parse the value.

property Camera.ElectronsPerADU: Float
Returns:

The gain of the camera in photoelectrons per A/D unit in its current modes. See Notes and MaxADU, ElectronsPerADU, and FullWellCapacity in the Camera Interface.

Return type:

Float

Raises:

  • PropertyNotImplementedException – If this property is not available for the camera.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

property Camera.ExposureMax: Float

Added in version 3: Member added.

Returns:

The maximum exposure time (seconds) supported by StartExposure().

Return type:

Float

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.ExposureMin: Float

Added in version 3: Member added.

Returns:

The minimum exposure time (seconds) supported by StartExposure().

Return type:

Float

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This must be a non-zero number representing the shortest possible exposure time supported by the camera model.

  • For bias frame acquisition an even shorter exposure may be possible; please see StartExposure() for more information.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.ExposureResolution: Float

Added in version 3: Member added.

Returns:

The smallest increment in exposure time (seconds) supported by StartExposure().

Return type:

Float

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This can be used, for example, to specify the resolution of a user interface “spin control” used to dial in the exposure time.

  • The duration provided to StartExposure() does not have to be an exact multiple of this number; the driver must choose the closest available value.

  • In some cases the resolution may not be constant over the full range of exposure times; in this case the smallest increment must be chosen by the driver.

  • A value of 0.0 shall indicate that there is no minimum resolution except that imposed by the resolution of the float data type.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.FastReadout: Boolean

Added in version 2: For imaging mode support

Read/Write Enables the camera’s FastReadout mode if available, and gets the current state of FastReadout mode. See Notes.

Returns:

True if the camera is in FastReadout mode, else False if it is in normal mode (in which ReadoutModes may be active).

Return type:

Boolean

Deprecation Notice

FastReadout is an obsolete mechanic for controlling camera mode(s). The ReadoutMode mechanic should be used henceforth.

Raises:

  • PropertyNotImplementedException – If FastReadout is not supported (CanFastReadout is False)

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • Some older cameras have a single “fast mode” intended for use in focusing. When set to True, the camera will operate in Fast mode; when False, the camera will operate normally. This property, if implemented, must default to False.

  • This mode mechanic is deprecated, and is includeed only for older cameras and drivers. The ReadoutMode mechanic should be used henceforth.

property Camera.FullWellCapacity: Float
Returns:

The maximum number of photoelectrons that can be held by a single pixel in the camera’s current modes. See See Notes below and MaxADU, ElectronsPerADU, and FullWellCapacity in the Camera Interface.

Return type:

Float

Raises:

  • PropertyNotImplementedException – If this property is not available for the camera.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • At run-time, a change to Binx, BinY, Gain, Offset, or ReadoutMode which results in this value changing must be reflected immediately in this property’s value. Similarly, if a change via the camera’s SetupDialog() settings changes the value, this property must be updated immediately.

  • See MaxADU, ElectronsPerADU, and FullWellCapacity in the Camera Interface.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.Gain: Integer

Added in version 2: Member added.

Read/Write Gets or sets the current gain value or gains index per its current gain-setting operating mode (see description below)

Returns:

The current gain value or gains index

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If Gain is not supported at all ()neither Gains Index nor Gain Value mode is supported).

  • InvalidValueException – If the supplied value is not valid

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

If the camera can support several different operating modes where gain and other parameters are different, it is better to use ReadoutMode and ReadoutModes to change all parameters in one go. If this approach is used, Gain and any other affected parameters must be kept in sync with operational values established by the readout mode.

Gain Modes Description

The Gain property is used to adjust the gain setting of the camera and has two modes of operation:

  • Gains Index: The Gain property is the selected gain’s index within the Gains array of textual gain names.

  • Gain Value: The Gain property is a direct numeric representation of the camera’s gain.

A driver can support none, one or both gain modes depending on the camera’s capabilities. However, only one mode can be active at any one moment because both modes share the Gain property to return the gain value. Your application can determine which mode is operational by reading the GainMin, GainMax property and this Gain property. If a property can be read then its associated mode is active, if it throws a PropertyNotImplementedException then the mode is not active.

Note

  • If a driver supports both modes the astronomer must be able to select the required mode through the driver Setup dialogue.

  • During driver initialisation the driver must set Gain to a valid value.

property Camera.GainMax: Integer

Added in version 2: Member added.

Returns:

The maximum gain value that this camera supports in Gain Value mode (see Notes and Gain)

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If Gain is not supported at all or if the camera is operating in the Gains Index mode.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

For Gain Value mode

When Gain is operating in Gain Value mode:

Note

  • GainMin and GainMax act together; either both must return values, or both must throw PropertyNotImplementedException.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.GainMin: Integer

Added in version 2: Member added.

Returns:

The minimum gain value that this camera supports in Gain Value mode (see notes and Gain)

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If Gain is not supported at all or if the camera is operating in the Gains Index mode.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

For Gain Value mode

When Gain is operating in Gain Value mode:

Note

  • GainMin and GainMax act together; either both must return values, or both must throw PropertyNotImplementedException.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.Gains: Array[String]

Added in version 2: Member added.

Returns:

Array (0-based) of Gain names supported by the camera when in Gains Index mode (see Notes and Gain)

Return type:

Array of strings

Raises:

  • PropertyNotImplementedException – If Gain is not supported at all or if the camera is operating in the Gain Value mode.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

For Gains Index mode

When Gain is operating in the Gains Index mode:

Note

  • Typically the application software will display the returned gain names in a drop list, from which the astronomer can select the desired gain’s name. The application can then configure the selected gain by setting the camera’s Gain property to the array index of the selected gain name.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.HasShutter: Boolean
Returns:

If True, indicates that the camera has a mechanical shutter, else False.

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException.

Note

If HasShutter is False, the StartExposure() method must ignore the Light parameter.

property Camera.HeatSinkTemperature: Float
Returns:

The current heat sink (aka “ambient”) temperature (deg C).

Return type:

Float

Raises:

  • PropertyNotImplementedException – If the camera has no cooler.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

property Camera.ImageArray: Array (multi-dimensional see below)
Returns:

Array containing the exposure pixel values in ADU. See notes for array dimensionality and row vs column ordering, and SensorType

Return type:

Integer ADU values

Raises:

  • InvalidOperationException – If no image data is available (ImageReady is False)

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • The array will have dimensions of NumX by NumY as set at the time StartExposure() was called. Full color images will include a “plane” for each color, with the additional plane index following the X and Y indices. See below for details.

  • This is a synchronous call and clients should be prepared for it to take a long time to complete when large images are being transferred.

  • Drivers written in C++ must return the image as a SafeArray.

  • Developers of Alpaca camera devices are strongly advised to implement the ImageBytes mechanic, which is specified in the Alpaca API Reference, to ensure fast image transfer to the client.

Array shaping and ordering - Monochrome and Bayer

The returned two dimensional array that supports monochrome and Bayer matrix colour sensors is specified with width as its first dimension and height as its second, rightmost, dimension. From an infrastructure perspective, the .NET CLR and C like languages store arrays in memory using row major order, which means that the rightmost array index changes most rapidly.

For an array Array[X, Y] it is the Y index that changes most rapidly, leading to a memory layout that looks like this:

_images/rowmajor.png

On the other hand, the ImageArray property is specified to return Array[NumX, NumY] where X represents width (horizontal lines) and Y represents height (vertical columns). For the ImageArray array, the rightmost dimension is defined as the image height, hence, when stored in memory, the height index will change most rapidly. This means that, from an application perspective, values are held in memory in column major order

_images/columnmajor.png

despite being stored in row major order from an infrastructure perspective. We considered the application view to have primacy and thus consider the returned array to be column major in structure, regardless of the form in which it is stored in memory.

Bayer Matrix Color Images

In the following definitions, R = red, G = green, B = blue, C = cyan, M = magenta, Y = yellow. The Bayer matrix is defined with X increasing from left to right, and Y increasing from top to bottom. The pattern repeats every N x M pixels for the entire pixel array, where N is the height of the Bayer matrix, and M is the width.

SensοrType RGGB indicates the following matrix

_images/bayer-rggb.jpg

SensοrType CMYG indicates the following matrix

_images/bayer-cmyg.jpg

SensοrType CMYG2 indicates the following matrix

_images/bayer-cmyg2.jpg

SensοrType LRGB indicates the following matrix (Kodak TRUESENSE)

_images/bayer-lrgb.jpg

The alignment of the array may be modified by BayerOffsetX and BayerOffsetY. The offset is measured from the 0,0 position in the sensor array to the upper left corner of the Bayer matrix table. Please note that the Bayer offset values are not affected by subframe settings.

For example CMYG2 sensor has a Bayer matrix offset as shown below, BayerOffsetX is 0 and BayerOffsetY is 1

_images/bayer-cmyg2-offset.jpg

Array Shaping and Ordering - Multi-Plane Color Images (non-Bayer)

Full color images contain multiple “planes”, each of which specifies the pixel data for a single color. In ImageArray the third or rightmost index selects the plane. For an RGB image the planes (in order) are R=0, G=1, and B=2. For an LRGB image the planes are L=0, R=1, G=2, and B=3.

property Camera.ImageArrayVariant: Array[COM-Variant]

This property is used only in Windows ASCOM/COM drivers. Alpaca drivers and stand-alone (Alpaca) cameras must raise PropertyNotImplementedException.

Returns:

Array containing the exposure pixel values in ADU.

Return type:

Windows COM Variant ADU values.

Raises:

Attention

This property is included here for completeness, however it is unique and useful only within Windows COM (C#, Visual Basic). For more information see the documentation for ASCOM libraries in the Windows Platform.

Note

  • This is a synchronous call and clients should be prepared for it to take a long time to complete when large images are being transferred.

  • Drivers written in C++ must return the image as a SafeArray.

  • See the description of Camera.ImageArray above for details. ImageArrayVariant differs only in the binary form of the individual array elements (COM-Variant instead of Integer).

property Camera.ImageReady: Boolean
Returns:

True if the requested exposure has completed and Camera.ImageArray contains the image reeady to be reads via that property.

Return type:

Boolean

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • If ImageReady returns a valid False or True value, then the non-blocking process of acquiring an image is proceeding normally or has been successful.

  • ImageReady will be False immediately upon return from StartExposure(). It will remain False until the exposure has been successfully completed and an image is ready for retrieval via Camera.ImageArray.

property Camera.InterfaceVersion: Short

Added in version 2: Member added.

Returns:

ASCOM Device interface definition version that this device supports. Should return 4 for this interface version.

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This is a single “short” integer indicating the version of this specific ASCOM universal interface definition. For ICameraV4, this must be 4. It should not to be confused with the DriverVersion property, which is the major.minor version of the driver for this device.

  • Clients can detect legacy V1 drivers by trying to read this property. If the driver raises an error, it is a V1 driver. V1 did not specify this property. A driver may also return a value of 1.In other words, a raised error or a return value of 1 indicates that the driver is a V1 driver.

property Camera.IsPulseGuiding: Boolean
Returns:

Indicates that the camera is currently executing a PulseGuide() operation. This duplicates the function of Telescope.IsPulseGuiding, except for hardware “guider cables”. See What Does PulseGuide() Do? I’m Confused.

Return type:

Boolean

Raises:

  • PropertyNotImplementedException – If the camera does not support pulse guiding (CanPulseGuide is False)

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • If IsPulseGuiding returns a valid True or False value, then the process of pulse-guiding is proceeding normally or has completed successfully, respectively.

  • IsPulseGuiding will be True immediately upon return from PulseGuide(). It will remain True until the requested pulse-guide interval has elapsed, and the pulse-guiding operation has been successfully completed. If PulseGuide() returns with IsPulseGuiding = False, then you can assume that the operation succeeded with a very short pulse-guide interval.

  • This duplicates the function of Telescope.IsPulseGuiding except using hardware “guider cables”. See What Does PulseGuide() Do? I’m Confused.

property Camera.LastExposureDuration: Float
Returns:

The actual duration of the last exposure in seconds

Return type:

Float

Raises:

  • PropertyNotImplementedException – If the camera doesn’t support this feature

  • InvalidOperationException – If no image has yet been successfully acquired.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

This may differ from the exposure duration requested due to shutter latency, camera timing precision, etc.

property Camera.LastExposureStartTime: String

Changed in version 2: (Platform 6.3) Clarified that the value must be in UTC.

Returns:

UTC start time of the last exposure in FITS standard format ISO-8601, UTC.

Return type:

String

Raises:

  • PropertyNotImplementedException – If the camera doesn’t support this feature

  • InvalidOperationException – If no image has yet been successfully acquired.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • Reports the actual exposure UTC start date/time in the FITS-standard / ISO-8601 CCYY-MM-DDThh:mm:ss[.sss…] format.

  • This must be the actual time at which the camera started to collect photons. This may differ from the time at which StartExposure() was called, due to shutter latency, camera timing precision, etc.

property Camera.MaxADU: Integer
Returns:

The maximum possible ADU value that the camera can produce in its current mode. See MaxADU, ElectronsPerADU, and FullWellCapacity in the Camera Interface.

Return type:

Integer

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

property Camera.MaxBinX: Integer
Returns:

The maximum supported X binning value of the camera in its current modes.

Return type:

Integer

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

If CanAsymmetricBin = False, returns the maximum allowed binning factor. If CanAsymmetricBin = True, returns the maximum allowed binning factor for the X axis.

property Camera.MaxBinY: Integer
Returns:

The maximum supported Y binning value of the camera in its current modes.

Return type:

Integer

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

If CanAsymmetricBin = False, returns the same value as MaxBinX. If CanAsymmetricBin = True, returns the maximum allowed binning factor for the Y axis.

property Camera.Name: String

Added in version 2: Member added.

Returns:

The short name of the driver, for display purposes.

Return type:

string

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

The Description property is used to return info about the device rather than the driver.

property Camera.NumX: Integer

Read/Write Set or return the current (sub)frame width. Combined with StartX > 0 to specify a subframe in the X dimension.

Returns:

The current X size of the image in binned pixels

Return type:

Integer

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

  • If binning is active, value is in binned pixels.

  • Immediately after completing an exposure, NumX will be the X dimension of ImageArray.

  • Must default to CameraXSize with StartX = 0 and BinX = 1 (full frame unbinned) on initial camera startup.

Warning

No error check is performed for incompatibilty with binning and subframe settings and capabilities when this property is changed. If these values are incompatible, the driver must throw an InvalidValueException from a subsequent call to StartExposure().

property Camera.NumY: Integer

Read/Write Set or return the current (sub)frame width. Combined with StartY > 0 to specify a subframe in the Y dimension.

Returns:

The current Y size of the image in binned pixels

Return type:

Integer

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

  • If binning is active, value is in binned pixels.

  • Immediately after completing an exposure, ‘’NumY’’ will be the Y dimension of ImageArray.

  • Must default to CameraYSize with StartY = 0 and BinY = 1 (full frame unbinned) on initial camera startup.

Warning

No error check is performed for incompatibilty with binning and subframe settings and capabilities. If these values are incompatible, the driver must throw an InvalidValueException from a subsequent call to StartExposure().

property Camera.Offset: Integer

Added in version 3: Member added.

Read/Write Gets or sets the current offset value or offsets index per its current offset-setting operating mode (see description below)

Returns:

The current offset value or Offsets index

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If Offset is not supported at all (neither Offsets Index nor Offset Value mode is supported.)

  • InvalidValueException – If the supplied value is not valid

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

If the camera can support several different operating modes where Offset and other parameters are different, it is better to use ReadoutMode and ReadoutModes to change all parameters in one go. If this approach is used, Gain and any other affected parameters must be kept in sync with operational values established by the readout mode.

Offset Modes Description

The Offset property is used to adjust the offset setting of the camera and has two modes of operation:

A driver can support none, one or both offset modes depending on the camera’s capabilities. However, only one mode can be active at any one moment because both modes share the Offset property to return the offset value. Your application can determine which mode is operational by reading the OffsetMin, OffsetMax property and this Offset property. If a property can be read then its associated mode is active, if it throws a PropertyNotImplementedException then the mode is not active.

Note

  • If a driver supports both modes the astronomer must be able to select the required mode through the driver Setup dialogue.

  • During driver initialisation the driver must set Offset to a valid value.

property Camera.OffsetMax: Integer

Added in version 3: Member added.

Returns:

The maximum offset value that this camera supports in Offset Value mode (see notes and Offset)

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If Offset is not supported at all or if the camera is operating in the Offsets Index mode.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

For Offsets Value mode

When Offset is operating in Offsets-Value mode:

Note

  • OffsetMin and OffsetMax act together and that either both must return values, or both must throw PropertyNotImplementedException.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.OffsetMin: Integer

Added in version 3: Member added.

Returns:

Minimum offset value that this camera supports in Offset Value mode (see notes and Offset)

Return type:

Integer

Raises:

  • PropertyNotImplementedException – If Offset is not supported at all or if the camera is operating in the Offsets Index mode.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

For Offset Value mode

When Offset is operating in Offset Value mode:

Note

  • OffsetMin and OffsetMax act together and that either both must return values, or both must throw PropertyNotImplementedException.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.Offsets: Array[String]

Added in version 3: Member added.

Returns:

Array (0-based) of Offset names supported by the camera when in Gains Index mode (see Notes and Offset)

Return type:

Array of strings

Raises:

  • PropertyNotImplementedException – If Offset is not supported at all or if the camera is operating in the Offsets Value mode.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

For Offsets-Index mode

When Offset is operating in the Offsets Index mode:

Note

  • Typically the application software will display the returned offset names in a drop list, from which the astronomer can select the desired offset’s name. The application can then configure the selected offset by setting the camera’s Offset property to the array index of the selected offset name.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.PercentCompleted: Integer

Added in version 2: Member added.

Returns:

The percentage completeness (0% - 100%) of the current exposure in progress

Return type:

Integer

Raises:

Note

  • If valid, returns an integer between 0 and 100, where 0 indicates 0% progress (function just started) and 100 indicates 100% progress (i.e. completion).

  • At the discretion of the device, PercentCompleted may optionally be valid when CameraState is in any or all of the following states:

    • cameraExposing

    • cameraWaiting

    • cameraReading

    • cameraDownload

    In all other states an InvalidOperationException must be raised.

  • Typically the application user interface will show a progress bar based on the PercentCompleted value.

property Camera.PixelSizeX: Float
Returns:

The physical width (microns) of the camera sensor elements.

Return type:

Float

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • Value must be greater than 0 microns

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.PixelSizeY: Float
Returns:

The physical height (microns) of the camera sensor elements.

Return type:

Float

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • Value must be greater than 0 microns

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.ReadoutMode: Integer

Added in version 2: Member added.

ReadoutModes are provided so the camera can offer a simple way to select combinations of gain, offset, analog-to-digital converter bit depth, and other operational parameters. Often the specific combinations of these parameters is chosen by the camera maker to support a specific usage of the camera. Each combination is given a name for ReadoutModes, for example “High Gain”, “Low Gain”, “Fast”, etc. The index in this array is written to ReadoutMode to select the mode to use. The name ReadoutMode is historical and should be construed to mean simply “mode”. See the Notes below.

Read/Write Gets or sets the index of the current camera readout mode in ReadoutModes array.

Returns:

The index in ReadoutModes array of the currently active camera readout mode.

Return type:

Integer

Raises:

Attention

Must be implemented if CanFastReadout is false, must throw a PropertyNotImplementedException if CanFastReadout is True. Please note that the FastReadout mechanic is now deprecated and should not be used in any new cameras.

Note

  • ReadoutMode is an index into the array ReadoutModes, and selects the desired readout mode for the camera. Defaults to 0 if not set.

  • It is strongly recommended, but not required, that cameras make the 0-index mode suitable for standard imaging operations, since it is the default.

  • The name ReadoutMode is historical, meaning a mode of reading the pixel data from the sensor. We can’t change the name, but with the advent of newer CMOS cameras, multiple combinations of gain, offset, analog-to-digital converter bit depth, and other operational parameters exist. Thus this property has been generalized to cover these combinations as modes.

Important

The ReadoutMode may interact with Gain and/or Offset of the camera; if so, the camera must ensure that the two properties do not conflict if both are used.

property Camera.ReadoutModes: Array[String]

Added in version 2: Member added.

ReadoutModes are provided so the camera can offer a simple way to select combinations of gain, offset, analog-to-digital converter bit depth, and other operational parameters. Often the specific combinations of these parameters is chosen by the camera maker to support a specific usage of the camera. Each combination is given a name for ReadoutModes, for example “High Gain”, “Low Gain”, “Fast”, etc. This array contains these names.

Returns:

Array (0-based) of ReadoutMode names supported by the camera (see notes and ReadoutMode)

Return type:

Array of Strings (0-based)

Raises:

Attention

Must be implemented if CanFastReadout is False, must throw a PropertyNotImplementedException if CanFastReadout is True.

Note

  • Readout modes may be available from the camera, and if so then CanFastReadout must be False. The two camera mode selection schemes are mutually exclusive.

  • This property provides an array of strings, each of which is the name of an available readout mode of the camera. At least one string will be present in the list. Your application may use this list to present to the user a drop-list of mode names. The choice of available modes made available is entirely at the discretion of the camera.

  • The default readout mode (on startup) must be ReadoutModes[0]. The device should reserve this for “standard” imaging operations since it is the power-up default.

  • To select a mode, set ReadoutMode to the index of the desired mode in ReadoutModes. The index is zero-based.

  • Applications should only read this property while a connection to the camera is actually established. Drivers often support multiple cameras with different capabilities, which are not known until the connection is made. If the available readout modes are not known because no connection has been established, this property shall throw A NotConnectedException.

property Camera.SensorName: String

Added in version 2: Member added.

Returns:

The name of the sensor used within the camera. See Notes

Return type:

String

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Mandatory, must return an empty string if the sensor’s name is not known.

Note

  • Returns the name (data sheet part number) of the sensor, e.g. ICX285. The format is to be exactly as shown on manufacturer data sheet, subject to the following rules:

    • All letters shall be upper-case.

    • Spaces shall not be included.

    • Any extra suffixes that define region codes, package types, temperature range, coatings, grading, colour/monochrome, etc. shall not be included.

    • For colour sensors, if a suffix differentiates different Bayer matrix encodings, it shall be included.

    • The property must return an empty string if the sensor name is not known

  • Examples:

    • ICX285AL-F shall be reported as ICX285

    • KAF-8300-AXC-CD-AA shall be reported as KAF-8300

  • The most common usage of this property is to select approximate colour balance parameters to be applied to the Bayer matrix of one-shot colour sensors. Application authors should assume that an appropriate IR cut-off filter is in place for colour sensors.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.SensorType: enum SensorType

Added in version 2: Member added.

Returns:

The type of sensor within the camera

Return type:

enum SensοrType

Raises:

  • PropertyNotImplementedException – If the sensor type is unknown or the device just doesn’t support this.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Note

  • See ImageArray for details on array shaping for various sensor types.

  • Please note that additional type values may be defined in future updates of the standard, as new Bayer matrices may be created by sensor manufacturers in the future. If this occurs, then a new enumeration value shall be defined. The pre-existing enumeration values shall not change.

  • It is recommended that this property be retrieved only after a connection is established with the camera hardware, to ensure that the driver is aware of the capabilities of the specific camera model.

property Camera.SetCCDTemperature: Float

Read/Write Get or set the camera’s cooler setpoint (degrees Celsius).

Returns:

The camera’s cooler temperature setpoint (degrees Celsius)

Return type:

Float

Raises:

Attention

Setting this property must be short-lived because it is only expected to establish the new setpoint and must not block until the setpoint has been reached or otherwise wait for any actual temperature changes.

Note

  • This method should be short-lived because it is only expected to ‘set’ the new set point and must not block until the set point has been reached.

  • The driver must throw an InvalidValueException if an attempt is made to set SetCCDTemperatureoutside the valid range for the camera. As an assistance to driver authors, to protect equipment and prevent harm to individuals, Conform will report an issue if it is possible to set SetCCDTemperature below -280C or above +100C.

  • Camera hardware and/or driver should perform cooler ramping to prevent thermal shock and potential damage to the CCD array or cooler stack, however a property-write to SetCCDTemperature must not wait for any temperature changes.

property Camera.StartX: Integer

Read/Write Set or return the current X-axis start position in binned pixels.

Subframe Feature: To set the camera to use a subframe on the sensor, first set the binning, then set StartX, NumX, StartY, and NumY to establish the binned area on the sensor to use for subsequent exposures. Each time an exposure completes, NumX and NumY will describe the dimensions of ImageArray.

Returns:

The current X-axis start position on the sensor in binned pixels.

Return type:

Integer

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Note

  • If binning is active, value is in binned pixels.

  • Defaults to 0 with NumX = CameraXSize (full frame) on initial camera startup.

property Camera.StartY: Integer

Read/Write Set or return the current Y-axis start position in binned pixels.

Subframe Feature: To set the camera to use a subframe on the sensor, first set the binning, then set StartX, NumX, StartY, and NumY to establish the binned area on the sensor to use for subsequent exposures. Each time an exposure completes, NumX and NumY will describe the dimensions of ImageArray.

Returns:

The current Y-axis start position on the sensor in binned pixels.

Return type:

Integer

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Note

  • If binning is active, value is in binned pixels.

  • Defaults to 0 with NumY = CameraYSize (full frame) on initial camera startup.

property Camera.SubExposureDuration: Float

Added in version 3: Member added.

(Read/Write) Sets the camera’s sub-exposure interval (seconds)

On-Board Subexposure Feature: This feature was added to Camera V3 to support CMOS cameras which can provide high dynamic range images via stacking of short duration images. It allows applications to avoid downloading and storing large image frames only to stack them on the client system resulting in a single image. Instead the camera may stack the short-duration images on-board and return the stacked result in ImageArray, saving both storage on the client system and transfer time of the subframes.

Returns:

The camera’s sub-exposure interval (seconds)

Return type:

Float

Raises:

  • PropertyNotImplementedException – If the camera does not support on-board stacking with user-supplied sub-exposure interval.

  • InvalidValueException – The supplied duration is not valid (negative or zero). See notes for other conditiopns.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

This is an optional property and can throw a PropertyNotImplementedException.

Note

  • This property provides for a camera to divide an exposure interval (as given to StartExposure()) into separate sub-exposures, then stack them internally, returning the final exposure to the client. This is often required with CMOS sensors to get the best dynamic range.

  • The SubExposureDuration must be checked against the Duration paremeter at the time of a call to StartExposure(). If the value makes no sense (longer than Duration or possibly an odd fraction of Duration), then StartExposure() must throw InvalidValueException. See notes for StartExposure().

property Camera.SupportedActions: COM: ArrayList of String elements, Alpaca: Array of String

Added in version 2: Recommended over (now) deprecated CommandBlind(), CommandBool(), and CommandString() as more flexible extension mechanic.

Returns the list of custom action names supported by this driver, to be used with Action(),

Returns:

The list of custom action names supported by this driver

Return type:

COM: ArrayList of String elements, Alpaca: Array of String

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This method, combined with Action(), is the supported mechanic for adding non-standard functionality.

  • SupportedActions is a “discovery” mechanism that enables clients to know which Actions a device supports without having to exercise the Actions themselves. This mechanism is necessary because there could be people / equipment safety issues if actions are called unexpectedly or out of a defined process sequence. It follows from this that SupportedActions must return names that match the spelling of custom action names exactly, without additional descriptive text. However, returned names may use any casing because the ActionName parameter of Action() is case insensitive.

Enumerated Constants

Camera.CameraStates: Integer

Current condition of the Camera. See State Transition Diagram for Camera.CameraState. Valid values are as follows:

Symbol

Val

Description

cameraIdle

0

At idle state, available to start exposure

cameraWaiting

1

Exposure started but waiting (for shutter, trigger, filter wheel, etc.)

cameraExposing

2

Exposure currently in progress

cameraReading

3

Sensor array is being read out (digitized)

cameraDownloading

4

Downloading data to host

cameraError

5

Camera error condition serious enough to prevent further operations
Camera.GuideDirections: Integer

The direction in which the guide-rate motion is to be made. See What Does PulseGuide() Do? I’m Confused.

Symbol

Val

Description

guideNorth

0

North (+ declination)

guideSouth

1

South (- declination)

guideEast

2

East (+ right ascension)

guideWest

3

West (- right ascension)
Camera.SensοrType: Integer

Type of sensor in the Camera.

Symbol

Val

Description

Monochrome

0

Single-plane monochrome

Color

1

Multiple-plane Color

RGGB

2

Single-plane Bayer matrix RGGB

CMYG

3

Single-plane Bayer matrix CMYG

CMYG2

4

Single-plane Bayer matrix CMYG2

LRGB

5

Single-plane Bayer matrix LRGB