Base class for creating camera device adapters. More...

#include <DeviceBase.h>

Inheritance diagram for CCameraBase:

Public Member Functions
virtual const unsigned char *	GetImageBuffer ()=0
	Return pixel data.

virtual unsigned	GetImageWidth () const =0
	Return image buffer X-size in pixels.

virtual unsigned	GetImageHeight () const =0
	Return image buffer Y-size in pixels.

virtual unsigned	GetImageBytesPerPixel () const =0
	Return image buffer pixel depth in bytes.

virtual int	SnapImage ()=0
	Perform exposure and grab a single image.

virtual bool	Busy ()=0

virtual int	StartSequenceAcquisition (double interval)=0
	Start continuous sequence acquisition.

virtual int	StopSequenceAcquisition ()=0
	Stop and wait for the thread to finish.

double	GetPixelSizeUm () const final
	Unused and slated for removal. Implemented in DeviceBase.h.

virtual unsigned	GetNumberOfComponents () const
	Return the number of components in this image.

virtual int	GetComponentName (unsigned channel, char *name)
	Return the name for each component.

virtual unsigned	GetNumberOfChannels () const
	Return the number of channels.

virtual int	GetChannelName (unsigned, char *name)
	Return the channel name.

virtual const unsigned char *	GetImageBuffer (unsigned)
	Return the image buffer for a specific channel.

virtual const unsigned int *	GetImageBufferAsRGB32 ()
	Return pixel data with interleaved RGB pixels in 32 bpp format.

virtual void	GetTags (char *serializedMetadata)
	Fill serializedMetadata with the device's metadata tags.

virtual int	PrepareSequenceAcqusition ()
	Set up the camera so that Sequence acquisition can start without delay.

virtual int	StartSequenceAcquisition (long numImages, double interval_ms, bool stopOnOverflow)=0
	Start sequence acquisition.

virtual int	GetExposureSequenceMaxLength (long &) const

virtual int	StartExposureSequence ()

virtual int	StopExposureSequence ()

virtual int	ClearExposureSequence ()

virtual int	AddToExposureSequence (double)

virtual int	SendExposureSequence () const

virtual bool	IsCapturing ()=0
	Indicate whether sequence acquisition is currently running.

virtual void	AddTag (const char key, const char deviceLabel, const char *value)
	Add new tag or modify the value of an existing one.

virtual void	RemoveTag (const char *key)
	Remove an existing tag from the metadata associated with this device.

virtual bool	SupportsMultiROI ()

virtual bool	IsMultiROISet ()

virtual int	GetMultiROICount (unsigned &)

virtual int	SetMultiROI (const unsigned , const unsigned , const unsigned , const unsigned , unsigned)

virtual int	GetMultiROI (unsigned , unsigned , unsigned , unsigned , unsigned *)

Public Member Functions inherited from CDeviceBase< MM::Camera, U >
virtual void	SetModuleName (const char *name)
	Assign a name for the module (for use only by the calling code).

virtual void	GetModuleName (char *name) const
	Return the module name (for use only by the calling code).

virtual void	SetDescription (const char *descr)
	Assign description string for a device (for use only by the calling code).

virtual void	GetDescription (char *name) const
	Return device description (for use only by the calling code).

virtual void	SetLabel (const char *label)
	Set the device label (for use only by the calling code).

virtual void	GetLabel (char *name) const
	Return the device label (for use only by the calling code).

virtual double	GetDelayMs () const
	Return device delay used for synchronization by the calling code.

virtual void	SetDelayMs (double delay)
	Set the device delay used for synchronization by the calling code.

virtual void	SetCallback (MM::Core *cbk)
	Set the callback for accessing parent functionality (used only by the calling code).

virtual bool	UsesDelay ()
	Signal if the device responds to different delay settings.

virtual unsigned	GetNumberOfProperties () const
	Return the number of properties.

virtual int	GetProperty (const char name, char value) const
	Obtain the value of the property.

