Camera Class

Master Interfaces Reference

These green boxes in each interface member each have a link to the corresponding member definition in Master ICameraV4 Interface (external). The information in this Alpyca document is provided for your convenience. If there is any question, the info in ASCOM Master Interface Definitions (external) is the official specification.

Note

See the Example: Acquiring an Image, Creating FITS Image below.

class alpaca.camera.Camera(address: str, device_number: int, protocol: str = 'http')

Bases: Device

ASCOM Standard iCamera V4 Interface.

Initialize the Camera object

Parameters:

  • address (str) – IP address and port of the device (x.x.x.x:pppp)

  • device_number (int) – The index of the device (usually 0)

  • protocol (str, optional) – Only if device needs https. Defaults to “http”.

AbortExposure() → None

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

Raises:

Note

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

  • Will not raise an exception if the camera is already idle.

Master Interfaces Reference

Camera.AbortExposure() (external)

Action(ActionName: str, *Parameters) → str

Invoke the specified device-specific custom action

Common to all devices

Parameters:

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

  • *Parameters – List of required parameters or [] if none are required.

Returns:

String result of the action.

Raises:

Note

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

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Action(), find this specific device’s specification, and see Action() there.

CommandBlind(Command: str, Raw: bool) → None

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

Common to all devices

Parameters:

  • Command – The literal command string to be transmitted.

  • Raw – If true, command is transmitted ‘as-is’. If false, then protocol framing characters may be added prior to transmission.

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for CommandBlind(), find this specific device’s specification, and see CommandBlind() there.

CommandBool(Command: str, Raw: bool) → bool

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

Common to all devices

Returns:

The True/False response from the command

Parameters:

  • Command – The literal command string to be transmitted.

  • Raw – If true, command is transmitted ‘as-is’. If false, then protocol framing characters may be added prior to transmission.

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for CommandBlind(), find this specific device’s specification, and see CommandBlind() there.

CommandString(Command: str, Raw: bool) → str

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

Common to all devices

Returns:

The string response from the command

Parameters:

  • Command – The literal command string to be transmitted.

  • Raw – If true, command is transmitted ‘as-is’. If false, then protocol framing characters may be added prior to transmission.

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for CommandString(), find this specific device’s specification, and see CommandString() there.

Connect() → None

Connect to the device asynchronously.

Common to all devices

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Non-Blocking Use Connecting to indicate completion.

  • Natively present only in Platform 7 (2024) devices, but this library emulates Connect()/Disconnect()/Connecting mechanic for older devices.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Connect(), find this specific device’s specification, and see Connect() there.

Disconnect() → None

Disconnect from the device asynchronously.

Common to all devices

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Non-Blocking Use Connecting to indicate completion.

  • Natively present only in Platform 7 (2024) devices, but this library emulates Connect()/Disconnect()/Connecting mechanic for older devices.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Disconnect(), find this specific device’s specification, and see Disconnect() there.

PulseGuide(Direction: GuideDirections, Duration: int) → None

Pulse guide in the specified direction for the specified time (ms).

Non-blocking: See Notes, and How can I tell if my asynchronous request failed after being started?

Parameters:

  • Direction – GuideDirections

  • Interval – duration of the guide move, milliseconds

Raises:

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. See How can I tell if my asynchronous request failed after being started?

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

  • 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.

Master Interfaces Reference

Camera.PulseGuide() (external)

StartExposure(Duration: float, Light: bool) → None

Start an exposure.

Non-blocking: Returns with ImageReady = False if exposure has successfully been started. See How can I tell if my asynchronous request failed after being started?

Parameters:

  • Duration – Duration of exposure in seconds.

  • Light – True for light frame, False for dark frame.

Raises:

Note

Master Interfaces Reference

Camera.StartExposure() (external)

StopExposure() → None

Stop the current exposure, if any, and download the image data already acquired.

Raises:

Note

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

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

  • Will not raise an exception if the camera is already idle.

Master Interfaces Reference

Camera.StopExposure() (external)

property BayerOffsetX: int

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

Raises:

Note

  • The value returned will be in the range 0 to M-1 where M is the 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.

  • 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.

Master Interfaces Reference

Camera.BayerOffsetX (external)

property BayerOffsetY: int

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

Raises:

Note

  • The value returned will be in the range 0 to M-1 where M is the 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.

  • 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.

Master Interfaces Reference

Camera.BayerOffsetY (external)

property BinX: int

(Read/Write) Set or return the binning factor for the X axis.

