Sensor Interface Class. More...

#include <dlapi.h>

Classes
struct	Calibration
	A data structure containing all factory-calibrated sensor characterization. More...

struct	Info
	A data structure containing sensor specifications. More...

struct	Settings
	C-style settings structure with built-in type conversion. More...

Public Types
enum	Model { RESERVED1 = 0x00 , RESERVED2 = 0x01 , ICX694 = 0x02 , ICX814 = 0x03 , CCD4710 = 0x04 , CCD7700 = 0x05 , RESERVED3 = 0x06 , RESERVED4 = 0x07 , RESERVED5 = 0x09 , RESERVED6 = 0x08 , KAF3200 = 0x0a , KAF8300 = 0x0b , RESERVED7 = 0x10 , RESERVED8 = 0x11 , RESERVEDB1 = 0x100 , RESERVEDC1 = 0x200 , GSENSE4040 = 0x300 , GSENSE4040BSI , GSENSE2020 = 0x600 , P1300 = 0x400 , IMX428 = 0x500 , IMX428_7 , IMX290 = 0x800 , IMX455 = 0x900 , InvalidSensorModel = 0xFF }

enum	Status { Idle , Trigger , PreShutter , DoShutterOpen , Starting , Exposing , DoShutterClose , Reading , ReadyToDownload , HomingShutter , InvalidSensorState = 0xFF }

enum	Setting { UseOverscan , RBIPreflashDuration , RBIPreflashFlushCount , UseWindowHeater , FanSpeed , ToggleIRLEDs , UseOnChipBinning , UseExtTrigger , AutoFanMode , ShutterPolarity , EnableStatusLED , PartialExposureLength , UseFWAsShutter , AnalogGain0 , AnalogGain1 , ContinuousExposure , SettingCount , SoftwareBinMode = 0x10000000 , SoftwareSettingCount , FirstSensorSetting = UseOverscan , FirstSoftwareSetting = SoftwareBinMode , InvalidSensorSetting = 0xff }

enum class	SoftwareBinningMode : int { SumAndClip , Average , Count , First = SumAndClip , Default = SumAndClip }

enum	CalibrationKey { EGain , DriftStabilization , CalibrationCount , FirstCalibrationKey = EGain , InvalidCalibrationKey = 0xff }

enum	AdjustableGainMode { eAdjustableADCGain0 , eAdjustableADCGain1 , eAdjustableADCGainCount , eAdjustableADCGainFirst = eAdjustableADCGain0 , eAdjustableGainAC4040HiGain = eAdjustableADCGain0 , eAdjustableGainAC4040LoGain = eAdjustableADCGain1 }

Public Member Functions
virtual const unsigned int	getSensorId () const =0
	Returns the sensor index of the specified sensor (within ICamera)

virtual ISensor::Info	getInfo () const =0
	Returns the buffered ISensor::Info structure.

virtual ISensor::Calibration	getCalibration () const =0
	Returns the buffered ISensor::Calibration structure.

virtual ISensor::Settings	getSettings () const =0
	Returns the buffered ISensor::Settings structure.

virtual int	getSetting (ISensor::Setting key) const =0
	Returns the requested setting value.

virtual TSubframe	getSubframe () const =0
	Returns the sensor's buffered TSubframe structure.

virtual IImagePtr	getImage () const =0
	Returns the ISensor's buffered image.

virtual IPromisePtr	queryInfo ()=0
	Query the camera's ISensor::Info structure.

virtual IPromisePtr	querySetting (ISensor::Setting setting)=0
	Query a specific value with an ISensor::Setting key from the camera.

virtual IPromisePtr	queryCalibration ()=0
	Query the camera's ISensor::Calibration structure.

virtual IPromisePtr	queryCalibration (ISensor::CalibrationKey key, int subkey)=0

virtual unsigned int	getCalibration (ISensor::CalibrationKey key, int subkey)=0

virtual IPromisePtr	querySubframe ()=0
	Query the camera's current subframe.