int	GetProperty (const char *name, double &val)
	Obtain the value of the property.

int	GetProperty (const char *name, long &val)
	Obtain the value of the property.

bool	IsPropertyEqualTo (const char name, const char val) const
	Check if the property value is equal to a specific string.

virtual int	GetPropertyReadOnly (const char *name, bool &readOnly) const
	Check whether the property is read-only.

virtual int	GetPropertyInitStatus (const char *name, bool &preInit) const
	Check whether the property is pre-init.

virtual int	HasPropertyLimits (const char *name, bool &hasLimits) const

virtual int	GetPropertyLowerLimit (const char *name, double &lowLimit) const
	Provide lower limit for a property that has property limits.

virtual int	GetPropertyUpperLimit (const char *name, double &hiLimit) const
	Provide upper limit for a property that has property limits.

virtual int	IsPropertySequenceable (const char *name, bool &sequenceable) const
	Check whether the property can be run in a sequence.

virtual int	GetPropertySequenceMaxLength (const char *name, long &nrEvents) const
	Provide the maximum number of events that can be executed by this sequenceable property.

virtual int	StartPropertySequence (const char *name)
	Start a (TTL-triggered) sequence for the given property.

virtual int	StopPropertySequence (const char *name)
	Stop a (TTL-triggered) sequence for the given property.

virtual int	ClearPropertySequence (const char *name)
	Clear a property sequence.

virtual int	AddToPropertySequence (const char name, const char value)
	Add to a property sequence.

virtual int	SendPropertySequence (const char *name)
	Send the property sequence to the device.

virtual bool	GetPropertyName (unsigned uIdx, char *name) const
	Obtain the property name given the index.

virtual int	GetPropertyType (const char *name, MM::PropertyType &pt) const
	Obtain property type (string, float, or integer).

virtual int	SetProperty (const char name, const char value)
	Set the property value.

virtual bool	HasProperty (const char *name) const
	Check if device supports a given property.

virtual unsigned	GetNumberOfPropertyValues (const char *propertyName) const
	Return the number of allowed property values.

virtual bool	GetPropertyValueAt (const char propertyName, unsigned index, char value) const
	Return the allowed value of the property, given its index.

int	CreateProperty (const char name, const char value, MM::PropertyType eType, bool readOnly, MM::ActionFunctor *pAct=0, bool isPreInitProperty=false)
	Create a new property for the device.

int	CreatePropertyWithHandler (const char name, const char value, MM::PropertyType eType, bool readOnly, int(U::memberFunction)(MM::PropertyBase pProp, MM::ActionType eAct), bool isPreInitProperty=false)
	Create a new property for the device.

int	CreateIntegerProperty (const char name, long value, bool readOnly, MM::ActionFunctor pAct=0, bool isPreInitProperty=false)
	Create an integer-valued property for the device.

int	CreateFloatProperty (const char name, double value, bool readOnly, MM::ActionFunctor pAct=0, bool isPreInitProperty=false)
	Create a float-valued property for the device.

int	CreateStringProperty (const char name, const char value, bool readOnly, MM::ActionFunctor *pAct=0, bool isPreInitProperty=false)
	Create a string-valued property for the device.

int	SetPropertyLimits (const char *name, double low, double high)
	Define limits for properties with a continuous range of values.

int	SetAllowedValues (const char *name, std::vector< std::string > &values)
	Set an entire array of allowed values.

int	ClearAllowedValues (const char *name)
	Clear allowed values, and make any value valid.

int	AddAllowedValue (const char name, const char value)
	Add a single allowed value.

int	AddAllowedValue (const char name, const char value, long data)
	Add a single allowed value, plus additional data.

int	GetPropertyData (const char name, const char value, long &data)
	Obtain data field associated with the allowed property value.

int	GetCurrentPropertyData (const char *name, long &data)
	Obtain data field associated with the currently applied property value.

int	UpdateStatus ()
	Refresh the entire state of the device and synchronize property values with the actual state of the hardware.

