CMMCore Class Reference

#include <MMCore.h>

List of all members.

Public Member Functions
	CMMCore ()
	~CMMCore ()
Initialization and set-up
Loading of drivers, initialization and setting-up the environment.
void	loadDevice (const char *label, const char *library, const char *name) throw (CMMError)
void	unloadAllDevices () throw (CMMError)
void	initializeAllDevices () throw (CMMError)
void	initializeDevice (const char *label) throw (CMMError)
void	reset () throw (CMMError)
void	clearLog ()
void	initializeLogging ()
void	shutdownLogging ()
void	enableDebugLog (bool enable)
void	enableStderrLog (bool enable)
std::string	getUserId () const
std::string	getHostName () const
void	logMessage (const char *msg)
std::string	getVersionInfo () const
std::string	getAPIVersionInfo () const
Configuration	getSystemState () const
void	setSystemState (const Configuration &conf)
Configuration	getConfigState (const char *group, const char *config) const throw (CMMError)
Configuration	getConfigGroupState (const char *group) const throw (CMMError)
void	saveSystemState (const char *fileName) throw (CMMError)
void	loadSystemState (const char *fileName) throw (CMMError)
void	saveSystemConfiguration (const char *fileName) throw (CMMError)
void	loadSystemConfiguration (const char *fileName) throw (CMMError)
Device discovery and configuration interface.
std::vector< std::string >	getAvailableDevices (const char *library) throw (CMMError)
std::vector< std::string >	getAvailableDeviceDescriptions (const char *library) throw (CMMError)
std::vector< int >	getAvailableDeviceTypes (const char *library) throw (CMMError)
Generic device interface
API guaranteed to work for all devices.
std::vector< std::string >	getDeviceLibraries (const char *path)
std::vector< std::string >	getLoadedDevices () const
std::vector< std::string >	getLoadedDevicesOfType (MM::DeviceType devType) throw (CMMError)
std::vector< std::string >	getDevicePropertyNames (const char *label) const throw (CMMError)
std::string	getProperty (const char *label, const char *propName) const throw (CMMError)
void	setProperty (const char *label, const char *propName, const char *propValue) throw (CMMError)
bool	hasProperty (const char *label, const char *propName) const throw (CMMError)
std::vector< std::string >	getAllowedPropertyValues (const char *label, const char *propName) const throw (CMMError)
bool	isPropertyReadOnly (const char *label, const char *propName) const throw (CMMError)
bool	isPropertyPreInit (const char *label, const char *propName) const throw (CMMError)
MM::DeviceType	getDeviceType (const char *label) throw (CMMError)
bool	deviceBusy (const char *deviceName) throw (CMMError)
void	waitForDevice (const char *deviceName) throw (CMMError)
void	waitForConfig (const char *group, const char *configName) throw (CMMError)
bool	systemBusy () throw (CMMError)
void	waitForSystem () throw (CMMError)
void	waitForImageSynchro () throw (CMMError)
bool	deviceTypeBusy (MM::DeviceType devType) throw (CMMError)
void	waitForDeviceType (MM::DeviceType devType) throw (CMMError)
void	sleep (double intervalMs) const
double	getDeviceDelayMs (const char *label) const throw (CMMError)
void	setDeviceDelayMs (const char *label, double delayMs) throw (CMMError)
void	setTimeoutMs (long timeoutMs)
long	getTimeoutMs ()
bool	usesDeviceDelay (const char *label) const throw (CMMError)
std::string	getCoreErrorText (int code) const
System role identification for devices.
std::string	getCameraDevice ()
std::string	getShutterDevice ()
std::string	getFocusDevice ()
std::string	getXYStageDevice ()
std::string	getAutoFocusDevice ()
std::string	getImageProcessorDevice ()
void	setCameraDevice (const char *cameraLabel) throw (CMMError)
void	setShutterDevice (const char *shutterLabel) throw (CMMError)
void	setFocusDevice (const char *focusLabel) throw (CMMError)
void	setXYStageDevice (const char *xyStageLabel) throw (CMMError)
void	setAutoFocusDevice (const char *focusLabel) throw (CMMError)
void	setImageProcessorDevice (const char *procLabel) throw (CMMError)
Multiple property settings
A single configuration applies to multiple devices at the same time.
void	defineConfig (const char *groupName, const char *configName, const char *deviceName, const char *propName, const char *value)
void	defineConfigGroup (const char *groupName) throw (CMMError)
void	deleteConfigGroup (const char *groupName) throw (CMMError)
bool	isGroupDefined (const char *groupName)
bool	isConfigDefined (const char *groupName, const char *configName)
void	setConfig (const char *groupName, const char *configName) throw (CMMError)
void	deleteConfig (const char *groupName, const char *configName) throw (CMMError)
std::vector< std::string >	getAvailableConfigGroups () const
std::vector< std::string >	getAvailableConfigs (const char *configGroup) const
std::string	getCurrentConfig (const char *groupName) const
Configuration	getConfigData (const char *configGroup, const char *configName) const throw (CMMError)
double	getPixelSizeUm () const
void	setPixelSizeUm (const char *resoultionID, double pixSize) throw (CMMError)
void	definePixelSizeConfig (const char *resolutionID, const char *deviceName, const char *propName, const char *value)
std::vector< std::string >	getAvailablePixelSizeConfigs () const
Configuration	getPixelSizeConfigData (const char *configName) const throw (CMMError)
Imaging support
Imaging related API.
void	setROI (unsigned x, unsigned y, unsigned xSize, unsigned ySize) throw (CMMError)
void	getROI (unsigned &x, unsigned &y, unsigned &xSize, unsigned &ySize) const throw (CMMError)
void	clearROI () throw (CMMError)
void	setExposure (double exp) throw (CMMError)
double	getExposure () const throw (CMMError)
void *	getImage () const throw (CMMError)
void	snapImage () throw (CMMError)
unsigned	getImageWidth () const
unsigned	getImageHeight () const
unsigned	getBytesPerPixel () const
unsigned	getImageBitDepth () const
long	getImageBufferSize () const
void	assignImageSynchro (const char *deviceLabel) throw (CMMError)
void	removeImageSynchro (const char *label) throw (CMMError)
void	removeImageSynchroAll ()
void	setAutoShutter (bool state)
bool	getAutoShutter ()
void	setShutterOpen (bool state) throw (CMMError)
bool	getShutterOpen () throw (CMMError)
void	startSequenceAcquisition (long numImages, double intervalMs) throw (CMMError)
void	stopSequenceAcquisition () throw (CMMError)
void *	getLastImage () const throw (CMMError)
void *	popNextImage () throw (CMMError)
long	getRemainingImageCount ()
long	getBufferTotalCapacity ()
long	getBufferFreeCapacity ()
double	getBufferIntervalMs () const
bool	isBufferOverflowed () const
void	setCircularBufferMemoryFootprint (unsigned sizeMB) throw (CMMError)
Auto-focusing
API for controlling auto-focusing devices or software modules.
double	getFocusScore ()
void	enableContinuousFocus (bool enable) throw (CMMError)
bool	isContinuousFocusEnabled () throw (CMMError)
void	fullFocus () throw (CMMError)
void	incrementalFocus () throw (CMMError)
State device support
API for controlling state devices (filters, turrets, etc.)
void	setState (const char *deviceLabel, long state) throw (CMMError)
long	getState (const char *deviceLabel) const throw (CMMError)
long	getNumberOfStates (const char *deviceLabel)
void	setStateLabel (const char *deviceLabel, const char *stateLabel) throw (CMMError)
std::string	getStateLabel (const char *deviceLabel) const throw (CMMError)
void	defineStateLabel (const char *deviceLabel, long state, const char *stateLabel) throw (CMMError)
std::vector< std::string >	getStateLabels (const char *deviceLabel) const throw (CMMError)
long	getStateFromLabel (const char *deviceLabel, const char *stateLabel) const throw (CMMError)
PropertyBlock	getStateLabelData (const char *deviceLabel, const char *stateLabel) const
PropertyBlock	getData (const char *deviceLabel) const
Property blocks
API for defining interchangeable equipment attributes
void	definePropertyBlock (const char *blockName, const char *propertyName, const char *propertyValue)
std::vector< std::string >	getAvailablePropertyBlocks () const
PropertyBlock	getPropertyBlockData (const char *blockName) const
Stage control
API for controlling X, Y and Z stages
void	setPosition (const char *deviceName, double position) throw (CMMError)
double	getPosition (const char *deviceName) const throw (CMMError)
void	setXYPosition (const char *deviceName, double x, double y) throw (CMMError)
void	getXYPosition (const char *deviceName, double &x, double &y) throw (CMMError)
double	getXPosition (const char *deviceName) throw (CMMError)
double	getYPosition (const char *deviceName) throw (CMMError)
void	stop (const char *deviceName) throw (CMMError)
void	home (const char *deviceName) throw (CMMError)
void	setOriginXY (const char *deviceName) throw (CMMError)
Serial port control
API for serial ports
void	setSerialPortCommand (const char *name, const char *command, const char *term) throw (CMMError)
std::string	getSerialPortAnswer (const char *name, const char *term) throw (CMMError)
void	writeToSerialPort (const char *name, const std::vector< char > &data) throw (CMMError)
std::vector< char >	readFromSerialPort (const char *name) throw (CMMError)