virtual IPromisePtr	setSetting (ISensor::Setting key, int value)=0
	Update an ISensor::Setting value in the camera by key.

virtual IPromisePtr	setSubframe (const TSubframe &value)=0
	Update the camera's active subframe.

virtual IPromisePtr	startExposure (const TExposureOptions &params)=0
	Start an exposure using this sensor.

virtual IPromisePtr	DebugStartExposure (unsigned int id, const char *exposureType, const TExposureOptions &params)=0
	Start an exposure using this sensor with aditional information. \id id of the exposure taken \exposureType exposure information ("Locate_Image", "Cal_Image", "Track_Image")

virtual IPromisePtr	startDownload ()=0
	Start downloading an image from the camera to DLAPI's internal buffers.

virtual IPromisePtr	abortExposure ()=0
	Abort any exposures/downloads either in progress, or waiting for user input.

virtual void	getReadoutModes (char *buf, size_t &lng) const =0
	Returns a list of human readable readout modes (the index of each entry corresponding to TExposureOptions::readoutMode)

virtual void	getAdjustableGains (AdjustableGainMode mode, int *pGainEntries, unsigned int &gainEntryCount) const =0
	getAdjustableGains()

virtual unsigned int	getAdjustableGainCount (AdjustableGainMode mode) const =0
	getAdjustableGainCount()

virtual unsigned int	getDefaultAdjustableGain (AdjustableGainMode mode) const =0
	getDefaultAdjustableGain()

Detailed Description

Sensor Interface Class.

An interface to a sensing chip connected to DLAPI cameras.

Member Enumeration Documentation

◆ AdjustableGainMode

enum dl::ISensor::AdjustableGainMode

Enumerator
eAdjustableADCGain0
eAdjustableADCGain1
eAdjustableADCGainCount
eAdjustableADCGainFirst
eAdjustableGainAC4040HiGain
eAdjustableGainAC4040LoGain

                                {
            eAdjustableADCGain0,
            eAdjustableADCGain1,
 
            eAdjustableADCGainCount,
            eAdjustableADCGainFirst = eAdjustableADCGain0,
 
            eAdjustableGainAC4040HiGain = eAdjustableADCGain0,
            eAdjustableGainAC4040LoGain = eAdjustableADCGain1
        };

◆ CalibrationKey

enum dl::ISensor::CalibrationKey

Enumerator
EGain
DriftStabilization
CalibrationCount
FirstCalibrationKey
InvalidCalibrationKey

        {
            EGain,
            DriftStabilization,
 
            CalibrationCount,           
            FirstCalibrationKey = EGain,
            InvalidCalibrationKey = 0xff
        };

◆ Model

enum dl::ISensor::Model

Enumerator
RESERVED1	Reserved for future use.
RESERVED2	Reserved for future use.
ICX694	Sony ICX694.
ICX814	Sony ICX814.
CCD4710	CCD 47-10.
CCD7700	CCD 77-00.
RESERVED3	Reserved for future use.
RESERVED4	Reserved for future use.
RESERVED5	Reserved for future use.
RESERVED6	Reserved for future use.
KAF3200	Kodak KAF 3200.
KAF8300	Kodak KAF 8300.
RESERVED7	Reserved for future use.
RESERVED8	Reserved for future use.
RESERVEDB1	Reserved for subvariant 1.
RESERVEDC1	Reserved for subvariant 3.
GSENSE4040	GPixel GSENSE4040.
GSENSE4040BSI	GPixel GSENSE4040 BSI.
GSENSE2020	GPixel GSENSE2020.
P1300	Python 1300.
IMX428	Sony IMX428.
IMX428_7	Sony IMX428 (STC-7 Variant)
IMX290	Sony IMX290.
IMX455	Sony IMX455.
InvalidSensorModel	Uninitialized sensor model value.

                   {
            RESERVED1 = 0x00,   
            RESERVED2 = 0x01,   
            ICX694 = 0x02,      
            ICX814 = 0x03,      
            CCD4710 = 0x04,     
            CCD7700 = 0x05,     
            RESERVED3 = 0x06,   
            RESERVED4 = 0x07,   
            RESERVED5 = 0x09,   
            RESERVED6 = 0x08,   
            KAF3200 = 0x0a,     
            KAF8300 = 0x0b,     
 
            RESERVED7 = 0x10,   
            RESERVED8 = 0x11,   
 
            RESERVEDB1 = 0x100, 
            
            RESERVEDC1 = 0x200, 
 
            GSENSE4040 = 0x300, 
            GSENSE4040BSI,      
 
            GSENSE2020 = 0x600, 
 
            P1300 = 0x400,      
 
            IMX428 = 0x500,     
            IMX428_7,           
 
            IMX290 = 0x800,     
 
            IMX455 = 0x900,     
 
            InvalidSensorModel = 0xFF 
        };