int	UpdateProperty (const char *name)
	Update property value from the hardware.

int	ApplyProperty (const char *name)
	Apply the current property value to the hardware.

virtual bool	GetErrorText (int errorCode, char *text) const
	Obtain the error text associated with the error code.

virtual bool	SupportsDeviceDetection (void)

virtual MM::DeviceDetectionStatus	DetectDevice (void)

virtual void	SetParentID (const char *parentId)

virtual void	GetParentID (char *parentID) const

Public Member Functions inherited from MM::Camera
virtual DeviceType	GetType () const

virtual long	GetImageBufferSize () const =0
	Return the size in bytes of the image buffer.

virtual unsigned	GetBitDepth () const =0
	Return the bit depth (dynamic range) of the pixel.

virtual int	GetBinning () const =0
	Return the current binning factor.

virtual int	SetBinning (int binSize)=0
	Set binning factor.

virtual void	SetExposure (double exp_ms)=0
	Set exposure in milliseconds.

virtual double	GetExposure () const =0
	Return the current exposure setting in milliseconds.

virtual int	SetROI (unsigned x, unsigned y, unsigned xSize, unsigned ySize)=0
	Set the camera Region Of Interest.

virtual int	GetROI (unsigned &x, unsigned &y, unsigned &xSize, unsigned &ySize)=0
	Return the actual dimensions of the current ROI.

virtual int	ClearROI ()=0
	Reset the Region of Interest to full frame.

virtual int	IsExposureSequenceable (bool &isSequenceable) const =0
	Return whether a camera's exposure time can be sequenced.

Public Member Functions inherited from MM::Device
virtual int	Initialize ()=0

virtual int	Shutdown ()=0
	Shut down (unload) the device.

virtual void	GetName (char *name) const =0

Protected Member Functions
virtual std::vector< std::string >	GetTagKeys ()

virtual std::string	GetTagValue (const char *key)

Protected Member Functions inherited from CDeviceBase< MM::Camera, U >
void	SetErrorText (int errorCode, const char *text)
	Define the error text associated with the code.

const char *	GetMorePropertyErrorInfo (void) const

void	SetMorePropertyErrorInfo (const char *ptext) const

int	LogMessage (const char *msg, bool debugOnly=false) const
	Output the specified text message to the log stream.

int	LogMessage (const std::string &msg, bool debugOnly=false) const
	Output the specified text message to the log stream.

int	LogMessageCode (const int errorCode, bool debugOnly=false) const
	Output the text message of specified code to the log stream.

int	LogTimeDiff (MM::MMTime start, MM::MMTime end, const std::string &message, bool debugOnly=false) const
	Output time difference between two time stamps.

int	LogTimeDiff (MM::MMTime start, MM::MMTime end, bool debugOnly=false) const
	Output time difference between two time stamps.

void	InitializeDefaultErrorMessages ()
	Set up the standard set of error codes and error messages.

MM::Device *	GetDevice (const char *deviceLabel) const
	Get the handle (pointer) to the specified device label.

void	GetLoadedDeviceOfType (MM::DeviceType devType, char *deviceName, const unsigned int deviceIterator)
	Provide access to the names of devices of a given type.

int	WriteToComPort (const char portLabel, const unsigned char buf, unsigned bufLength)
	Send an array of bytes to the COM port.

int	SendSerialCommand (const char portName, const char command, const char *term)
	Send an ASCII string with the specified terminating characters to the serial port.

int	GetSerialAnswer (const char portName, const char term, std::string &ans)
	Get the received string from the serial port, waiting for the terminating character sequence.

int	ReadFromComPort (const char portLabel, unsigned char buf, unsigned bufLength, unsigned long &read)
	Read the current contents of Rx serial buffer.

int	PurgeComPort (const char *portLabel)
	Clear the serial port buffers.

MM::PortType	GetSerialPortType (const char *portLabel)
	TODO-BRIEF.

int	OnPropertiesChanged ()
	Signal that something changed in the property structure.