Raises:

  • InvalidValueException – If the given binning value is invalid

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

  • If CanAssymetricBin is False, then the binning values must be the same. Setting this property will 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().

  • 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.

Master Interfaces Reference

Camera.BinX (external)

property BinY: int

(Read/Write) Set or return the binning factor for the Y axis.

Raises:

  • InvalidValueException – If the given binning value is invalid

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

  • If CanAssymetricBin is False, then the binning values must be the same. Setting this property will 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().

  • 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.

Master Interfaces Reference

Camera.BinY (external)

property CCDTemperature: float

The current CCD temperature in degrees Celsius.

Raises:

Master Interfaces Reference

Camera.CCDTemperature (external)

property CameraState: CameraStates

The camera’s operational state (CameraStates)

Raises:

  • NotConnectedException – If the camera status is unavailable

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Master Interfaces Reference

Camera.CameraState (external)

property CameraXSize: int

The width of the camera sensor in unbinned pixels

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.CameraXSize (external)

property CameraYSize: int

The height of the camera sensor in unbinned pixels

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.CameraYSize (external)

property CanAbortExposure: bool

The camera can abort exposures

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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 StopExposure()

  • 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.

Master Interfaces Reference

Camera.CanAbortExposure (external)

property CanAsymmetricBin: bool

The camera supports asymmetric binning

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • If true, the camera can have different binning on the X and Y axes, as determined by BinX and BinY. If false, the binning must be equal on the X and Y axes.

  • 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.

Master Interfaces Reference

Camera.CanAsymmetricBin (external)

property CanFastReadout: bool

The camera supports a fast readout mode

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.CanFastReadout (external)

property CanGetCoolerPower: bool

The camera’s cooler power level is available via CoolerPower

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.CanGetCoolerPower (external)

property CanPulseGuide: bool

The camera supports pulse guiding via PulseGuide()

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.CanPulseGuide (external)

property CanSetCCDTemperature: bool

The camera cooler temperature can be controlled

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

  • 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.

Master Interfaces Reference

Camera.CanSetCCDTemperature (external)

property CanStopExposure: bool

The camera can stop exposures

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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().

  • 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.

Master Interfaces Reference

Camera.CanStopExposure (external)

property Connected: bool

(Read/Write) Retrieve or set the connected state of the device.

Common to all devices

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.

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • 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.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Connected, find this specific device’s specification, and see Connected there.

property Connecting: bool

Returns True while the device is undertaking an asynchronous Connect() or Disconnect() operation.

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Use this property to determine when an (async) Connect() or Disconnect() has completed, at which time it will transition from True to False.

  • Natively present only in Platform 7 (2024) devices, but this library emulates Connect()/Disconnect()/Connecting mechanic for older devices.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Connecting, find this specific device’s specification, and see Connecting there.

property CoolerOn: bool

(Read/Write) Turn the camera cooler on and off or return the current cooler on/off state.

Raises:

Warning

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.

Master Interfaces Reference

Camera.CoolerOn (external)

property CoolerPower: float

The current cooler power level in percent.

Raises:

Master Interfaces Reference

Camera.CoolerPower (external)

property Description: str

Description of the device such as manufacturer and model number.

Common to all devices

Raises:

  • NotConnectedException – If the device status is unavailable

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

  • The description length will 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.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Description, find this specific device’s specification, and see Description there.

property DeviceState: List[dict]

List of key-value pairs representing the operational properties of the device

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for DeviceState, find this specific device’s specification, and see DeviceState there.

property DriverInfo: List[str]

Descriptive and version information about the ASCOM driver

Common to all devices

Returns:

Python list of strings (see Notes)

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • This describes the driver not the device. See the Description property for information on the device itself

  • The return is a Python list of strings, the total length of which may be hundreds to thousands of characters long. It is intended to display detailed information on the ASCOM (COM or Alpaca) driver, including version and copyright data. . To get the driver version in a parse-able string, use the DriverVersion property.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for DriverInfo, find this specific device’s specification, and see DriverInfo there.

property DriverVersion: str

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

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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. Note: on systems with a comma as the decimal point you may need to make accommodations to parse the value.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for DriverVersion, find this specific device’s specification, and see DriverVersion there.

property ElectronsPerADU: float

The gain of the camera in photoelectrons per A/D unit.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Some cameras have multiple gain modes, resulting in this value changing.

  • 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.

Master Interfaces Reference

Camera.ElectronsPerADU (external)