◆ Setting

enum dl::ISensor::Setting

Enumerator
UseOverscan	Use the sensor's overscan region in exposures. This is off by default. Enabling this changes ISensor::Info::pixelsX, and ISensor::Info::pixelsY. See also ISensor::Info, ISensor::setSubframe()
RBIPreflashDuration	The duration of an RBI flash before exposures, value is stored in milliseconds.
RBIPreflashFlushCount	The number of post-flash flushes performed before an exposure.
UseWindowHeater	Toggles a sensor's window heater to prevent fog/frost.
FanSpeed	Control the speed of the camera's fan.
ToggleIRLEDs	Control the RBI Preflash IR LEDs on the camera. Used for testing purposes. 0 means off, anything else is on.
UseOnChipBinning	Enable use of on-chip binning for main sensor.
UseExtTrigger	Enable use of external trigger. Set to non-zero to hold exposures in the "Wait for Trigger" state until Ext Trigger is received.
AutoFanMode	Enable use of self-regulating fan algorithm.
ShutterPolarity	Sets the polarity of a solenoid shutter. Typically only needs to be set once by the factory. Flipping this setting from zero to non-zero (or vice versa) when your shutter functions properly will invert its operation (i.e. requesting open will close it, and vice versa).
EnableStatusLED	When this setting is set to zero, it turns off the camera's status LED at all times. Otherwise, the status LED behaves according to the manual.
PartialExposureLength	This number is an integer (in increments of 1 second) controlling the length of sub-exposures when taking an internally stacked image (for cameras that support the feature).
UseFWAsShutter	Enable use of Filter Wheel as shutter. 0 is off, N on (where N is an integer value representing the slot to use as the shutter. 0xFF is "last slot")
AnalogGain0	Control analog gain for cameras supporting adjustable gain modes (e.g. High-Gain mode in an AC4040)
AnalogGain1	Control analog gain for cameras supporting adjustable gain modes (e.g. Low-Gain mode in an AC4040)
ContinuousExposure	Control continuous exposure mode. 0 = off, otherwise on. StartExposure begins repeated exposures as soon as an image is downloaded. AbortExposure exits out of the mode and requires re-enabling.
SettingCount	The maximum number of settings available to the user.
SoftwareBinMode	Selects the algorithm for software binning. See also: ISensor::SoftwareBinningMode.
SoftwareSettingCount
FirstSensorSetting	The first index of a sensor setting. (In this case, ISensor::UseOverscan)
FirstSoftwareSetting
InvalidSensorSetting	Uninitialized sensor setting, not for external use.

        {
            UseOverscan,            
            RBIPreflashDuration,    
            RBIPreflashFlushCount,  
            UseWindowHeater,        
            FanSpeed,               
            ToggleIRLEDs,           
            UseOnChipBinning,       
            UseExtTrigger,          
            AutoFanMode,            
            ShutterPolarity,        
            EnableStatusLED,        
            PartialExposureLength,  
            UseFWAsShutter,         
            AnalogGain0,            
            AnalogGain1,            
            ContinuousExposure,     
 
            SettingCount,           
            
            // Software-only settings (not reflected in hardware)
            SoftwareBinMode = 0x10000000,       
            
            SoftwareSettingCount,
 
            FirstSensorSetting = UseOverscan, 
            FirstSoftwareSetting = SoftwareBinMode,
            
            InvalidSensorSetting = 0xff 
        };