int	OnPropertyChanged (const char propName, const char propValue)
	Signal to the core that a property value has changed.

int	OnStagePositionChanged (double pos)
	Signal that the stage has arrived at a new position.

int	OnXYStagePositionChanged (double xPos, double yPos)
	Signal that the XY stage has arrived at a new position.

int	OnExposureChanged (double exposure)
	Signal that the exposure has changed.

int	OnSLMExposureChanged (double exposure)
	Signal that the SLM exposure has changed.

int	OnMagnifierChanged ()
	Signal that the magnifier has changed.

unsigned long	GetClockTicksUs ()
	Get the system ticks in microseconds.

MM::MMTime	GetCurrentMMTime ()
	Get current time.

bool	IsCallbackRegistered () const
	Check if we have callback mechanism set up.

MM::Core *	GetCoreCallback () const
	Get the callback object.

void	EnableDelay (bool state=true)
	Enable response to delay settings.

void	CreateHubIDProperty ()
	Create read-only property displaying parentID (hub label).

MM::Hub *	GetParentHub () const
	Return the parent Hub device pointer, or null if there isn't any.

T_HUB *	AssignToHub ()
	Return the parent Hub device pointer, or null if there isn't any.

Additional Inherited Members
Public Types inherited from CDeviceBase< MM::Camera, U >
typedef MM::Action< U >	CPropertyAction

typedef MM::ActionEx< U >	CPropertyActionEx

Static Public Attributes inherited from MM::Camera
static const DeviceType	Type = CameraDevice

Detailed Description

template<class U>
class CCameraBase

Base class for creating camera device adapters.

This class has a functional constructor - must be invoked from the derived class.

Member Function Documentation

◆ AddTag()

template<class U >

virtual void CCameraBase< U >::AddTag	(	const char *	key,
		const char *	deviceLabel,
		const char *	value
	)

inlinevirtual

Add new tag or modify the value of an existing one.

These will automatically be added to images inserted into the circular buffer. Use this mechanism for tags that do not change often. For metadata that change often, create an instance of metadata yourself and add to one of the versions of the InsertImage function.

Implements MM::Camera.

◆ AddToExposureSequence()

template<class U >

virtual int CCameraBase::AddToExposureSequence ( double )

inlinevirtual

Implements MM::Camera.

◆ Busy()

template<class U >

virtual bool CCameraBase::Busy ( )

pure virtual

Implements MM::Device.

◆ ClearExposureSequence()

template<class U >

virtual int CCameraBase::ClearExposureSequence ( )

inlinevirtual

Implements MM::Camera.

◆ GetChannelName()

template<class U >

virtual int CCameraBase< U >::GetChannelName	(	unsigned	,
		char *	name
	)

inlinevirtual

Return the channel name.

Multi-channel cameras should provide names for their channels. Single channel cameras do not need to override this default implementation.

Implements MM::Camera.

References CDeviceUtils::CopyLimitedString().

◆ GetComponentName()

template<class U >

virtual int CCameraBase< U >::GetComponentName	(	unsigned	component,
		char *	name
	)

inlinevirtual

Return the name for each component.

Implements MM::Camera.

References CDeviceUtils::CopyLimitedString().

◆ GetExposureSequenceMaxLength()

template<class U >

virtual int CCameraBase::GetExposureSequenceMaxLength ( long & ) const

inlinevirtual

Implements MM::Camera.

◆ GetImageBuffer() [1/2]

template<class U >

virtual const unsigned char * CCameraBase::GetImageBuffer ( )

pure virtual

Return pixel data.

Required by the MM::Camera API. GetImageBuffer will be called shortly after SnapImage returns. Use it to wait for camera read-out and transfer of data into memory Return a pointer to a buffer containing the image data The calling program will assume the size of the buffer based on the values obtained from GetImageBufferSize(), which in turn should be consistent with values returned by GetImageWidth(), GetImageHeight(), GetImageBytesPerPixel(), and getNumberOfComponents(). The calling program also assumes that camera never changes the size of the pixel buffer on its own. In other words, the buffer can change only if appropriate properties are set (such as binning, pixel type, etc.) Multi-Channel cameras should return the content of the first channel in this call.