property ExposureMax: float

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

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.ExposureMax (external)

property ExposureMin: float

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

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.ExposureMin (external)

property ExposureResolution: float

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

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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 will choose the closest available value. Also in some cases the resolution may not be constant over the full range of exposure times; in this case the smallest increment will be chosen by the driver. A value of 0.0 indicates 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.

Master Interfaces Reference

Camera.ExposureResolution (external)

property FastReadout: bool

(Read/Write) Gets or sets Fast Readout Mode.

Raises:

Note

  • This function may in some cases interact with ReadoutModes; for example, there may be modes where the Fast/Normal switch is meaningless. In this case, it may be preferable to use the ReadoutModes feature to control fast/normal switching.

Master Interfaces Reference

Camera.FastReadout (external)

property FullWellCapacity: float

The full well capacity of the camera (see Notes).

Raises:

  • NotConnectedException – If the device is not connected.

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Reports the full well capacity of the camera in electrons, at the current camera settings (binning, SetupDialog settings, etc.).

  • 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.

Master Interfaces Reference

Camera.FullWellCapacity (external)

property Gain: int

(Read/Write) Gets or sets the current gain value or index (see Notes)

Raises:

Note

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 descriptions.

    • In this mode the Gains method returns a 0-based array of strings, which describe available gain settings e.g. “ISO 200”, “ISO 1600”

    • GainMin and GainMax will throw a NotImplementedException.

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

    • In this mode the GainMin and GainMax properties must return integers specifying the valid range for Gain.

    • The Gains array property will throw a NotImplementedException.

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 NotImplementedException then the mode is not active.

Important

The ReadoutMode may in some cases affect the gain of the camera; if so, the driver must ensure that the two properties do not conflict if both are used.

Master Interfaces Reference

Camera.Gain (external)

property GainMax: int

Maximum gain value that this camera supports (see notes and Gain)

Raises:

  • NotImplementedException – If the Gain property is not implemented or is operating in 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. The device did not successfully complete the request.

Note

When Gain is operating in gain-value mode:

  • GainMax must return the camera’s highest valid Gain setting

  • The Gains property will throw NotImplementedException

GainMax and GainMin act together and that either both will return values, or both will throw NotImplementedException.

  • 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.

Master Interfaces Reference

Camera.GainMax (external)

property GainMin: int

Minimum gain value that this camera supports (see notes and Gain)

Raises:

  • NotImplementedException – If the Gain property is not implemented or is operating in 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. The device did not successfully complete the request.

Note

When Gain is operating in gain-value mode:

  • GainMin must return the camera’s highest valid Gain setting

  • The Gains property will throw NotImplementedException

GainMin and GainMax act together and that either both will return values, or both will throw NotImplementedException.

  • 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.

Master Interfaces Reference

Camera.GainMin (external)

property Gains: List[str]

List of Gain names supported by the camera (see notes and Gain)

Raises:

  • NotImplementedException – If the Gain property is not implemented or is operating in gains-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. The device did not successfully complete the request.

Note

When Gain is operating in the gains-index mode:

  • The Gains property returns a list of available gain setting names.

  • The GainMax and GainMin properties will throw NotImplementedException.

The returned gain names could, for example, be a list of ISO settings for a DSLR camera or a list of gain names for a CMOS camera. Typically the application software will display the returned gain names in a drop list, from which the astronomer can select the required value. The application can then configure the required gain by setting the camera’s Gain property to the array index of the selected description.

  • 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.

Master Interfaces Reference

Camera.Gains (external)

property HasShutter: bool

Indicate whether the camera has a mechanical shutter.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

Master Interfaces Reference

Camera.HasShutter (external)

property HeatSinkTemperature: float

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

Raises:

Master Interfaces Reference

Camera.HeatSinkTemperature (external)

property ImageArray: List[int]

Return a multidimensional list containing the exposure pixel values.

Raises:

Note

  • The returned array is in row-major format, and typically must be transposed for use with numpy and astropy for creating FITS files. See the example below.

  • Automatically adapts to devices returning either JSON image data or the much faster ImageBytes format. In either case the returned nested list array contains standard Python int or float pixel values. See the Alpaca API Reference (external). See ImageArrayInfo for metadata covering the returned image data.

Master Interfaces Reference

Camera.ImageArray (external)

property ImageArrayInfo: ImageMetadata

Get image metadata sucn as dimensions, data type, rank.

See Class ImageMetadata for the properties available.

Note

If no image has been retrieved via ImageArray, this returns None.