◆ SoftwareBinningMode

enum class dl::ISensor::SoftwareBinningMode : int

strong

Enumerator
SumAndClip
Average
Count
First
Default

        {
            SumAndClip,
            Average,
 
            Count,
            First = SumAndClip,
            Default = SumAndClip
        };

◆ Status

enum dl::ISensor::Status

Enumerator
Idle	Sensor is in idle state, and can accept ISensor::startExposure() commands.
Trigger	Sensor is waiting for trigger.
PreShutter	Sensor is preparing for shutter movement.
DoShutterOpen	Sensor is opening the shutter.
Starting	Sensor is starting the exposure.
Exposing	Sensor is exposing.
DoShutterClose	Sensor is closing the shutter post-exposure.
Reading	Sensor is reading data to buffer.
ReadyToDownload	Sensor is ready to transfer the image.
HomingShutter	Sensor is waiting for the shutter to return home. Sensor is busy, and is unable to start an exposure until the shutter is homed.
InvalidSensorState	The sensor status is uninitialized.

        {
 
            Idle,            
            Trigger,         
            PreShutter,      
            DoShutterOpen,   
            Starting,        
            Exposing,        
            DoShutterClose,  
            Reading,         
            ReadyToDownload, 
            HomingShutter,   
 
            InvalidSensorState = 0xFF, 
        };

Member Function Documentation

◆ abortExposure()

virtual IPromisePtr dl::ISensor::abortExposure ( )

pure virtual

Abort any exposures/downloads either in progress, or waiting for user input.

Returns: IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.

See also: IPromisePtr, ISensor::startExposure(), ISensor::startDownload

To abort an ongoing image, send this command to the camera. No image is buffered, or transferred from the camera. All image data acquired is discarded. It is considered good practice to call abortExposure() when you connect to a camera, to clear any pending exposures that may be in progress from improper shutdown procedures.

◆ DebugStartExposure()

virtual IPromisePtr dl::ISensor::DebugStartExposure	(	unsigned int	id,
		const char *	exposureType,
		const TExposureOptions &	params )

pure virtual

Start an exposure using this sensor with aditional information. \id id of the exposure taken \exposureType exposure information ("Locate_Image", "Cal_Image", "Track_Image")

Parameters

value the parameters of the exposure.

Returns: IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.

See also: startExposure

◆ getAdjustableGainCount()

virtual unsigned int dl::ISensor::getAdjustableGainCount ( AdjustableGainMode mode ) const

pure virtual

getAdjustableGainCount()

Parameters

mode	the index of the ADC converter you wish to fetch gain mode count for

Returns: the maximum number of allowed analog gain options returned by ISensor::getAdjustableGains()

See also: ISensor::setSetting(), ISensor::Setting::AnalogGain0, ISensor::Setting::AnalogGain1, ICamera::Capability::eSupportsAdjustableGain

◆ getAdjustableGains()

virtual void dl::ISensor::getAdjustableGains	(	AdjustableGainMode	mode,
		int *	pGainEntries,
		unsigned int &	gainEntryCount ) const

pure virtual

getAdjustableGains()

Parameters

mode	the index of the ADC converter you wish to fetch gain modes for. See full description for mappings.
pGainEntries	a pointer to an array of integers that will receive the complete list of gain entries.
gainEntryCount	[IN] the size of the array passed into pGainEntries. [OUT] Number of entries put into pGainEntries.

See also: ISensor::setSetting(), ISensor::Setting::AnalogGain0, ISensor::Setting::AnalogGain1, ICamera::Capability::eSupportsAdjustableGain, ISensor::getAdjustableGainCount()

