dl::ICamera Class Referenceabstract

Camera interface class. More...

#include <dlapi.h>

Classes

struct  Info
 
struct  Status
 

Public Types

enum  State { Uninitialized, Initializing, Ready, Error }
 
enum  Model {
  Aluma, Reserved1, Reserved2, AlumaCMOS,
  StarChaser, STC, AlumaAC2020, StarChaserE,
  Reserved8, InvalidCameraModel = 0xff, Reserved4 = StarChaser, Reserved5 = STC,
  Reserved3 = AlumaCMOS, Reserved6 = AlumaAC2020, Reserved7 = StarChaserE, StarChaserP3 = StarChaserE
}
 
enum  Capability {
  eSupportsFan, eSupportsCooler, eSupportsCoolerTemp, eSupportsHeatSinkTemp,
  eSupportsAdaptiveOptics, eSupportsFilterWheel, eSupportsGuidePort, eSupportsWiFi,
  eSupportsDefogHeater, eSupportsSensorGainOffset, eSupportsInternalStacking, eSupportsFastContinuousReadout,
  eSupportsShutter, eSupportsPrecisionCoolerPower, eSupportsExtendedStartDownload, eSupportsInputVoltage,
  eSupportsOverscan, eSupportsOnChipBinning, eSupportsAdjustableGain, eSupportsPeripheralInfo,
  CameraCapabilityCount, InvalidCameraCapability = 0xff
}
 

Public Member Functions

virtual ~ICamera ()=0
 virtual destructor ensuring the class is abstract. More...
 
virtual bool initialize ()=0
 Initializes the camera by fetching operational status, and initializing the various peripherals. More...
 
virtual IPromisePtr queryInfo ()=0
 Queries the camera's unit information structure (ICamera::Info) More...
 
virtual IPromisePtr queryStatus ()=0
 Queries the camera's ICamera::Status structure. More...
 
virtual IPromisePtr queryNetworkSettings ()=0
 Queries the camera's network settings. More...
 
virtual IPromisePtr queryCapability (ICamera::Capability key)=0
 Queries a camera for a specific capability. More...
 
virtual IPromisePtr pulseGuide (EPulseGuideDirection direction, unsigned int duration, bool abort)=0
 Executes or aborts a pulse guide operation of given duration and direction. More...
 
virtual IPromisePtr setNetworkSettings (const TNetworkSettings &cfg)=0
 Updates the camera's network settings. More...
 
virtual ICamera::Info getInfo () const =0
 Returns the buffered ICamera::Info structure. More...
 
virtual void getSerial (char *buffer, size_t &buffer_length) const =0
 Returns a human readable version of the camera's serial number string. e.g. "AL8300M-19010101". More...
 
virtual EEndpointType getConnectionType () const =0
 Returns the connection type of the camera (USB, Networked, etc). More...
 
virtual void getConnectionInfo (char *buffer, size_t &buffer_length) const =0
 Returns a human readable information string about the camera's connection (IP Address, USB Handle, etc). More...
 
virtual ICamera::Status getStatus () const =0
 Returns the buffered status structure. More...
 
virtual bool getCapability (ICamera::Capability key) const =0
 Returns the buffered value of a successful call to ICamera::queryCapability() More...
 
virtual TNetworkSettings getNetworkSettings () const =0
 Returns the buffered network settings. More...
 
virtual ISensorPtr getSensor (unsigned int id) const =0
 Returns a pointer to the indexed sensor (zero is always the primary imaging chip). More...
 
virtual ITECPtr getTEC () const =0
 Returns a pointer to the camera's TEC (if one is available). More...
 
virtual IAOPtr getAO () const =0
 Returns a pointer to the camera's AO (if one is available). More...
 
virtual IFWPtr getFW () const =0
 Returns a pointer to the camera's FW (if one is available). More...
 

Detailed Description

Camera interface class.