Master Interfaces Reference

Camera.ImageArrayInfo (external)

property ImageReady: bool

Indicates that an image is ready to be downloaded.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions.The device cannot successfully complete the previous Expose() request (see Attention below).

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 download.

Attention

  • If the camera encounters a problem which prevents or prevented it from successfully completing the exposure, the driver will raise an exception when you attempt to read ImageReady.

Master Interfaces Reference

Camera.ImageReady (external)

property InterfaceVersion: int

ASCOM Device interface definition version that this device supports.

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • This is a single integer indicating the version of this specific ASCOM universal interface definition. For example, for ICameraV3, this will be 3. It should not to be confused with the DriverVersion property, which is the major.minor version of the driver for this device.

  • This value is cached internally after first retrieval since it is repeatedly used if emulating Connect/Disconnect semantics on older (pre - Platform 7) devioces.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for InterfaceVersion, find this specific device’s specification, and see InterfaceVersion there.

property IsPulseGuiding: bool

Indicates that the camera is currently in a PulseGuide() operation.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. See Attention below. The device did not successfully complete the request.

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.

Attention

  • If the camera encounters a problem which prevents it from successfully completing the the pulse-guiding operation, the driver will raise an exception when you attempt to read IsPulseGuiding.

Master Interfaces Reference

Camera.IsPulseGuiding (external)

property LastExposureDuration: float

Report the actual exposure duration in seconds (i.e. shutter open time).

Raises:

Note

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

Master Interfaces Reference

Camera.LastExposureDuration (external)

property LastExposureStartTime: str

Start time of the last exposure in FITS standard format, UTC.

Raises:

Note

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

Master Interfaces Reference

Camera.LastExposureStartTime (external)

property MaxADU: int

The maximum ADU value of the camera.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.MaxADU (external)

property MaxBinX: int

The maximum supported X binning value of the camera.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.MaxBinX (external)

property MaxBinY: int

The maximum supported Y binning value of the camera.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.MaxBinY (external)

property Name: str

The short name of the driver, for display purposes.

Common to all devices

Raises:

DriverException – If the driver cannot successfully complete the request. This exception may be encountered on any call to the device.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Name, find this specific device’s specification, and see Name there.

property NumX: int

(Read/Write) Set or return the current subframe width.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

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

Attention

  • No error check is performed for incompatibilty with BinX, and StartX, If these values are incompatible, you will receive an InvalidValueException from a subsequent call to StartExposure().

Master Interfaces Reference

Camera.NumX (external)

property NumY: int

(Read/Write) Set or return the current subframe height.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

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

Attention

  • No error check is performed for incompatibilty with BinY, and StartY, If these values are incompatible, you will receive an InvalidValueException from a subsequent call to StartExposure().

Master Interfaces Reference

Camera.NumY (external)

property Offset: int

(Read/Write) Gets or sets the current offset value or index (see Notes)

Raises:

Note

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

  • Offsets-Index: The Offset property is the selected offset’s index within the Offsets array of textual offset descriptions.

    • In this mode the Offsets method returns a 0-based array of strings, which describe available offset settings.

    • OffsetMin and OffsetMax will throw a NotImplementedException.

  • Offsets-Value: The Offset property is a direct numeric representation of the camera’s offset.

    • In this mode the OffsetMin and OffsetMax properties must return integers specifying the valid range for Offset.

    • The Offsets array property will throw a NotImplementedException.

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 NotImplementedException then the mode is not active.

Important

The ReadoutMode may in some cases affect the offset of the camera; if so, the driver must ensure that the two properties do not conflict if both are used.

Master Interfaces Reference

Camera.Offset (external)

property OffsetMax: int

Maximum offset value that this camera supports (see notes and Offset)

Raises:

  • NotImplementedException – If the Offset property is not implemented or is operating in 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. The device did not successfully complete the request.

Note

When Offset is operating in offsets-value mode:

  • OffsetMax must return the camera’s highest valid Offset setting

  • The Offsets property will throw NotImplementedException

OffsetMax and OffsetMin act together and that either both will return values, or both will throw NotImplementedException.

  • 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.

Master Interfaces Reference

Camera.OffsetMax (external)

property OffsetMin: int

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

Raises:

  • NotImplementedException – If the Offset property is not implemented or is operating in 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. The device did not successfully complete the request.

Note

When Offset is operating in offsets-value mode:

  • OffsetMin must return the camera’s highest valid Offset setting

  • The Offsets property will throw NotImplementedException.