Returns the allowed analog gain values user can pass into ISensor::Setting::AnalogGain0 and ISensor::Setting::AnalogGain1. These gains refer to adjustable analog converter gains. Measured EGain values are scaled in the camera to match the new analog gains. We recommend passing in a buffer with a minimum size equal to the value returned by ISensor::getAdjustableGainCount().

e.g.

++
          void getGains(ISensorPtr pSensor, ISensor::AdjustableGainMode mode, ...) 
          {
            auto optionCount = pSensor->getAdjustableGainCount(mode);
            auto pOptions = new unsigned int[optionCount];
            pSensor->getAdjustableGains(mode, pOptions, optionCount);
          
            // your logic here.
          
            delete[] pOptions; 
          }
          
          // Example call: getGains(pSensor, ISensor::eAdjustableGainAC4040HiGain, ...);

◆ getCalibration() [1/2]

virtual ISensor::Calibration dl::ISensor::getCalibration ( ) const

pure virtual

Returns the buffered ISensor::Calibration structure.

Returns: returns the buffered sensor calibration struct.

See also: ISensor::Calibration, ISensor::queryCalibration()

Returns the buffered sensor calibration structure, refreshed by ISensor::queryCalibration().

◆ getCalibration() [2/2]

virtual unsigned int dl::ISensor::getCalibration	(	ISensor::CalibrationKey	key,
		int	subkey )

pure virtual

◆ getDefaultAdjustableGain()

virtual unsigned int dl::ISensor::getDefaultAdjustableGain ( AdjustableGainMode mode ) const

pure virtual

getDefaultAdjustableGain()

Parameters

mode	the index of the ADC converter you wish to fetch the default gain value for

Returns: the default gain value of the specified Adjustable Gain mode

◆ getImage()

virtual IImagePtr dl::ISensor::getImage ( ) const

pure virtual

Returns the ISensor's buffered image.

Returns: returns the buffered image.

See also: IImagePtr, ISensor::startExposure()

Returns the buffered image structure, only updated when ISensor::startDownload() is complete. Image buffers stored here are destroyed when the next exposure is retrieved, so you should get in the habit of making a local copy as soon as you retrieve an image.

e.g.

++
           using namespace dl;
          
           struct image 
           {
             unsigned short * pBuffer;
             unsigned int     length;
             TImageMetadata  meta;
         
             image() : pBuffer(nullptr), length(0), meta() {}
             image(IImagePtr pImage) : pBuffer(_pBuffer), length(_length) 
             {
               // Make a deep copy of the incoming IImage immediately
               pBuffer = new short[pImage->getBufferLength()];
               memcpy(pBuffer, pImage->getImageBuffer(), length);
               meta = pImage->getMetadata();
             }
             ~image() { delete [] pBuffer; }
           }
         
           image * getImage(IPromisePtr pImagePromise, ISensorPtr pSensor) 
           {
             // pImagePromise would be a promise retrieved from calling ISensor::startDownload()
             // You would typically monitor this in a non-blocking fashion, using IPromise::GetStatus(), since image transfer can take several seconds.
             IPromise::Status result = pImagePromise->wait(); 
             if (result != IPromise::Complete) 
             { 
               // An error occurred.
               pImagePromise->release(); 
               return nullptr; 
             } 
         
             // The image was transferred successfully, retrieve it, make a local copy of it, and return it to the caller.
             pImagePromise->release();
             IImagePtr pImage = pSensor->getImage();
             return new image(pImage);
           }

In the example above, we've called ISensor::startDownload() externally, and passed the resulting pointer into getImage(), along with the sensor we're downloading the image from. Ownership of the generated image object is then handed off to the caller, and the API will clean up the internal image buffer when the next download is started.

◆ getInfo()

virtual ISensor::Info dl::ISensor::getInfo ( ) const

pure virtual

Returns the buffered ISensor::Info structure.

Returns: returns the buffered sensor info struct.

See also: ISensor::Info, ISensor::queryInfo()

Returns the buffered sensor info structure, refreshed by ISensor::queryInfo().

◆ getReadoutModes()