Supported data types are byte (8 bits per pixel, 1 component), short (16 bits per pixel, 1 component), float (32 bits per pixel, 1 component, not supported by the UI yet), RGB_32 (8 bits per component, 4 components), RGB_64 (16 bits per component, 4 components, not supported by UI yet). RGB buffers are expected to be in big endian ARGB format (ARGB8888), which means that on little endian format (currently most/all? code is compiled for little endian architecture), the format is BGRA888 (see: https://en.wikipedia.org/wiki/RGBA_color_model).

Implements MM::Camera.

Referenced by CCameraBase::GetImageBuffer().

◆ GetImageBuffer() [2/2]

template<class U >

virtual const unsigned char * CCameraBase::GetImageBuffer ( unsigned )

inlinevirtual

Return the image buffer for a specific channel.

Version of GetImageBuffer for multi-channel cameras. Single channel (standard) cameras do not need to override this.

Implements MM::Camera.

References CCameraBase::GetImageBuffer(), and CCameraBase::GetNumberOfChannels().

◆ GetImageBufferAsRGB32()

template<class U >

virtual const unsigned int * CCameraBase::GetImageBufferAsRGB32 ( )

inlinevirtual

Return pixel data with interleaved RGB pixels in 32 bpp format.

Implements MM::Camera.

◆ GetImageBytesPerPixel()

template<class U >

virtual unsigned CCameraBase::GetImageBytesPerPixel ( ) const

pure virtual

Return image buffer pixel depth in bytes.

Required by the MM::Camera API.

Implements MM::Camera.

◆ GetImageHeight()

template<class U >

virtual unsigned CCameraBase::GetImageHeight ( ) const

pure virtual

Return image buffer Y-size in pixels.

Required by the MM::Camera API.

Implements MM::Camera.

◆ GetImageWidth()

template<class U >

virtual unsigned CCameraBase::GetImageWidth ( ) const

pure virtual

Return image buffer X-size in pixels.

Required by the MM::Camera API.

Implements MM::Camera.

◆ GetMultiROI()

template<class U >

virtual int CCameraBase< U >::GetMultiROI	(	unsigned *	,
		unsigned *	,
		unsigned *	,
		unsigned *	,
		unsigned *
	)

inlinevirtual

Implements MM::Camera.

◆ GetMultiROICount()

template<class U >

virtual int CCameraBase::GetMultiROICount ( unsigned & )

inlinevirtual

Implements MM::Camera.

◆ GetNumberOfChannels()

template<class U >

virtual unsigned CCameraBase::GetNumberOfChannels ( ) const

inlinevirtual

Return the number of channels.

Multi-channel cameras use this function to indicate how many channels they provide. Single channel cameras do not need to override this.

Implements MM::Camera.

Referenced by CCameraBase::GetImageBuffer().

◆ GetNumberOfComponents()

template<class U >

virtual unsigned CCameraBase::GetNumberOfComponents ( ) const

inlinevirtual

Return the number of components in this image.

This is '1' for grayscale cameras, and '4' for RGB cameras.

Implements MM::Camera.

◆ GetPixelSizeUm()

template<class U >

double CCameraBase::GetPixelSizeUm ( ) const

inlinefinalvirtual

Unused and slated for removal. Implemented in DeviceBase.h.

Implements MM::Camera.

◆ GetTags()

template<class U >

virtual void CCameraBase::GetTags ( char * serializedMetadata )

inlinevirtual

Fill serializedMetadata with the device's metadata tags.

Implements MM::Camera.

◆ IsCapturing()

template<class U >

virtual bool CCameraBase::IsCapturing ( )

pure virtual

Indicate whether sequence acquisition is currently running.

Returns true when sequence acquisition is active, false otherwise.

Implements MM::Camera.

Implemented in CLegacyCameraBase.

◆ IsMultiROISet()

template<class U >

virtual bool CCameraBase::IsMultiROISet ( )

inlinevirtual

Implements MM::Camera.

◆ PrepareSequenceAcqusition()

template<class U >

virtual int CCameraBase::PrepareSequenceAcqusition ( )

inlinevirtual

Set up the camera so that Sequence acquisition can start without delay.

Implements MM::Camera.

◆ RemoveTag()

template<class U >

virtual void CCameraBase::RemoveTag ( const char * key )

inlinevirtual

Remove an existing tag from the metadata associated with this device.

These tags will automatically be add to the metadata of an image inserted into the circular buffer.

Implements MM::Camera.

◆ SendExposureSequence()

template<class U >

virtual int CCameraBase::SendExposureSequence ( ) const

inlinevirtual

Implements MM::Camera.

◆ SetMultiROI()

template<class U >

virtual int CCameraBase< U >::SetMultiROI	(	const unsigned *	,
		const unsigned *	,
		const unsigned *	,
		const unsigned *	,
		unsigned
	)

inlinevirtual

Implements MM::Camera.

◆ SnapImage()

template<class U >

virtual int CCameraBase::SnapImage ( )

pure virtual

Perform exposure and grab a single image.

Required by the MM::Camera API.

SnapImage should start the image exposure in the camera and block until the exposure is finished. It should not wait for read-out and transfer of data. Return DEVICE_OK on success, error code otherwise.

Implements MM::Camera.

◆ StartExposureSequence()

template<class U >

virtual int CCameraBase::StartExposureSequence ( )

inlinevirtual

Implements MM::Camera.

◆ StartSequenceAcquisition() [1/2]

template<class U >

virtual int CCameraBase::StartSequenceAcquisition ( double interval )

pure virtual

Start continuous sequence acquisition.

Default to sequence acquisition with a high number of images.

Implements MM::Camera.

Implemented in CLegacyCameraBase.

◆ StartSequenceAcquisition() [2/2]

template<class U >

virtual int CCameraBase< U >::StartSequenceAcquisition	(	long	numImages,
		double	interval_ms,
		bool	stopOnOverflow
	)

pure virtual

Start sequence acquisition.

Implements MM::Camera.

Implemented in CLegacyCameraBase.

◆ StopExposureSequence()

template<class U >

virtual int CCameraBase::StopExposureSequence ( )

inlinevirtual

Implements MM::Camera.

◆ StopSequenceAcquisition()

template<class U >

virtual int CCameraBase::StopSequenceAcquisition ( )

pure virtual

Stop and wait for the thread to finish.

Implements MM::Camera.

Implemented in CLegacyCameraBase.

◆ SupportsMultiROI()

template<class U >

virtual bool CCameraBase::SupportsMultiROI ( )

inlinevirtual

Implements MM::Camera.

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

DeviceBase.h

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ AddTag()

◆ AddToExposureSequence()

◆ Busy()

◆ ClearExposureSequence()

◆ GetChannelName()

◆ GetComponentName()

◆ GetExposureSequenceMaxLength()

◆ GetImageBuffer() [1/2]

◆ GetImageBuffer() [2/2]

◆ GetImageBufferAsRGB32()

◆ GetImageBytesPerPixel()

◆ GetImageHeight()

◆ GetImageWidth()

◆ GetMultiROI()

◆ GetMultiROICount()

◆ GetNumberOfChannels()

◆ GetNumberOfComponents()

◆ GetPixelSizeUm()

◆ GetTags()

◆ IsCapturing()

◆ IsMultiROISet()

◆ PrepareSequenceAcqusition()

◆ RemoveTag()

◆ SendExposureSequence()

◆ SetMultiROI()

◆ SnapImage()

◆ StartExposureSequence()

◆ StartSequenceAcquisition() [1/2]

◆ StartSequenceAcquisition() [2/2]

◆ StopExposureSequence()

◆ StopSequenceAcquisition()

◆ SupportsMultiROI()