OffsetMin and OffsetMax act together and that either both will return values, or both will throw NotImplementedException.

  • 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.

Master Interfaces Reference

Camera.OffsetMin (external)

property Offsets: List[str]

List of Offset names supported by the camera (see notes and Offset)

Raises:

  • NotImplementedException – If the Offset property is not implemented or is operating in 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. The device did not successfully complete the request.

Note

When Offset is operating in the offsets-index mode:

  • The Offsets property returns a list of available offset setting names.

  • The OffsetMax and OffsetMin properties will throw NotImplementedException.

The returned offset names could, for example, be a list of ISO settings for a DSLR camera or a list of offset names for a CMOS camera. Typically the application software will display the returned offset names in a drop list, from which the astronomer can select the required value. The application can then configure the required offset by setting the camera’s Offset property to the array index of the selected description.

  • 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.

Master Interfaces Reference

Camera.Offsets (external)

property PercentCompleted: int

The percentage completeness of this operation

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

    • cameraDownloading

In all other states an InvalidOperationException will be raised.

Attention

  • If the camera encounters a problem which prevents or prevented it from successfully completing the operation, the driver will raise an exception when you attempt to read PercentComplete.

Master Interfaces Reference

Camera.PercentCompleted (external)

property PixelSizeX: float

The width (microns) of the camera sensor elements.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.PixelSizeX (external)

property PixelSizeY: float

The height (microns) of the camera sensor elements.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.PixelSizeY (external)

property ReadoutMode: int

(Read/Write) Gets or sets the current camera readout mode (see Notes)

Raises:

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.

Important

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

Master Interfaces Reference

Camera.ReadoutMode (external)

property ReadoutModes: List[str]

List of ReadoutMode names supported by the camera (see notes and ReadoutMode)

Raises:

Note

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

  • This property provides an array of strings, each of which describes 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 modes. The choice of available modes made available is entirely at the discretion of the camera. Please note that if the camera has many different modes of operation, then the most commonly adjusted settings will probably be in ReadoutModes; additional settings may be provided using SetupDialog().

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

  • 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.

Master Interfaces Reference

Camera.ReadoutModes (external)

property SensorName: str

The name of the sensor used within the camera.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

    • All letters will be upper-case.

    • Spaces will not be included.

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

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

    • The property will 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.

Master Interfaces Reference

Camera.SensorName (external)

property SensorType: SensorType

The type of sensor within the camera.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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.

Master Interfaces Reference

Camera.SensorType (external)

property SetCCDTemperature: float

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

Raises:

  • InvalidValueException – If set to a value outside the camera’s valid temperature setpoint range.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Master Interfaces Reference

Camera.SetCCDTemperature (external)

property StartX: int

(Read/Write) Set or return the current X-axis subframe start position.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

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

Attention

  • No error check is performed for incompatibilty with BinX, and NumX, If these values are incompatible, you will receive an InvalidValueException from a subsequent call to StartExposure().

Master Interfaces Reference

Camera.StartX (external)

property StartY: int

(Read/Write) Set or return the current Y-axis subframe start position.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

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

Attention

  • No error check is performed for incompatibilty with BinY, and NumY, If these values are incompatible, you will receive an InvalidValueException from a subsequent call to StartExposure().

Master Interfaces Reference

Camera.StartY (external)

property SubExposureDuration: float

(Read/Write) Set or return the camera’s sub-exposure interval (sec)

Raises:

Master Interfaces Reference

Camera.SubExposureDuration (external)

property SupportedActions: List[str]

The list of custom action names supported by this driver

Common to all devices

Returns:

Python list of strings (see Notes)

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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 Action() names exactly, without additional descriptive text. However, returned names may use any casing because the ActionName parameter of Action() is case insensitive.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for SupportedActions, find this specific device’s specification, and see SupportedActions there.

ImageMetadata Class

class alpaca.camera.ImageMetadata(metadata_version: int, image_element_type: ImageArrayElementTypes, transmission_element_type: ImageArrayElementTypes, rank: int, num_x: int, num_y: int, num_z: int)

Bases: object

Metadata describing the returned ImageArray data

Note

property Dimension1

The first (X) dimension of the image array

property Dimension2

The second (Y) dimension of the image array

property Dimension3

The third (Z) dimension of the image array (None or 3)

property ImageElementType: ImageArrayElementTypes

The data type of the pixels in originally acquired image

Note

Within Python, the returned nested list(s) image pixels themselves will be either int or float.