virtual void dl::ISensor::getReadoutModes	(	char *	buf,
		size_t &	lng ) const

pure virtual

Returns a list of human readable readout modes (the index of each entry corresponding to TExposureOptions::readoutMode)

Parameters

buf	pointer to an array of characters of length lng
lng	input the maximum length of the storage buffer, outputs the actual length of the storage buffer.

Returns a null-terminated, '\n' delimited list of readout modes. The index of this list is zero-based, when referencing readout modes in TExposureOptions.

++
          std::string getReadoutModes(ISensorPtr pSensor)
          {
            char buf[1028];
            size_t lng = 1028;
            pSensor->getReadoutModes(&(buf[0]), lng);
            return std::string(&(buf[0]), lng);
          }

e.g. The above function for an Aluma 3200 would return "Normal\nLow-Noise\0". If you wanted to use Low-Noise mode, you would set it up in TExposureOptions as follows:

++
          void startExposure(ISensorPtr pSensor)
          {
            TExposureOptions expOptions;
            expOptions.duration = 1.0;
            expOptions.binX = 1;
            expOptions.binY = 1;
            expOptions.readoutMode = 1; // because Low-Noise is second in the zero-indexed readout mode list.
            expOptions.isLightFrame = true;
            expOptions.useRBIPreflash = false;
            expOptions.useExtTrigger = false;
            handlePromise(pSensor->startExposure(expOptions));
          }

◆ getSensorId()

virtual const unsigned int dl::ISensor::getSensorId ( ) const

pure virtual

Returns the sensor index of the specified sensor (within ICamera)

Returns: returns the sensor's internal API index.

Returns the sensor's internal API index. i.e. 0 for main imaging sensors, and 1+ for any connected external sensors.

◆ getSetting()

virtual int dl::ISensor::getSetting ( ISensor::Setting key ) const

pure virtual

Returns the requested setting value.

Parameters

ISensor::Setting key the key value to retrieve

Returns: returns the setting value specified with key

See also: ISensor::Settings, ISensor::Setting, ISensor::querySettings()

Returns the buffered sensor setting specified by key, refreshed by ISensor::querySettings().

◆ getSettings()

virtual ISensor::Settings dl::ISensor::getSettings ( ) const

pure virtual

Returns the buffered ISensor::Settings structure.

Returns: returns the buffered sensor settings struct.

See also: ISensor::Settings, ISensor::querySettings()

Returns the buffered sensor settings structure, refreshed by ISensor::querySettings().

◆ getSubframe()

virtual TSubframe dl::ISensor::getSubframe ( ) const

pure virtual

Returns the sensor's buffered TSubframe structure.

Returns: returns the buffered sensor subframe struct.

See also: ISensor::Subframe, ISensor::querySubframe()

Returns the buffered sensor calibration structure, refreshed by ISensor::queryCalibration().

◆ queryCalibration() [1/2]

virtual IPromisePtr dl::ISensor::queryCalibration ( )

pure virtual

Query the camera's ISensor::Calibration structure.

Returns: queries the sensor's calibration structure.

See also: IPromisePtr, ISensor::queryCalibration()

[DEPRECATED]

Returns the buffered sensor image calibration structure, refreshed by ISensor::queryCalibration().

◆ queryCalibration() [2/2]

virtual IPromisePtr dl::ISensor::queryCalibration	(	ISensor::CalibrationKey	key,
		int	subkey )

pure virtual

◆ queryInfo()

virtual IPromisePtr dl::ISensor::queryInfo ( )

pure virtual

Query the camera's ISensor::Info structure.

Returns: queries the sensor's info structure.

See also: IPromisePtr, ISensor::getInfo()

Returns the buffered sensor inof structure, refreshed by ISensor::queryImage().

◆ querySetting()

virtual IPromisePtr dl::ISensor::querySetting ( ISensor::Setting setting )

pure virtual

Query a specific value with an ISensor::Setting key from the camera.

Parameters

setting a setting key to retrieve.