An interface to a DLAPI compliant camera providing general access to camera-level functions/settings, and stores references to connected peripherals/imaging sensors. Each instance of ICamera is self-contained, and can safely be used in tandem with other instances of ICamera. Because Camera I/O is threaded at the DLAPI level, the number of ICamera instances you can control simultaneously is limited by the number of active threads your system can have at any given time.

Further to this limitation, each ICamera instance has references to a number of ISensor instances. While these instances are self-contained, DLAPI is not capable of performing simultaneous downloads of two sensors on the same camera at this time. Attempting to call image transport functions for one sensor while another sensor is in the ISensor::ReadyToDownload state will return an error (specifically EStatusCode::ReadoutInProgress).

Member Enumeration Documentation

◆ Capability

Enumerator
eSupportsFan 

Camera supports control of an internal fan.

eSupportsCooler 

Camera supports control of an internal cooler.

eSupportsCoolerTemp 

Camera supports querying of cooler temperature.

eSupportsHeatSinkTemp 

Camera supports querying of heat sink temperature.

eSupportsAdaptiveOptics 

Camera supports control of Adaptive Optics peripheral.

eSupportsFilterWheel 

Camera supports control of Filter Wheel peripheral.

eSupportsGuidePort 

Camera supports control of a guide system via a guide port.

eSupportsWiFi 

Camera supports communication over WiFi networks (and thus, the commands for network settings)

eSupportsDefogHeater 

Camera has a window heater for defogging the sensor window.

eSupportsSensorGainOffset 

Camera supports the control of ADC gain/offset manipulation.

eSupportsInternalStacking 

Camera supports exposing as a series of short sub-exposures, stacked in the camera to a single images.

eSupportsFastContinuousReadout 

Camera supports continuous readout between exposures (i.e. when operated in "Fast Mode", camera will not report idle between exposures)

eSupportsShutter 

Camera supports the use of a shutter.

eSupportsPrecisionCoolerPower 

Camera supports querying of precision cooler power, calculated in the camera (rather than converted by the API)

eSupportsExtendedStartDownload 
eSupportsInputVoltage 
eSupportsOverscan 
eSupportsOnChipBinning 
eSupportsAdjustableGain 

Camera supports the use of adjustable analog gains.

eSupportsPeripheralInfo 

Camera supports the retrieval of connected peripheral information.

CameraCapabilityCount 

Number of camera capability keys to query.

InvalidCameraCapability 

Capability has not been initialized/reported an invalid/unsupported feature.