---

Detailed Description

The interface to the core image acquisition services. This class is intended as the top-most level interface to the core services. Its public methods define the programmatic API, typically wrapped into the high-level language wrapper (Python, Java, etc.). Public methods are designed to conform to default processing conventions for the automatic wrapper generator SWIG (http://www.swig.org).

---

Constructor & Destructor Documentation

CMMCore::CMMCore (   )

Constructor. Initializes buffers and error message text. It does not load any hardware devices at this point.

CMMCore::~CMMCore (   )

Destructor. Cleans-up and unloads all devices.

---

Member Function Documentation

void CMMCore::assignImageSynchro (  const char *  label  )  throw (CMMError)

Add device to the image-synchro list. Image acquistion waits for all devices in this list. Parameters: const  char* label - device label

void CMMCore::clearLog (   )

Delete an exisiting log file and start a new one.

void CMMCore::clearROI (   )  throw (CMMError)

Resets the current ROI to the full frame.

void CMMCore::defineConfig (  const char *  groupName, const char *  configName, const char *  deviceLabel, const char *  propName, const char *  value )

Defines a single configuration entry (setting). If the configuration group/name was not previously defined a new configuration will be automatically created. If the name was previously defined the new setting will be added to its list of property settings. The new setting will override previously defined ones if it refers to the same property name. Parameters: groupName  group name configName  configuration name deviceLabel  device label propName  property name value  property value

void CMMCore::defineConfigGroup (  const char *  groupName  )  throw (CMMError)

Creates an empty configuration group.

void CMMCore::definePixelSizeConfig (  const char *  resolutionID, const char *  deviceLabel, const char *  propName, const char *  value )

Defines a single pixel size entry (setting). The system will treat pixel size configurations very similar to configuration presets, i.e. it will try to detect if any of the pixel size presets matches the current state of the system. If the pixel size was previously defined the new setting will be added to its list of property settings. The new setting will override previously defined ones if it refers to the same property name. Parameters: resolutionID  identifier for one unique property setting deviceLabel  device label propName  property name value  property value

void CMMCore::definePropertyBlock (  const char *  blockName, const char *  propertyName, const char *  propertyValue )

Defines a reference for the collection of property-value pairs. This construct is useful for defining interchangeable equipment features, such as objective magnifications, filter wavelengths, etc.

void CMMCore::defineStateLabel (  const char *  deviceLabel, long  state, const char *  label )  throw (CMMError)

Defines a label for the specific state/ Parameters: const  char* deviceLabel device label long  state state const  char* label assingned label

void CMMCore::deleteConfig (  const char *  groupName, const char *  configName )  throw (CMMError)

Deletes a configuration from a group. The command will fail if the configuration was not previously defined.

void CMMCore::deleteConfigGroup (  const char *  groupName  )  throw (CMMError)

Deletes an entire configuration group.

bool CMMCore::deviceBusy (  const char *  label  )  throw (CMMError)

Checks the busy status of the specific device. Parameters: label  - device label

bool CMMCore::deviceTypeBusy (  MM::DeviceType  devType  )  throw (CMMError)

Checks the busy status for all devices of the specific type. The system will report busy if any of the devices of the spefified type are busy. Returns: bool - true on busy Parameters: MM::DeviceType  devType

void CMMCore::enableDebugLog (  bool  enable  )

Enable or disable logging of debug messages. Parameters: enable  - if set to true debug messages will be recorded in the log file

void CMMCore::enableStderrLog (  bool  enable  )

Enables or disables log message display on the standard console. Parameters: enable  - if set to true, log file messages will be echoed on the stderr.

std::vector< std::string > CMMCore::getAllowedPropertyValues (  const char *  label, const char *  propName )  const throw (CMMError)

Returns all valid values for the specified property. If the array is empty it means that there are no restrictions for values. However, even if all values are allowed it is not guaranteed that all of them will be acually accepted by the device at run time. Returns: vector<string> the array of values Parameters: const  char* label device label const  std::string& propName property name

string CMMCore::getAPIVersionInfo (   )  const

Displays the module and device interface versions.

string CMMCore::getAutoFocusDevice (   )

Returns the label of the currently selected auto-focus device.

bool CMMCore::getAutoShutter (   )

Returns the current setting of the auto-shutter option.

vector< string > CMMCore::getAvailableConfigs (  const char *  group  )  const

Returns all defined configuration names in a given group Returns: std::vector<string> an array of configuration names

vector< string > CMMCore::getAvailableDeviceDescriptions (  const char *  library  )  throw (CMMError)

Get descriptions for available devices from the specified library.

vector< string > CMMCore::getAvailableDevices (  const char *  library  )  throw (CMMError)

Get available devices from the specified library.

vector< int > CMMCore::getAvailableDeviceTypes (  const char *  library  )  throw (CMMError)

Get type information for available devices from the specified library.

vector< string > CMMCore::getAvailablePixelSizeConfigs (   )  const

Returns all defined resolution preset names Returns: std::vector<string> an array of resolution presets

std::vector< std::string > CMMCore::getAvailablePropertyBlocks (   )  const

Returns all defined property block identifiers.

unsigned CMMCore::getBytesPerPixel (   )  const

How many bytes for each pixel. This value does not necessarily reflect the capabilities of the particular camera A/D converter. Returns: unsigned number of bytes

string CMMCore::getCameraDevice (   )

Returns the label of the currently selected camera device. Returns: camera name

Configuration CMMCore::getConfigData (  const char *  groupName, const char *  configName )  const throw (CMMError)

Returns the configuration object for a given group and name. Returns: Configuration configuration object

Configuration CMMCore::getConfigGroupState (  const char *  group  )  const throw (CMMError)

Returns the parital state of the system, only for the devices included in the specified group. It will create a union of all devices referenced in a group.

Configuration CMMCore::getConfigState (  const char *  group, const char *  config )  const throw (CMMError)

Returns the parital state of the system, only for the devices included in the specified configuration.

string CMMCore::getCurrentConfig (  const char *  groupName  )  const

Returns the current configuration for a given group. An empty string as a valide return value, since the system state will not always correspond to any of the defined configurations. Also, in general it is possible that the system state fits multiple configurations. This method will return only the first maching configuration, if any. Returns: string configuration name

PropertyBlock CMMCore::getData (  const char *  deviceLabel  )  const

Returns the collection of property-value pairs defined for the current state.

double CMMCore::getDeviceDelayMs (  const char *  label  )  const throw (CMMError)

Reports action delay in milliseconds for the specific device. The delay is used in the synchronization process to ensure that the action is performed, without polling. Value of "0" means that action is either blocking or that polling of device status is required. Some devices ignore this setting. Returns: double - delay time Parameters: const  char* label

vector< string > CMMCore::getDeviceLibraries (  const char *  path  )

Returns a list of library names available in the specified directory. Parameters: path  - serach path. If zero, current working directory will be used as default.

vector< string > CMMCore::getDevicePropertyNames (  const char *  label  )  const throw (CMMError)

Returns all property names supported by the device. Returns: vector<string> property name array Parameters: const  char* label device label

MM::DeviceType CMMCore::getDeviceType (  const char *  label  )  throw (CMMError)

Returns device type.

double CMMCore::getExposure (   )  const throw (CMMError)

Returns the current exposure setting of the camera in milliseconds. Returns: double dExp exposure in milliseconds

string CMMCore::getFocusDevice (   )

Returns the label of the currently selected focus device. Returns: focus stage name

string CMMCore::getHostName (   )  const

Displays current host name.

void * CMMCore::getImage (   )  const throw (CMMError)

Exposes the internal image buffer. Designed specifically for the SWIG wrapping for Java and scripting languages. Returns: a pointer to the internal image buffer.

unsigned CMMCore::getImageBitDepth (   )  const

How many bits of dynamic range are to be expected from the camera. This value should be used only as a guideline - it does not guarante that image buffer will contain only values from the returned dynamic range. Returns: unsigned number of bits

long CMMCore::getImageBufferSize (   )  const

Returns the size of the internal image buffer. Returns: buffer size

unsigned CMMCore::getImageHeight (   )  const

Vertical dimentsion of the image buffer in pixels. Returns: unsigned Y size

string CMMCore::getImageProcessorDevice (   )

Returns the label of the currently selected image processor device.

unsigned CMMCore::getImageWidth (   )  const

Horizontal dimentsion of the image buffer in pixels. Returns: unsigned X size

void * CMMCore::getLastImage (   )  const throw (CMMError)

Gets the last image from the circular buffer. Returns 0 if the buffer is empty.

vector< string > CMMCore::getLoadedDevices (   )  const

Returns an array of labels for currently loaded devices. Returns: vector<string> array of labels

vector< string > CMMCore::getLoadedDevicesOfType (  MM::DeviceType  devType  )  throw (CMMError)

Returns an array of labels for currently loaded devices of specific type. Parameters: devType  - device type identifier Returns: vector<string> array of labels

long CMMCore::getNumberOfStates (  const char *  deviceLabel  )

Returns the total number of available positions (states).

Configuration CMMCore::getPixelSizeConfigData (  const char *  configName  )  const throw (CMMError)

Returns the configuration object for a give pixel size preset. Returns: Configuration configuration object

double CMMCore::getPixelSizeUm (   )  const

Returns the curent pixel size in microns. This method is based on sensing the current pixel size configuration and adjusting for the binning.

double CMMCore::getPosition (  const char *  label  )  const throw (CMMError)

Returns the current position of the stage in microns. Returns: position Parameters: label

string CMMCore::getProperty (  const char *  label, const char *  propName )  const throw (CMMError)

Returns the property value for the specified device. Returns: string property value Parameters: const  char* label device label const  char* propName property name

PropertyBlock CMMCore::getPropertyBlockData (  const char *  blockName  )  const

Returns the collection of property-value pairs defined in this block.

void CMMCore::getROI (  unsigned &  x, unsigned &  y, unsigned &  xSize, unsigned &  ySize )  const throw (CMMError)

Returns info on the current Region Of Interest (ROI). Parameters: unsigned  x coordinate of the top left corner unsigned  y coordinate of the top left corner unsigned  xSize horizontal dimension unsigned  ySize vertical dimension

std::string CMMCore::getSerialPortAnswer (  const char *  name, const char *  term )  throw (CMMError)

Contouously read from the serial port until the terminating sequence is encountered.

string CMMCore::getShutterDevice (   )

Returns the label of the currently selected shutter device. Returns: shutter name

bool CMMCore::getShutterOpen (   )  throw (CMMError)

Return the default shutter state.

long CMMCore::getState (  const char *  deviceLabel  )  const throw (CMMError)

Returns the current state (position) on the specific device. The command will fail if the device does not support states. Returns: long current state Parameters: const  char* deviceLabel device label

long CMMCore::getStateFromLabel (  const char *  deviceLabel, const char *  stateLabel )  const throw (CMMError)

Obtain the state for a given label. Returns: long state Parameters: const  char* deviceLabel device label const  char* stateLabel state label

string CMMCore::getStateLabel (  const char *  deviceLabel  )  const throw (CMMError)

Returns the current state as the label (string). Returns: string state label Parameters: const  char* deviceLabel device label

PropertyBlock CMMCore::getStateLabelData (  const char *  deviceLabel, const char *  stateLabel )  const

Returns the collection of property-value pairs defined for the specific device and state label.

vector< string > CMMCore::getStateLabels (  const char *  deviceLabel  )  const throw (CMMError)

Return labels for all states Returns: vector<string> an array of labels Parameters: const  char* deviceLabel device label

Configuration CMMCore::getSystemState (   )  const

Returns the entire system state, i.e. the collection of all property values from all devices. Returns: - Configuration object containing a collection of device-property-value triplets

string CMMCore::getUserId (   )  const

Displays current user name.

string CMMCore::getVersionInfo (   )  const

Displays core version.

double CMMCore::getXPosition (  const char *  deviceName  )  throw (CMMError)

Obtains the current position of the X axis of the XY stage in microns. Returns: x position Parameters: const  char* label

void CMMCore::getXYPosition (  const char *  deviceName, double &  x, double &  y )  throw (CMMError)

Obtains the current position of the XY stage in microns. Parameters: const  char* label x  y

string CMMCore::getXYStageDevice (   )

Returns the label of the currently selected XYStage device.

double CMMCore::getYPosition (  const char *  deviceName  )  throw (CMMError)

Obtains the current position of the Y axis of the XY stage in microns. Returns: y position Parameters: const  char* label

bool CMMCore::hasProperty (  const char *  label, const char *  propName )  const throw (CMMError)

Checks if device has a property with a specified name. The exception will be thrown in case device label is not defined.

void CMMCore::home (  const char *  deviceName  )  throw (CMMError)

Calibrates and homes the XY stage.

void CMMCore::initializeAllDevices (   )  throw (CMMError)

Calls Initialize() method for each loaded device. This method also initialized allowed values for core properties, based on the collection of loaded devices.

void CMMCore::initializeDevice (  const char *  label  )  throw (CMMError)

Initializes specific device. Parameters: label  device label

bool CMMCore::isConfigDefined (  const char *  groupName, const char *  configName )

Checks if the configuration already exists within a group. Returns: true if the configuration is already defined

bool CMMCore::isGroupDefined (  const char *  groupName  )

Checks if the group already exists. Returns: true if the group is already defined

bool CMMCore::isPropertyPreInit (  const char *  label, const char *  propName )  const throw (CMMError)

Tells us whether the property must be defined prior to initialization. Returns: bool true for pre-init property Parameters: const  char* label device label const  char* propName property name

bool CMMCore::isPropertyReadOnly (  const char *  label, const char *  propName )  const throw (CMMError)

Tells us whether the property can be modified. Returns: bool true for read-only property Parameters: const  char* label device label const  char* propName property name