Returns: queries a sensor's setting structure.

See also: IPromisePtr, ISensor::Setting, ISensor::getSettings()

Returns the buffered sensor settings structure, refreshed by ISensor::querySettings().

◆ querySubframe()

virtual IPromisePtr dl::ISensor::querySubframe ( )

pure virtual

Query the camera's current subframe.

Returns: returns the buffered sensor subframe.

See also: IPromisePtr, ISensor::querySubframe()

Returns the buffered sensor subframe structure, refreshed by ISensor::querySubframe().

◆ setSetting()

virtual IPromisePtr dl::ISensor::setSetting	(	ISensor::Setting	key,
		int	value )

pure virtual

Update an ISensor::Setting value in the camera by key.

Parameters

key	the sensor setting to update.
value	the new value of the supplied key.

Returns: IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.

See also: ISensor::Settings, ISensor::Setting

Updates a sensor setting value in the camera, and returns a promise to the user to monitor the operation's execution. Every supported sensor setting is accompanied with an associated ISensor::Setting key, which you can then update via this function. The function accepts an int parameter which is stored in the camera's internal settings structure. Casting from the c-style ISensor::Settings structure to the function's int parameter is the responsibility of the user.

◆ setSubframe()

virtual IPromisePtr dl::ISensor::setSubframe ( const TSubframe & value )

pure virtual

Update the camera's active subframe.

Parameters

value the new value of the subframe to send to the camera.

Returns: IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.

Updates a sensor's subframe value in the camera, and returns a promise to the user to monitor the operation's execution. The subframe's offset is base zero, with an origin dependent on whether or not ISensor::Setting::useOverscan is set. If useOverscan is disabled, pixel [0,0] is situated at the origin of the sensor's active area. If useOverscan is enabled, pixel [0,0] is situated at the origin of the sensor's overscan region. Be sure to update the sensor subframe when toggling the useOverscan setting.

++
           void toggleOverscan(ISensorPtr pSensor, bool enable = true)
           {
             // We're going to ignore any promise errors here, for the sake of brevity.
             pSensor->SetSetting(ISensor::UseOverscan, enable ?  1 : 0)->release();
         
             // Be sure to update your sensor's info structure, to ensure you've got the right frame properties.
             // If you've got a locally buffered copy of the ISensor::Info struct, you should update that now as well.
             pSensor->queryInfo()->release();
         
             // If you're taking full frame images, you should take this opportunity to update your subframe using
             // the new frame dimensions as well.
           }

◆ startDownload()

virtual IPromisePtr dl::ISensor::startDownload ( )

pure virtual

Start downloading an image from the camera to DLAPI's internal buffers.

Returns: IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.

See also: IPromisePtr, ISensor::startExposure(), ISensor::Status, ISensor::getImage(), ISensor::abortExposure()

The start download command should only be called once a sensor reports the ISensor::Status::Reading, ISensor::Status::Idle, or ISensor::Status::ReadyToDownload state. Once ISensor::startDownload() is called, the camera enters an image transferring state, and will respond busy to any commands not related to transferring the image at hand. All the user has to do at this point is wait for the IPromisePtr to report IPromise::Complete, and call ISensor::getImage() to retrieve the transferred image from the buffer. The API handles all the rest.

Retrieving an image buffer looks something like this:

++
          using namespace dl;
          bool handlePromise(IPromisePtr pPromise)
          {
            if (!pPromise) return false;
            auto result = pPromise->wait();
            // n.b. Fetch error messages here, if applicable
            pPromise->release();
            return result == IPromise::Complete;
          }
        
          bool IsImageReady(ICameraPtr pCamera, ISensorPtr pSensor)
          {
            auto pPromise = pCamera->queryStatus();
            if (!handlePromise(pPromise)) return false;
            auto status = pCamera->getStatus();
            auto sensorId = pSensor->getSensorId();
            auto sensorStatus = ( sensorId != 0 ) ? status.extSensorState : status.mainSensorState;
            return sensorStatus == ISensor::ReadyToDownload;
          }
          
          bool startDownload(ICameraPtr pCamera, ISensorPtr pSensor, IPromisePtr& pImagePromise)
          {
            pImagePromise = nullptr; // Default to returning nothing, unless an image is ready.
            if (!IsImageReady(pCamera, pSensor)) return false;
            pImagePromise = pSensor->startDownload();
            return true;
          }