property MetadataVersion

The version of metadata, currently 1

property Rank

The matrix rank of the image data (either 2 or 3)

property TransmissionElementType: ImageArrayElementTypes

The ddta type of the pixels in the transmitted image bytes stream

Note

Within Python, the returned image pixels themselves will be either int or float.

To save transmission time camera may choose to use a smaller data type than the original image if the pixel values would all be representative in that data type without a loss of precision.

Example: Acquiring an Image, Creating FITS Image

Using numpy and astropy.io.fits, connect to an Alpaca Camera, acquire a short image, download and make a local FITS file:

import os
import time
import array
from alpaca.camera import *     # Sorry Python purists, this has multiple required Classes
import numpy as np
import astropy.io.fits as fits

#
# Set up the camera
#
c = Camera('localhost:32323', 0)    # Connect to the ALpaca Omni Simulator
c.Connected = True
c.BinX = 1
c.BinY = 1
# Assure full frame after binning change
c.StartX = 0
c.StartY = 0
c.NumX = c.CameraXSize // c.BinX    # Watch it, this needs to be an int (typ)
c.NumY = c.CameraYSize // c.BinY
#
# Acquire a light image, wait while printing % complete
#
c.StartExposure(2.0, True)
while not c.ImageReady:
    time.sleep(0.5)
    print(f'{c.PercentCompleted}% complete')
print('finished')
#
# OK image acquired, grab the image array and the metadata
#
img = c.ImageArray
imginfo = c.ImageArrayInfo
if imginfo.ImageElementType == ImageArrayElementTypes.Int32:
    if c.MaxADU <= 65535:
        imgDataType = np.uint16 # Required for BZERO & BSCALE to be written
    else:
        imgDataType = np.int32
elif imginfo.ImageElementType == ImageArrayElementTypes.Double:
    imgDataType = np.float64
#
# Make a numpy array of he correct shape for astropy.io.fits
#
if imginfo.Rank == 2:
    nda = np.array(img, dtype=imgDataType).transpose()
else:
    nda = np.array(img, dtype=imgDataType).transpose(2,1,0)
#
# Create the FITS header and common FITS fields
#
hdr = fits.Header()
hdr['COMMENT'] = 'FITS (Flexible Image Transport System) format defined in Astronomy and'
hdr['COMMENT'] = 'Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.'
hdr['COMMENT'] = 'Contact the NASA Science Office of Standards and Technology for the'
hdr['COMMENT'] = 'FITS Definition document #100 and other FITS information.'
if imgDataType ==  np.uint16:
    hdr['BZERO'] = 32768.0
    hdr['BSCALE'] = 1.0
hdr['EXPOSURE'] = c.LastExposureDuration
hdr['EXPTIME'] = c.LastExposureDuration
hdr['DATE-OBS'] = c.LastExposureStartTime
hdr['TIMESYS'] = 'UTC'
hdr['XBINNING'] = c.BinX
hdr['YBINNING'] = c.BinY
hdr['INSTRUME'] = c.SensorName
try:
    hdr['GAIN'] = c.Gain
except:
    pass
try:
    hdr['OFFSET'] = c.Offset
    if type(c.Offset == int):
        hdr['PEDESTAL'] = c.Offset
except:
    pass
hdr['HISTORY'] = 'Created using Python alpyca-client library'
#
# Create the final FITS from the numpy array and FITS info
#
hdu = fits.PrimaryHDU(nda, header=hdr)

img_file = f"{os.getenv('USERPROFILE')}/Desktop/test.fts"
hdu.writeto(img_file, overwrite=True)
c.Connected = False

print("Booyah! Your FITS image is ready.")

Resulting FITS header:

Header listing for HDU #1:
SIMPLE  =                    T / conforms to FITS standard
BITPIX  =                   16 / array data type
NAXIS   =                    2 / number of array dimensions
NAXIS1  =                 1280
NAXIS2  =                 1024
EXPOSURE=            2.0052547
EXPTIME =            2.0052547
DATE-OBS= '2022-04-15T18:20:50'
TIMESYS = 'UTC     '
XBINNING=                    1
YBINNING=                    1
INSTRUME= 'MyCamera'
BSCALE  =                    1
BZERO   =                32768
COMMENT FITS (Flexible Image Transport System) format defined in Astronomy and
COMMENT Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.
COMMENT Contact the NASA Science Office of Standards and Technology for the
COMMENT FITS Definition document #100 and other FITS information.
HISTORY Created using Python alpyca-client library
END