1633  {
1634  eSupportsFan,
1635  eSupportsCooler,
1641  eSupportsWiFi,
1654 
1656  InvalidCameraCapability = 0xff
1657  };
Camera supports control of Adaptive Optics peripheral.
Definition: dlapi.h:1638
Camera supports control of Filter Wheel peripheral.
Definition: dlapi.h:1639
Camera supports continuous readout between exposures (i.e. when operated in "Fast Mode",...
Definition: dlapi.h:1645
Camera supports exposing as a series of short sub-exposures, stacked in the camera to a single images...
Definition: dlapi.h:1644
Camera supports querying of cooler temperature.
Definition: dlapi.h:1636
Camera supports the retrieval of connected peripheral information.
Definition: dlapi.h:1653
Camera supports communication over WiFi networks (and thus, the commands for network settings)
Definition: dlapi.h:1641
Camera supports the control of ADC gain/offset manipulation.
Definition: dlapi.h:1643
Camera has a window heater for defogging the sensor window.
Definition: dlapi.h:1642
Camera supports control of an internal fan.
Definition: dlapi.h:1634
Camera supports control of an internal cooler.
Definition: dlapi.h:1635
Number of camera capability keys to query.
Definition: dlapi.h:1655
Definition: dlapi.h:1650
Camera supports the use of adjustable analog gains.
Definition: dlapi.h:1652
Camera supports querying of precision cooler power, calculated in the camera (rather than converted b...
Definition: dlapi.h:1647
Camera supports querying of heat sink temperature.
Definition: dlapi.h:1637
Definition: dlapi.h:1651
Camera supports the use of a shutter.
Definition: dlapi.h:1646
Capability has not been initialized/reported an invalid/unsupported feature.
Definition: dlapi.h:1656
Definition: dlapi.h:1649
Camera supports control of a guide system via a guide port.
Definition: dlapi.h:1640

◆ Model

Enumerator
Aluma 

00 Aluma and AlumaCCD model cameras

Reserved1 

01 Reserved for future use

Reserved2 

02 Reserved for future use

AlumaCMOS 

03 Aluma AC4040 and AC4040BSI

StarChaser 

04 StarChaser model cameras

STC 

05 STC-7 and STC-428

AlumaAC2020 

06 Aluma AC2020 only

StarChaserE 

07 StarChaser E (new P3 variant)

Reserved8 

08 Reserved for future use

InvalidCameraModel 

Camera has not been initialized/reported invalid model.

Reserved4 

Historical Convenience.

Reserved5 
Reserved3 
Reserved6 
Reserved7 
StarChaserP3 
1609  {
1610  Aluma,
1611  Reserved1,
1612  Reserved2,
1613  AlumaCMOS,
1614  StarChaser,
1615  STC,
1616  AlumaAC2020,
1617  StarChaserE,
1618  Reserved8,
1619 
1620  InvalidCameraModel = 0xff,
1621  Reserved4 = StarChaser,
1622  Reserved5 = STC,
1623  Reserved3 = AlumaCMOS,
1627  };
08 Reserved for future use
Definition: dlapi.h:1618
07 StarChaser E (new P3 variant)
Definition: dlapi.h:1617
05 STC-7 and STC-428
Definition: dlapi.h:1615
Definition: dlapi.h:1625
03 Aluma AC4040 and AC4040BSI
Definition: dlapi.h:1613
06 Aluma AC2020 only
Definition: dlapi.h:1616
Definition: dlapi.h:1624
Definition: dlapi.h:1623
04 StarChaser model cameras
Definition: dlapi.h:1614
Definition: dlapi.h:1622
01 Reserved for future use
Definition: dlapi.h:1611
02 Reserved for future use
Definition: dlapi.h:1612
00 Aluma and AlumaCCD model cameras
Definition: dlapi.h:1610
Camera has not been initialized/reported invalid model.
Definition: dlapi.h:1620
Historical Convenience.
Definition: dlapi.h:1621
Definition: dlapi.h:1626

◆ State

Enumerator
Uninitialized 
Initializing 
Ready 
Error 
1598  {
1599  Uninitialized, //<! Uninitialized Camera is uninitialized.
1600  Initializing, //<! Initializing Camera is in process of initializing.
1601  Ready, //<! Ready Camera is ready for operation.
1602  Error //<! Error Camera has had an error.
1603  };
Definition: dlapi.h:1599
Definition: dlapi.h:1602
Definition: dlapi.h:1600
Definition: dlapi.h:1601

Constructor & Destructor Documentation

◆ ~ICamera()

virtual dl::ICamera::~ICamera ( )
pure virtual

virtual destructor ensuring the class is abstract.

Used to ensure ICamera is pure virtual

Member Function Documentation

◆ getAO()

virtual IAOPtr dl::ICamera::getAO ( ) const
pure virtual

Returns a pointer to the camera's AO (if one is available).

Returns
IAOPtr a pointer to the camera's adaptive optics unit.
See also
IAO

Returns a pointer to the camera's adaptive optics unit, or nullptr if no AO is present.

◆ getCapability()

virtual bool dl::ICamera::getCapability ( ICamera::Capability  key) const
pure virtual

Returns the buffered value of a successful call to ICamera::queryCapability()

Parameters
keythe ICamera::Capability key to retrieve. Each key requires a separate call to ICamera::queryCapability();
Returns
bool true if the camera feature is supported, false otherwise.

◆ getConnectionInfo()

virtual void dl::ICamera::getConnectionInfo ( char *  buffer,
size_t &  buffer_length 
) const
pure virtual

Returns a human readable information string about the camera's connection (IP Address, USB Handle, etc).

Parameters
buffera buffer to a character array.
buffer_lengththe maximum size of the supplied buffer, updated to be the length of the information string.

Returns a human readable string containing connection details about this camera. This is mostly for debug purposes. e.g. "USB: handle=0x1234", or "Net: ip="127.0.0.1"

{c++}
std::string getConnectionInfo(dl::ICameraPtr pCamera)
{
char buf[512] = {0};
size_t lng = 512;
pCamera->getConnectionInfo(&(buf[0]), lng);
return std::string(&(buf[0]), lng);
}

◆ getConnectionType()

virtual EEndpointType dl::ICamera::getConnectionType ( ) const
pure virtual

Returns the connection type of the camera (USB, Networked, etc).

Returns
EEndpointType Information about the camera's connection type.
See also
EEndpointType for more information.
EEndpointType

Returns the camera's connection type: USB, Net, etc. See EEndpointType for more details.

◆ getFW()

virtual IFWPtr dl::ICamera::getFW ( ) const
pure virtual

Returns a pointer to the camera's FW (if one is available).

Returns
a pointer to the camera's filter wheel.
See also
IFW

Returns a pointer to the camera's filter wheel unit, or nullptr if no FW is present.

◆ getInfo()

virtual ICamera::Info dl::ICamera::getInfo ( ) const
pure virtual

Returns the buffered ICamera::Info structure.

Returns
ICamera::Info the buffered camera info structure.
See also
ICamera::Info, ICamera::queryInfo()

Returns the buffered camera info structure, refreshed by ICamera::queryInfo().

◆ getNetworkSettings()

virtual TNetworkSettings dl::ICamera::getNetworkSettings ( ) const
pure virtual

Returns the buffered network settings.

Returns
TNetworkSettings the buffered camera info structure.
See also
TNetworkSettings, ICamera::setNetworkSettings(), ICamera::queryNetworkSettings()

Returns the buffered camera network settings structure, refreshed by ICamera::queryNetworkSettings().

◆ getSensor()

virtual ISensorPtr dl::ICamera::getSensor ( unsigned int  id) const
pure virtual

Returns a pointer to the indexed sensor (zero is always the primary imaging chip).

Parameters
idthe internal index of the sensor to retrieve
Returns
ISensorPtr a pointer to the sensor with id.
See also
ISensor, ICamera::getInfo()

This function retrieves a pointer to the camera's sensor with internal id matching the supplied parameter. The internal sensor id is a zero based index, starting with the main sensor, and increasing with external sensors up to the number of sensors a camera has is stored in the ICamera::Info::numberOfSensors variable. If a user attempts to access a sensor outside that range, or the sensor is otherwise unavailable, the function returns nullptr.

◆ getSerial()

virtual void dl::ICamera::getSerial ( char *  buffer,
size_t &  buffer_length 
) const
pure virtual

Returns a human readable version of the camera's serial number string. e.g. "AL8300M-19010101".

Parameters
bufferpointer to a character array which receives the serial number string.
buffer_length[IN] the maximum size of the buffer supplied, [OUT] the size of the string returned.
Returns
ICamera::Info the buffered camera info structure.
See also
ICamera::Info, ICamera::queryInfo()

Returns the human-readable serial number string of the camera, which requires the camera be properly initialized. Normally, this is handled on discovery by the API, but if an error occurs, you can manually initialize the camera by calling the following functions:

or calling ICamera::initialize().

n.b. This differs from the ICamera::Info::serialNumber in that serialNumber contains a subset of the information required to recreate the human-readable serial number string.

e.g.

{c++}
std::string getSerial(dl::ICameraPtr pCamera)
{
char buf[512] = {0};
size_t lng = 512;
pCamera->getSerial(&(buf[0]), lng);
return std::string(&(buf[0]), lng);
}

◆ getStatus()

virtual ICamera::Status dl::ICamera::getStatus ( ) const
pure virtual

Returns the buffered status structure.

Returns
ICamera::Status the buffered camera status structure.
See also
ICamera::Status, ICamera::queryStatus()

Returns the buffered camera status structure, refreshed by ICamera::queryStatus().

◆ getTEC()

virtual ITECPtr dl::ICamera::getTEC ( ) const
pure virtual

Returns a pointer to the camera's TEC (if one is available).

Returns
ITECPtr a pointer to the camera's thermo-electric cooler.
See also
ITEC

Returns a pointer to the camera's thermo-electric cooler, or nullptr if no TEC is present.

◆ initialize()

virtual bool dl::ICamera::initialize ( )
pure virtual

Initializes the camera by fetching operational status, and initializing the various peripherals.

A blocking call which queries the camera for all relevant information stuctures:

Throws a std::runtime_error on failure.

◆ pulseGuide()

virtual IPromisePtr dl::ICamera::pulseGuide ( EPulseGuideDirection  direction,
unsigned int  duration,
bool  abort 
)
pure virtual

Executes or aborts a pulse guide operation of given duration and direction.

Parameters
directionthe relay direction to fire.
See also
EPulseGuideDirection
Parameters
durationthe duration of the pulse guide operation in milliseconds.
abortset to true to abort a previous pulse guide operation, false to execute a new operation.
Returns
IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.
See also
IPromisePtr, EPulseGuideDirection, ICamera::getStatus()

Command the guider port output to move the mount in the provided direction, for the provided duration, or abort the current operation if abort is set to true.

The status of the current pulse guide operation is stored in the camera's ICamera::Status structure.

◆ queryCapability()

virtual IPromisePtr dl::ICamera::queryCapability ( ICamera::Capability  key)
pure virtual

Queries a camera for a specific capability.

Parameters
keythe capability you wish to retrieve from the camera.
Returns
IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.
See also
IPromisePtr, ICamera::Capability, ICamera::getCapability()

Queries the camera for the ICamera::Capability key passed in. Currently, they are used to denote support for specific features (like filter wheels and adaptive optics peripherals), but also for support to various parts of the camera (heat-sink temperature monitoring, or the use of a fan). They can be retrieved via a call to ICamera::getCapability().

e.g.

{c++}
bool getCapability(ICameraPtr pCamera, ICamera::Capability capability)
{
if (!pCamera) return false; // Always null-guard. You could also throw an exception here.
auto pPromise = pCamera->queryCapability(cap);
if (!handlePromise(pPromise)) return false; // We failed to query the camera. You could also throw an exception here.
return pCamera->getCapability(cap);
}

◆ queryInfo()

virtual IPromisePtr dl::ICamera::queryInfo ( )
pure virtual

Queries the camera's unit information structure (ICamera::Info)

Returns
IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.
See also
IPromisePtr, ICamera::getInfo()

Queries the camera for the ICamera::Info structure, retrieve the structure on promise completion with a call to ICamera::getInfo().

◆ queryNetworkSettings()

virtual IPromisePtr dl::ICamera::queryNetworkSettings ( )
pure virtual

Queries the camera's network settings.

Returns
IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.
See also
IPromisePtr, ICamera::getNetworkSettings(), ICamera::setNetworkSettings()

Queries the camera for the ICamera::NetworkStettings structure, retrieve the structure on promise completion with a call to ICamera::getStatus().

◆ queryStatus()

virtual IPromisePtr dl::ICamera::queryStatus ( )
pure virtual

Queries the camera's ICamera::Status structure.

Returns
IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.
See also
IPromisePtr, ICamera::getStatus()

Queries the camera for the ICamera::Status structure, retrieve the structure on promise completion with a call to ICamera::getStatus().

◆ setNetworkSettings()

virtual IPromisePtr dl::ICamera::setNetworkSettings ( const TNetworkSettings cfg)
pure virtual

Updates the camera's network settings.

Parameters
cfgthe new network configuration
Returns
IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.
See also
IPromisePtr, TNetworkSettings, ICamera::queryNetworkSettings(), ICamera::getNetworkSettings()

Updates the network settings of the camera.


The documentation for this class was generated from the following file:
  • C:/NightlyBuild/DL_Imaging/Aluma_Software/dlapi/src/dlapi.h