In the case of the code above, you would call startDownload() after a successful call to ISensor::startExposure. You would pass in a pointer to a camera and sensor via pCamera and pSensor respectively, and also pass in a reference to an IPromisePtr variable which will receive the promise returned by ISensor::startDownload(). When pImagePromise returns complete, the image will be stored in the local buffer, and is retrievable via ISensor::getImage().

◆ startExposure()

virtual IPromisePtr dl::ISensor::startExposure ( const TExposureOptions & params )

pure virtual

Start an exposure using this sensor.

Parameters

value the parameters of the exposure.

Returns: IPromisePtr pointer to promise for monitoring the status of the asynchronous operation.

See also: IPromisePtr, TExposureOptions, ISensor::startDownload(), ISensor::Status, ISensor::getImage(), ISensor::abortExposure()

The start exposure command takes its parameters from the TExposureOptions structure, and commands the camera to take an exposure. Users are then responsible for polling the status of the exposure using the ICamera::queryStatus() and ICamera::getStatus() commands. When the camera reports ISensor::Status::Reading, the user is responsible for calling ISensor::startDownload() to begin the image transfer from the camera.

Users are responsible for calling ISensor::setSubframe() before calling ISensor::startExposure() and retrieving frame size information for use in the exposure options.

e.g. Setting up a 1 second, full-frame, unbinned, light exposure

++
           using namespace dl;
           void startExposure(ISensorPtr pSensor)
           {
             // Grab sensor frame information
             ISensor::Info info = pSensor->getInfo();
             TSubframe subf;
             subf.top = 0;
             subf.left = 0;
             subf.width = info.pixelsX;
             subf.height = info.pixelsY;
             subf.binX = 1;
             subf.binY = 1;
         
             IPromisePtr pPromise = pSensor->setSubframe(subf);
             IPromise::Status result = pPromise->wait();
             if (result != IPromise::Success) throw std::logic_error("Failed to set subframe");
             pPromise->release();
         
             TExposureOptions options;
             options.duration = 1.0f;
             options.binX = 1;
             options.binY = 1;
             options.readoutMode = 0; // See: ISensor::getReadoutModes()
             options.isLightFrame = true;
             options.useRBIPreflash = false;
             options.useExtTrigger = false;
         
             pPromise = pSensor->startExposure(options);
             result = pPromise->wait();
             if (result != IPromise::Success) throw std::logic_error("Failed to start exposure");
             pPromise->release();
           }

You can then monitor the status of the exposure using ICamera::GetStatus(), and start downloading the image from the camera wiht ISensor::startDownload() when the respective sensor status is ISensor::ReadyToDownload.

The documentation for this class was generated from the following file:

C:/Users/arobi/Perforce/nightly/DL_Imaging/Aluma_Software/dlapi/src/dlapi.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ AdjustableGainMode

◆ CalibrationKey

◆ Model

◆ Setting

◆ SoftwareBinningMode

◆ Status

Member Function Documentation

◆ abortExposure()

◆ DebugStartExposure()

◆ getAdjustableGainCount()

◆ getAdjustableGains()

◆ getCalibration() [1/2]

◆ getCalibration() [2/2]

◆ getDefaultAdjustableGain()

◆ getImage()

◆ getInfo()

◆ getReadoutModes()

◆ getSensorId()

◆ getSetting()

◆ getSettings()

◆ getSubframe()

◆ queryCalibration() [1/2]

◆ queryCalibration() [2/2]

◆ queryInfo()

◆ querySetting()

◆ querySubframe()

◆ setSetting()

◆ setSubframe()

◆ startDownload()

◆ startExposure()