The Micro-Manager Core. More...

#include <MMCore.h>

Public Member Functions
	CMMCore ()

	~CMMCore ()

Initialization and setup.
void	loadDevice (const char label, const char moduleName, const char *deviceName) throw (CMMError)

void	unloadDevice (const char *label) throw (CMMError)

void	unloadAllDevices () throw (CMMError)

void	initializeAllDevices () throw (CMMError)

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

DeviceInitializationState	getDeviceInitializationState (const char *label) const throw (CMMError)

void	reset () throw (CMMError)

void	unloadLibrary (const char *moduleName) throw (CMMError)

void	updateCoreProperties () throw (CMMError)

std::string	getCoreErrorText (int code) const

std::string	getVersionInfo () const

std::string	getAPIVersionInfo () const

Configuration	getSystemState ()

void	setSystemState (const Configuration &conf)

Configuration	getConfigState (const char group, const char config) throw (CMMError)

Configuration	getConfigGroupState (const char *group) 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)

void	registerCallback (MMEventCallback *cb)

Logging and log management.
void	setPrimaryLogFile (const char *filename, bool truncate=false) throw (CMMError)

std::string	getPrimaryLogFile () const

void	logMessage (const char *msg)

void	logMessage (const char *msg, bool debugOnly)

void	enableDebugLog (bool enable)

bool	debugLogEnabled ()

void	enableStderrLog (bool enable)

bool	stderrLogEnabled ()

int	startSecondaryLogFile (const char *filename, bool enableDebug, bool truncate=true, bool synchronous=false) throw (CMMError)

void	stopSecondaryLogFile (int handle) throw (CMMError)

Device listing.
std::vector< std::string >	getDeviceAdapterSearchPaths ()

void	setDeviceAdapterSearchPaths (const std::vector< std::string > &paths)

std::vector< std::string >	getDeviceAdapterNames () throw (CMMError)

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

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

std::vector< long >	getAvailableDeviceTypes (const char *library) throw (CMMError)

Generic device control.
Functionality supported by all devices.
std::vector< std::string >	getLoadedDevices () const

std::vector< std::string >	getLoadedDevicesOfType (MM::DeviceType devType) const

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

std::string	getDeviceLibrary (const char *label) throw (CMMError)

std::string	getDeviceName (const char *label) throw (CMMError)

std::string	getDeviceDescription (const char *label) throw (CMMError)

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

bool	hasProperty (const char label, const char propName) throw (CMMError)

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

void	setProperty (const char label, const char propName, const char *propValue) throw (CMMError)

void	setProperty (const char label, const char propName, const bool propValue) throw (CMMError)

void	setProperty (const char label, const char propName, const long propValue) throw (CMMError)

void	setProperty (const char label, const char propName, const float propValue) throw (CMMError)

void	setProperty (const char label, const char propName, const double propValue) throw (CMMError)

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

bool	isPropertyReadOnly (const char label, const char propName) throw (CMMError)

bool	isPropertyPreInit (const char label, const char propName) throw (CMMError)

bool	isPropertySequenceable (const char label, const char propName) throw (CMMError)

bool	hasPropertyLimits (const char label, const char propName) throw (CMMError)

double	getPropertyLowerLimit (const char label, const char propName) throw (CMMError)

double	getPropertyUpperLimit (const char label, const char propName) throw (CMMError)

MM::PropertyType	getPropertyType (const char label, const char propName) throw (CMMError)

void	startPropertySequence (const char label, const char propName) throw (CMMError)

void	stopPropertySequence (const char label, const char propName) throw (CMMError)

long	getPropertySequenceMaxLength (const char label, const char propName) throw (CMMError)

void	loadPropertySequence (const char label, const char propName, std::vector< std::string > eventSequence) throw (CMMError)

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

void	waitForDevice (const char *label) throw (CMMError)

void	waitForConfig (const char group, const char configName) throw (CMMError)

bool	systemBusy () throw (CMMError)

void	waitForSystem () throw (CMMError)

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

void	waitForDeviceType (MM::DeviceType devType) throw (CMMError)

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

void	setDeviceDelayMs (const char *label, double delayMs) throw (CMMError)

bool	usesDeviceDelay (const char *label) throw (CMMError)

void	setTimeoutMs (long timeoutMs)

long	getTimeoutMs ()

void	sleep (double intervalMs) const

Management of 'current' device for specific roles.
std::string	getCameraDevice ()

std::string	getShutterDevice ()

std::string	getFocusDevice ()

std::string	getXYStageDevice ()

std::string	getAutoFocusDevice ()

std::string	getImageProcessorDevice ()

std::string	getSLMDevice ()

std::string	getGalvoDevice ()

std::string	getChannelGroup ()

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)

void	setSLMDevice (const char *slmLabel) throw (CMMError)

void	setGalvoDevice (const char *galvoLabel) throw (CMMError)

void	setChannelGroup (const char *channelGroup) throw (CMMError)

System state cache.
The system state cache retains the last-set or last-read value of each device property.
Configuration	getSystemStateCache () const

void	updateSystemStateCache ()

std::string	getPropertyFromCache (const char deviceLabel, const char propName) const throw (CMMError)

std::string	getCurrentConfigFromCache (const char *groupName) throw (CMMError)

Configuration	getConfigGroupStateFromCache (const char *group) throw (CMMError)

Configuration groups.
void	defineConfig (const char groupName, const char configName) throw (CMMError)

void	defineConfig (const char groupName, const char configName, const char deviceLabel, const char propName, const char *value) throw (CMMError)

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

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

void	renameConfigGroup (const char oldGroupName, const char newGroupName) 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)

void	deleteConfig (const char groupName, const char configName, const char deviceLabel, const char propName) throw (CMMError)

void	renameConfig (const char groupName, const char oldConfigName, const char *newConfigName) throw (CMMError)

std::vector< std::string >	getAvailableConfigGroups () const

std::vector< std::string >	getAvailableConfigs (const char *configGroup) const

std::string	getCurrentConfig (const char *groupName) throw (CMMError)

Configuration	getConfigData (const char configGroup, const char configName) throw (CMMError)

The pixel size configuration group.
std::string	getCurrentPixelSizeConfig () throw (CMMError)

std::string	getCurrentPixelSizeConfig (bool cached) throw (CMMError)

double	getPixelSizeUm ()

double	getPixelSizeUm (bool cached)

double	getPixelSizeUmByID (const char *resolutionID) throw (CMMError)

std::vector< double >	getPixelSizeAffine () throw (CMMError)

std::vector< double >	getPixelSizeAffine (bool cached) throw (CMMError)

std::vector< double >	getPixelSizeAffineByID (const char *resolutionID) throw (CMMError)

double	getMagnificationFactor () const

void	setPixelSizeUm (const char *resolutionID, double pixSize) throw (CMMError)

void	setPixelSizeAffine (const char *resolutionID, std::vector< double > affine) throw (CMMError)

void	definePixelSizeConfig (const char resolutionID, const char deviceLabel, const char propName, const char value) throw (CMMError)

void	definePixelSizeConfig (const char *resolutionID) throw (CMMError)

std::vector< std::string >	getAvailablePixelSizeConfigs () const

bool	isPixelSizeConfigDefined (const char *resolutionID) const throw (CMMError)

void	setPixelSizeConfig (const char *resolutionID) throw (CMMError)

void	renamePixelSizeConfig (const char oldConfigName, const char newConfigName) throw (CMMError)

void	deletePixelSizeConfig (const char *configName) throw (CMMError)

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

Image acquisition.
void	setROI (int x, int y, int xSize, int ySize) throw (CMMError)

void	setROI (const char *label, int x, int y, int xSize, int ySize) throw (CMMError)

void	getROI (int &x, int &y, int &xSize, int &ySize) throw (CMMError)

void	getROI (const char *label, int &x, int &y, int &xSize, int &ySize) throw (CMMError)

void	clearROI () throw (CMMError)

bool	isMultiROISupported () throw (CMMError)

bool	isMultiROIEnabled () throw (CMMError)

void	setMultiROI (std::vector< unsigned > xs, std::vector< unsigned > ys, std::vector< unsigned > widths, std::vector< unsigned > heights) throw (CMMError)

void	getMultiROI (std::vector< unsigned > &xs, std::vector< unsigned > &ys, std::vector< unsigned > &widths, std::vector< unsigned > &heights) throw (CMMError)

void	setExposure (double exp) throw (CMMError)

void	setExposure (const char *cameraLabel, double dExp) throw (CMMError)

double	getExposure () throw (CMMError)

double	getExposure (const char *label) throw (CMMError)

void	snapImage () throw (CMMError)

void *	getImage () throw (CMMError)

void *	getImage (unsigned numChannel) throw (CMMError)

unsigned	getImageWidth ()

unsigned	getImageHeight ()

unsigned	getBytesPerPixel ()

unsigned	getImageBitDepth ()

unsigned	getNumberOfComponents ()

unsigned	getNumberOfCameraChannels ()

std::string	getCameraChannelName (unsigned int channelNr)

long	getImageBufferSize ()

void	setAutoShutter (bool state)

bool	getAutoShutter ()

void	setShutterOpen (bool state) throw (CMMError)

bool	getShutterOpen () throw (CMMError)

void	setShutterOpen (const char *shutterLabel, bool state) throw (CMMError)

bool	getShutterOpen (const char *shutterLabel) throw (CMMError)

void	startSequenceAcquisition (long numImages, double intervalMs, bool stopOnOverflow) throw (CMMError)

void	startSequenceAcquisition (const char *cameraLabel, long numImages, double intervalMs, bool stopOnOverflow) throw (CMMError)

void	prepareSequenceAcquisition (const char *cameraLabel) throw (CMMError)

void	startContinuousSequenceAcquisition (double intervalMs) throw (CMMError)

void	stopSequenceAcquisition () throw (CMMError)

void	stopSequenceAcquisition (const char *cameraLabel) throw (CMMError)

bool	isSequenceRunning () throw ()

bool	isSequenceRunning (const char *cameraLabel) throw (CMMError)

void *	getLastImage () throw (CMMError)

void *	popNextImage () throw (CMMError)

void *	getLastImageMD (unsigned channel, unsigned slice, Metadata &md) const throw (CMMError)

void *	popNextImageMD (unsigned channel, unsigned slice, Metadata &md) throw (CMMError)

void *	getLastImageMD (Metadata &md) const throw (CMMError)

void *	getNBeforeLastImageMD (unsigned long n, Metadata &md) const throw (CMMError)

void *	popNextImageMD (Metadata &md) throw (CMMError)

long	getRemainingImageCount ()

long	getBufferTotalCapacity ()

long	getBufferFreeCapacity ()

bool	isBufferOverflowed () const

void	setCircularBufferMemoryFootprint (unsigned sizeMB) throw (CMMError)

unsigned	getCircularBufferMemoryFootprint ()

void	initializeCircularBuffer () throw (CMMError)

void	clearCircularBuffer () throw (CMMError)

bool	isExposureSequenceable (const char *cameraLabel) throw (CMMError)

void	startExposureSequence (const char *cameraLabel) throw (CMMError)

void	stopExposureSequence (const char *cameraLabel) throw (CMMError)

long	getExposureSequenceMaxLength (const char *cameraLabel) throw (CMMError)

void	loadExposureSequence (const char *cameraLabel, std::vector< double > exposureSequence_ms) throw (CMMError)

Autofocus control.
double	getLastFocusScore ()

double	getCurrentFocusScore ()

void	enableContinuousFocus (bool enable) throw (CMMError)

bool	isContinuousFocusEnabled () throw (CMMError)

bool	isContinuousFocusLocked () throw (CMMError)

bool	isContinuousFocusDrive (const char *stageLabel) throw (CMMError)

void	fullFocus () throw (CMMError)

void	incrementalFocus () throw (CMMError)

void	setAutoFocusOffset (double offset) throw (CMMError)

double	getAutoFocusOffset () throw (CMMError)

State device control.
void	setState (const char *stateDeviceLabel, long state) throw (CMMError)

long	getState (const char *stateDeviceLabel) throw (CMMError)

long	getNumberOfStates (const char *stateDeviceLabel)

void	setStateLabel (const char stateDeviceLabel, const char stateLabel) throw (CMMError)

std::string	getStateLabel (const char *stateDeviceLabel) throw (CMMError)

void	defineStateLabel (const char stateDeviceLabel, long state, const char stateLabel) throw (CMMError)

std::vector< std::string >	getStateLabels (const char *stateDeviceLabel) throw (CMMError)

long	getStateFromLabel (const char stateDeviceLabel, const char stateLabel) throw (CMMError)

Focus (Z) stage control.
void	setPosition (const char *stageLabel, double position) throw (CMMError)

void	setPosition (double position) throw (CMMError)

double	getPosition (const char *stageLabel) throw (CMMError)

double	getPosition () throw (CMMError)

void	setRelativePosition (const char *stageLabel, double d) throw (CMMError)

void	setRelativePosition (double d) throw (CMMError)

void	setOrigin (const char *stageLabel) throw (CMMError)

void	setOrigin () throw (CMMError)

void	setAdapterOrigin (const char *stageLabel, double newZUm) throw (CMMError)

void	setAdapterOrigin (double newZUm) throw (CMMError)

void	setFocusDirection (const char *stageLabel, int sign)
	Set the focus direction of a stage.

int	getFocusDirection (const char *stageLabel) throw (CMMError)
	Get the focus direction of a stage.

bool	isStageSequenceable (const char *stageLabel) throw (CMMError)

bool	isStageLinearSequenceable (const char *stageLabel) throw (CMMError)

void	startStageSequence (const char *stageLabel) throw (CMMError)

void	stopStageSequence (const char *stageLabel) throw (CMMError)

long	getStageSequenceMaxLength (const char *stageLabel) throw (CMMError)

void	loadStageSequence (const char *stageLabel, std::vector< double > positionSequence) throw (CMMError)

void	setStageLinearSequence (const char *stageLabel, double dZ_um, int nSlices) throw (CMMError)

XY stage control.
void	setXYPosition (const char *xyStageLabel, double x, double y) throw (CMMError)

void	setXYPosition (double x, double y) throw (CMMError)

void	setRelativeXYPosition (const char *xyStageLabel, double dx, double dy) throw (CMMError)

void	setRelativeXYPosition (double dx, double dy) throw (CMMError)

void	getXYPosition (const char *xyStageLabel, double &x_stage, double &y_stage) throw (CMMError)

void	getXYPosition (double &x_stage, double &y_stage) throw (CMMError)

double	getXPosition (const char *xyStageLabel) throw (CMMError)

double	getYPosition (const char *xyStageLabel) throw (CMMError)

double	getXPosition () throw (CMMError)

double	getYPosition () throw (CMMError)

void	stop (const char *xyOrZStageLabel) throw (CMMError)

void	home (const char *xyOrZStageLabel) throw (CMMError)

void	setOriginXY (const char *xyStageLabel) throw (CMMError)

void	setOriginXY () throw (CMMError)

void	setOriginX (const char *xyStageLabel) throw (CMMError)

void	setOriginX () throw (CMMError)

void	setOriginY (const char *xyStageLabel) throw (CMMError)

void	setOriginY () throw (CMMError)

void	setAdapterOriginXY (const char *xyStageLabel, double newXUm, double newYUm) throw (CMMError)

void	setAdapterOriginXY (double newXUm, double newYUm) throw (CMMError)

bool	isXYStageSequenceable (const char *xyStageLabel) throw (CMMError)

void	startXYStageSequence (const char *xyStageLabel) throw (CMMError)

void	stopXYStageSequence (const char *xyStageLabel) throw (CMMError)

long	getXYStageSequenceMaxLength (const char *xyStageLabel) throw (CMMError)

void	loadXYStageSequence (const char *xyStageLabel, std::vector< double > xSequence, std::vector< double > ySequence) throw (CMMError)

Serial port control.
void	setSerialProperties (const char portName, const char answerTimeout, const char baudRate, const char delayBetweenCharsMs, const char handshaking, const char parity, const char *stopBits) throw (CMMError)

void	setSerialPortCommand (const char portLabel, const char command, const char *term) throw (CMMError)

std::string	getSerialPortAnswer (const char portLabel, const char term) throw (CMMError)

void	writeToSerialPort (const char *portLabel, const std::vector< char > &data) throw (CMMError)

std::vector< char >	readFromSerialPort (const char *portLabel) throw (CMMError)

SLM control.
Control of spatial light modulators such as liquid crystal on silicon (LCoS), digital micromirror devices (DMD), or multimedia projectors.
void	setSLMImage (const char slmLabel, unsigned char pixels) throw (CMMError)

void	setSLMImage (const char *slmLabel, imgRGB32 pixels) throw (CMMError)

void	setSLMPixelsTo (const char *slmLabel, unsigned char intensity) throw (CMMError)

void	setSLMPixelsTo (const char *slmLabel, unsigned char red, unsigned char green, unsigned char blue) throw (CMMError)

void	displaySLMImage (const char *slmLabel) throw (CMMError)

void	setSLMExposure (const char *slmLabel, double exposure_ms) throw (CMMError)

double	getSLMExposure (const char *slmLabel) throw (CMMError)

unsigned	getSLMWidth (const char *slmLabel) throw (CMMError)

unsigned	getSLMHeight (const char *slmLabel) throw (CMMError)

unsigned	getSLMNumberOfComponents (const char *slmLabel) throw (CMMError)

unsigned	getSLMBytesPerPixel (const char *slmLabel) throw (CMMError)

long	getSLMSequenceMaxLength (const char *slmLabel) throw (CMMError)

void	startSLMSequence (const char *slmLabel) throw (CMMError)

void	stopSLMSequence (const char *slmLabel) throw (CMMError)

void	loadSLMSequence (const char slmLabel, std::vector< unsigned char > imageSequence) throw (CMMError)

Galvo control.
Control of beam-steering devices.
void	pointGalvoAndFire (const char *galvoLabel, double x, double y, double pulseTime_us) throw (CMMError)

void	setGalvoSpotInterval (const char *galvoLabel, double pulseTime_us) throw (CMMError)

void	setGalvoPosition (const char *galvoLabel, double x, double y) throw (CMMError)

void	getGalvoPosition (const char *galvoLabel, double &x_stage, double &y_stage) throw (CMMError)

void	setGalvoIlluminationState (const char *galvoLabel, bool on) throw (CMMError)

double	getGalvoXRange (const char *galvoLabel) throw (CMMError)

double	getGalvoXMinimum (const char *galvoLabel) throw (CMMError)

double	getGalvoYRange (const char *galvoLabel) throw (CMMError)

double	getGalvoYMinimum (const char *galvoLabel) throw (CMMError)

void	addGalvoPolygonVertex (const char *galvoLabel, int polygonIndex, double x, double y) throw (CMMError)

void	deleteGalvoPolygons (const char *galvoLabel) throw (CMMError)

void	loadGalvoPolygons (const char *galvoLabel) throw (CMMError)

void	setGalvoPolygonRepetitions (const char *galvoLabel, int repetitions) throw (CMMError)

void	runGalvoPolygons (const char *galvoLabel) throw (CMMError)

void	runGalvoSequence (const char *galvoLabel) throw (CMMError)

std::string	getGalvoChannel (const char *galvoLabel) throw (CMMError)

Device discovery.
bool	supportsDeviceDetection (const char *deviceLabel)

MM::DeviceDetectionStatus	detectDevice (const char *deviceLabel)

Hub and peripheral devices.
std::string	getParentLabel (const char *peripheralLabel) throw (CMMError)

void	setParentLabel (const char deviceLabel, const char parentHubLabel) throw (CMMError)

std::vector< std::string >	getInstalledDevices (const char *hubLabel) throw (CMMError)

std::string	getInstalledDeviceDescription (const char hubLabel, const char peripheralLabel) throw (CMMError)

std::vector< std::string >	getLoadedPeripheralDevices (const char *hubLabel) throw (CMMError)

Static Public Member Functions
static void	noop ()
	A static method that does nothing.

Core feature control.
static void	enableFeature (const char *name, bool enable) throw (CMMError)

static bool	isFeatureEnabled (const char *name) throw (CMMError)

Friends
class	CoreCallback

class	CorePropertyCollection

Detailed Description

The Micro-Manager Core.

Provides a device-independent interface for hardware control. Additionally, provides some facilities (such as configuration groups) for application programming.

The signatures of most of the public member functions are designed to be wrapped by SWIG with minimal manual configuration.

Constructor & Destructor Documentation

◆ CMMCore()

CMMCore::CMMCore ( )

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

◆ ~CMMCore()

CMMCore::~CMMCore ( )

Destructor. Cleans-up and unloads all devices.

References reset().

Member Function Documentation

◆ addGalvoPolygonVertex()

void CMMCore::addGalvoPolygonVertex	(	const char *	deviceLabel,
		int	polygonIndex,
		double	x,
		double	y
	)
throw	(	CMMError
	)

Add a vertex to a galvo polygon.

◆ clearCircularBuffer()

void CMMCore::clearCircularBuffer	(		)
throw	(	CMMError
	)

Removes all images from the circular buffer.

It is rarely necessary to call this directly since starting a sequence acquisition or changing the ROI will always clear the buffer.

◆ clearROI()

void CMMCore::clearROI	(		)
throw	(	CMMError
	)

Set the region of interest of the current camera to the full frame.

A successful call to this method will clear any images in the sequence buffer, even if the ROI does not change.

◆ debugLogEnabled()

bool CMMCore::debugLogEnabled ( )

Indicates if logging of debug messages is enabled

◆ defineConfig() [1/2]

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

Defines a configuration. If the configuration group/name was not previously defined a new configuration will be automatically created; otherwise nothing happens.

Parameters

groupName	the configuration group name
configName	the configuration preset name

◆ defineConfig() [2/2]

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

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	the group name
configName	the configuration name
deviceLabel	the device label
propName	the property name
value	the property value

◆ defineConfigGroup()

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

Creates an empty configuration group.

◆ definePixelSizeConfig() [1/2]

void CMMCore::definePixelSizeConfig	(	const char *	resolutionID	)
throw	(	CMMError
	)

Defines an empty pixel size entry.

◆ definePixelSizeConfig() [2/2]

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

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

◆ defineStateLabel()

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

Defines a label for the specific state/

Parameters

deviceLabel	the device label
state	the state to be labeled
label	the label for the specified state

References Configuration::isPropertyIncluded(), and Configuration::isSettingIncluded().

◆ deleteConfig() [1/2]

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.

◆ deleteConfig() [2/2]

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

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

◆ deleteConfigGroup()

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

Deletes an entire configuration group.

◆ deleteGalvoPolygons()

void CMMCore::deleteGalvoPolygons	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Remove all added polygons

◆ deletePixelSizeConfig()

void CMMCore::deletePixelSizeConfig	(	const char *	configName	)
throw	(	CMMError
	)

Deletes a pixel size configuration. The command will fail if the configuration was not previously defined.

◆ detectDevice()

MM::DeviceDetectionStatus CMMCore::detectDevice ( const char * label )

Tries to communicate to a device through a given serial port Used to automate discovery of correct serial port Also configures the serial port correctly

For legacy reasons, an exception is not thrown if there is an error. Instead, MM::Unimplemented is returned if label is not a valid device.

Parameters

label the label of the device for which the serial port should be found

References getProperty(), and setProperty().

◆ deviceBusy()

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

Checks the busy status of the specific device.

Parameters

label the device label

Returns: true if the device is busy

◆ deviceTypeBusy()

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 specified type are busy.

Returns: true on busy

Parameters

devType a constant specifying the device type

Referenced by systemBusy().

◆ displaySLMImage()

void CMMCore::displaySLMImage	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Display the waiting image on the SLM.

◆ enableContinuousFocus()

void CMMCore::enableContinuousFocus	(	bool	enable	)
throw	(	CMMError
	)

Enables or disables the operation of the continuous focusing hardware device.

◆ enableDebugLog()

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

◆ enableFeature()

void CMMCore::enableFeature	(	const char *	name,
		bool	enable
	)
throw	(	CMMError
	)

static

Enable or disable the given Core feature.

Core features control whether experimental functionality (which is subject to breaking changes) is exposed, or whether stricter API usage is enforced.

Currently switchable features:

"StrictInitializationChecks" (default: disabled) When enabled, an exception is thrown when an operation requiring an initialized device is attempted on a device that is not successfully initialized. When disabled, no exception is thrown and a warning is logged (and the operation may potentially cause incorrect behavior or a crash).
"ParallelDeviceInitialization" (default: enabled) When enabled, serial ports are initialized in serial order, and all other devices are in parallel, using multiple threads, one per device module. Early testing shows this to be reliable, but switch this off when issues are encountered during device initialization.

Permanently enabled features:

None so far.

Permanently disabled features:

None so far.

Parameters

name	the feature name.
enable	whether to enable or disable the feature.

Exceptions

CMMError if the feature name is null or unknown, or attempting to disable a permanently enabled feature, or attempting to enable a permanently disabled feature.

◆ enableStderrLog()

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.

◆ fullFocus()

void CMMCore::fullFocus	(		)
throw	(	CMMError
	)

Performs focus acquisition and lock for the one-shot focusing device.

References getCoreErrorText(), and getDeviceName().

◆ getAllowedPropertyValues()

std::vector< std::string > CMMCore::getAllowedPropertyValues	(	const char *	label,
		const char *	propName
	)
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 actually accepted by the device at run time.

Returns: the array of values

Parameters

label	the device label
propName	the property name

◆ getAPIVersionInfo()

std::string CMMCore::getAPIVersionInfo ( ) const

Returns the module and device interface versions.

◆ getAutoFocusDevice()

std::string CMMCore::getAutoFocusDevice ( )

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

◆ getAutoFocusOffset()

double CMMCore::getAutoFocusOffset	(		)
throw	(	CMMError
	)

Measures offset for the one-shot focusing device.

References getCoreErrorText(), and getDeviceName().

◆ getAutoShutter()

bool CMMCore::getAutoShutter ( )

Returns the current setting of the auto-shutter option.

◆ getAvailableConfigGroups()

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

Returns the names of all defined configuration groups

Returns: an array of names of configuration groups

References ConfigGroupCollection::GetAvailableGroups().

Referenced by CoreCallback::OnPropertyChanged().

◆ getAvailableConfigs()

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

Returns all defined configuration names in a given group

For legacy reasons, an exception is not thrown if there is an error. Instead, an empty vector is returned if group is not a valid config group.

Returns: an array of configuration names

References ConfigGroupCollection::GetAvailableConfigs().

Referenced by CoreCallback::OnPropertyChanged().

◆ getAvailableDeviceDescriptions()

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

Get descriptions for available devices from the specified library.

◆ getAvailableDevices()

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

Get available devices from the specified device library.

◆ getAvailableDeviceTypes()

std::vector< long > CMMCore::getAvailableDeviceTypes	(	const char *	moduleName	)
throw	(	CMMError
	)

Get type information for available devices from the specified library.

◆ getAvailablePixelSizeConfigs()

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

Returns all defined resolution preset names

Returns: an array of resolution presets

References ConfigGroupBase< T >::GetAvailable().

Referenced by CoreCallback::OnPropertyChanged().

◆ getBufferFreeCapacity()

long CMMCore::getBufferFreeCapacity ( )

Returns the number of images that can be added to the buffer without overflowing

◆ getBufferTotalCapacity()

long CMMCore::getBufferTotalCapacity ( )

Returns the total number of images that can be stored in the buffer

◆ getBytesPerPixel()

unsigned CMMCore::getBytesPerPixel ( )

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

Returns: the number of bytes

◆ getCameraChannelName()

std::string CMMCore::getCameraChannelName ( unsigned int channelNr )

Returns the name of the requested channel as known by the default camera

◆ getCameraDevice()

std::string CMMCore::getCameraDevice ( )

Returns the label of the currently selected camera device.

Returns: camera name

◆ getChannelGroup()

std::string CMMCore::getChannelGroup ( )

Returns the group determining the channel selection.

◆ getCircularBufferMemoryFootprint()

unsigned CMMCore::getCircularBufferMemoryFootprint ( )

Returns the size of the Circular Buffer in MB

◆ getConfigData()

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

Returns the configuration object for a given group and name.

Returns: The configuration object

Referenced by CoreCallback::OnPropertyChanged().

◆ getConfigGroupState()

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

Returns the partial 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.

◆ getConfigGroupStateFromCache()

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

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

◆ getConfigState()

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

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

References Configuration::addSetting(), PropertySetting::getDeviceLabel(), PropertySetting::getPropertyName(), Configuration::getSetting(), and Configuration::size().

◆ getCoreErrorText()

std::string CMMCore::getCoreErrorText ( int code ) const

Returns a pre-defined error test with the given error code

Referenced by fullFocus(), getAutoFocusOffset(), getImage(), getLastImage(), incrementalFocus(), initializeCircularBuffer(), isMultiROIEnabled(), isMultiROISupported(), popNextImage(), snapImage(), and stopSequenceAcquisition().

◆ getCurrentConfig()

std::string CMMCore::getCurrentConfig	(	const char *	groupName	)
throw	(	CMMError
	)

Returns the current configuration for a given group. An empty string is a valid 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 matching configuration, if any.

Returns: The current configuration preset's name

References Configuration::isConfigurationIncluded().

◆ getCurrentConfigFromCache()

std::string CMMCore::getCurrentConfigFromCache	(	const char *	groupName	)
throw	(	CMMError
	)

Returns the configuration for a given group based on the data in the cache. An empty string is a valid 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 matching configuration, if any.

Returns: The cache's current configuration preset name

References Configuration::isConfigurationIncluded().

Referenced by CoreCallback::OnPropertyChanged().

◆ getCurrentFocusScore()

double CMMCore::getCurrentFocusScore ( )

Returns the focus score from the default focusing device measured at the current Z position. Use this value to create profiles or just to verify that the image is in focus. The absolute range of returned scores depends on the actual focusing device.

◆ getCurrentPixelSizeConfig() [1/2]

std::string CMMCore::getCurrentPixelSizeConfig	(		)
throw	(	CMMError
	)

Get the current pixel configuration name

References getCurrentPixelSizeConfig().

Referenced by getCurrentPixelSizeConfig(), and getPixelSizeUm().

◆ getCurrentPixelSizeConfig() [2/2]

std::string CMMCore::getCurrentPixelSizeConfig	(	bool	cached	)
throw	(	CMMError
	)

Get the current pixel configuration name

References Configuration::addSetting(), PropertySetting::getDeviceLabel(), CMMError::getMsg(), PropertySetting::getPropertyName(), Configuration::getSetting(), Configuration::isConfigurationIncluded(), Configuration::isPropertyIncluded(), and Configuration::size().

◆ getDeviceAdapterNames()

std::vector< std::string > CMMCore::getDeviceAdapterNames	(		)
throw	(	CMMError
	)

Return the names of discoverable device adapters.

Note that this list is constructed based on filename matching in the current search paths. This method does not check whether the files are valid and compatible device adapters.

◆ getDeviceAdapterSearchPaths()

std::vector< std::string > CMMCore::getDeviceAdapterSearchPaths ( )

Return the current device adapter search paths.

◆ getDeviceDelayMs()

double CMMCore::getDeviceDelayMs	(	const char *	label	)
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: the delay time in milliseconds

Parameters

label the device label

◆ getDeviceDescription()

std::string CMMCore::getDeviceDescription	(	const char *	label	)
throw	(	CMMError
	)

Returns description text for a given device label. "Description" is determined by the library and is immutable.

◆ getDeviceInitializationState()

DeviceInitializationState CMMCore::getDeviceInitializationState	(	const char *	label	)	const
throw	(	CMMError
	)

Queries the initialization state of the given device.

Parameters

label the device label

◆ getDeviceLibrary()

std::string CMMCore::getDeviceLibrary	(	const char *	label	)
throw	(	CMMError
	)

Returns device library (aka module, device adapter) name.

◆ getDeviceName()

std::string CMMCore::getDeviceName	(	const char *	label	)
throw	(	CMMError
	)

Returns device name for a given device label. "Name" is determined by the library and is immutable, while "label" is user assigned and represents a high-level handle to a device.

Referenced by fullFocus(), getAutoFocusOffset(), incrementalFocus(), initializeCircularBuffer(), isContinuousFocusEnabled(), and stopSequenceAcquisition().

◆ getDevicePropertyNames()

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

Returns all property names supported by the device.

Returns: property name array

Parameters

label the device label

◆ getDeviceType()

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

Returns device type.

◆ getExposure() [1/2]

double CMMCore::getExposure	(		)
throw	(	CMMError
	)

Returns the current exposure setting of the camera in milliseconds.

Returns: the exposure time in milliseconds

◆ getExposure() [2/2]

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

Returns the current exposure setting of the specified camera in milliseconds.

Parameters

label the camera device label

Returns: the exposure time in milliseconds

◆ getExposureSequenceMaxLength()

long CMMCore::getExposureSequenceMaxLength	(	const char *	cameraLabel	)
throw	(	CMMError
	)

Gets the maximum length of a camera's exposure sequence. This should only be called for cameras where exposure time is sequenceable

Parameters

cameraLabel the camera device label

◆ getFocusDevice()

std::string CMMCore::getFocusDevice ( )

Returns the label of the currently selected focus device.

Returns: focus stage name

Referenced by getPosition(), and setOrigin().

◆ getFocusDirection()

int CMMCore::getFocusDirection	(	const char *	stageLabel	)
throw	(	CMMError
	)

Get the focus direction of a stage.

Returns +1 if increasing position brings objective closer to sample, -1 if increasing position moves objective away from sample, or 0 if unknown. (Make sure to check for zero!)

The returned value is determined by the most recent call to setFocusDirection() for the stage, or defaults to what the stage device adapter declares (often 0, for unknown).

An exception is thrown if the direction has not been set and the device encounters an error when determining the default direction.

◆ getGalvoChannel()

std::string CMMCore::getGalvoChannel	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Get the name of the active galvo channel (for a multi-laser galvo device).

◆ getGalvoDevice()

std::string CMMCore::getGalvoDevice ( )

Returns the label of the currently selected Galvo device.

Returns: galvo name

◆ getGalvoPosition()

void CMMCore::getGalvoPosition	(	const char *	deviceLabel,
		double &	x,
		double &	y
	)
throw	(	CMMError
	)

Get the Galvo x,y position

◆ getGalvoXMinimum()

double CMMCore::getGalvoXMinimum	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Get the Galvo x minimum

◆ getGalvoXRange()

double CMMCore::getGalvoXRange	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Get the Galvo x range

◆ getGalvoYMinimum()

double CMMCore::getGalvoYMinimum	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Get the Galvo y minimum

◆ getGalvoYRange()

double CMMCore::getGalvoYRange	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Get the Galvo y range

◆ getImage() [1/2]

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

Exposes the internal image buffer.

Use to get the image acquired by snapImage

Multi-Channel cameras will return the content of the first channel in this function

Designed specifically for the SWIG wrapping for Java and scripting languages.

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 the format is BGRA888 (see: https://en.wikipedia.org/wiki/RGBA_color_model).

Returns: a pointer to the internal image buffer.

Exceptions

CMMError when the camera returns no data

References getCoreErrorText().

◆ getImage() [2/2]

void * CMMCore::getImage	(	unsigned	channelNr	)
throw	(	CMMError
	)

Returns the internal image buffer for a given Camera Channel

Use to get the image acquired by snapImage

Single channel cameras will return the content of their image buffer irrespective of the channelNr argument Designed specifically for the SWIG wrapping for Java and scripting languages.

Parameters

channelNr Channel number for which the image buffer is requested

Returns: a pointer to the internal image buffer.

◆ getImageBitDepth()

unsigned CMMCore::getImageBitDepth ( )

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 guarantee that image buffer will contain only values from the returned dynamic range.

Returns: the number of bits

◆ getImageBufferSize()

long CMMCore::getImageBufferSize ( )

Returns the size of the internal image buffer.

Returns: buffer size

◆ getImageHeight()

unsigned CMMCore::getImageHeight ( )

Vertical dimension of the image buffer in pixels.

Returns: the height in pixels (an integer)

◆ getImageProcessorDevice()

std::string CMMCore::getImageProcessorDevice ( )

Returns the label of the currently selected image processor device.

◆ getImageWidth()

unsigned CMMCore::getImageWidth ( )

Horizontal dimension of the image buffer in pixels.

Returns: the width in pixels (an integer)

◆ getInstalledDevices()

std::vector< std::string > CMMCore::getInstalledDevices	(	const char *	hubDeviceLabel	)
throw	(	CMMError
	)

Performs auto-detection and loading of child devices that are attached to a Hub device. For example, if a motorized microscope is represented by a Hub device, it is capable of discovering what specific child devices are currently attached. In that case this call might report that Z-stage, filter changer and objective turret are currently installed and return three device names in the string list.

Currently, this method can only be called once, right after loading the hub device. Doing otherwise results in undefined behavior. This function was intended for use during initial configuration, not routine loading of devices. These restrictions may be relaxed in the future if possible.

Parameters

hubDeviceLabel the label for the device of type Hub

◆ getLastFocusScore()

double CMMCore::getLastFocusScore ( )

Returns the latest focus score from the focusing device. Use this value to estimate or record how reliable the focus is. The range of values is device dependent.

◆ getLastImage()

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

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

References getCoreErrorText().

◆ getLastImageMD()

void * CMMCore::getLastImageMD	(	Metadata &	md	)	const
throw	(	CMMError
	)

Returns a pointer to the pixels of the image that was last inserted into the circular buffer Also provides all metadata associated with that image

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 the format is BGRA888 (see: https://en.wikipedia.org/wiki/RGBA_color_model).

◆ getLoadedDevices()

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

Returns an array of labels for currently loaded devices.

Returns: array of labels

◆ getLoadedDevicesOfType()

std::vector< std::string > CMMCore::getLoadedDevicesOfType ( MM::DeviceType devType ) const

Returns an array of labels for currently loaded devices of specific type.

Parameters

devType the device type identifier

Returns: array of labels

Referenced by getMagnificationFactor().

◆ getMagnificationFactor()

double CMMCore::getMagnificationFactor ( ) const

Returns the product of all Magnifiers in the system or 1.0 when none is found This is used internally by GetPixelSizeUm

Returns: products of all magnifier devices in the system or 1.0 when none is found

References getLoadedDevicesOfType().

Referenced by getPixelSizeUm().

◆ getMultiROI()

void CMMCore::getMultiROI	(	std::vector< unsigned > &	xs,
		std::vector< unsigned > &	ys,
		std::vector< unsigned > &	widths,
		std::vector< unsigned > &	heights
	)
throw	(	CMMError
	)

Get multiple ROIs from the current camera device. Will fail if the camera does not support multiple ROIs. Will return empty vectors if multiple ROIs are not currently being used.

Parameters

xs	(Return value) X indices for the upper-left corners of each ROI.
ys	(Return value) Y indices for the upper-left corners of each ROI.
widths	(Return value) Width in pixels for each ROI.
heights	(Return value) Height in pixels for each ROI.

◆ getNBeforeLastImageMD()

void * CMMCore::getNBeforeLastImageMD	(	unsigned long	n,
		Metadata &	md
	)		const
throw	(	CMMError
	)

Returns a pointer to the pixels of the image that was inserted n images ago Also provides all metadata associated with that image

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 the format is BGRA888 (see: https://en.wikipedia.org/wiki/RGBA_color_model).

◆ getNumberOfCameraChannels()

unsigned CMMCore::getNumberOfCameraChannels ( )

Returns the number of simultaneous channels the default camera is returning.

◆ getNumberOfComponents()

unsigned CMMCore::getNumberOfComponents ( )

Returns the number of components the default camera is returning. For example color camera will return 4 components (RGBA) on each snap.

◆ getNumberOfStates()

long CMMCore::getNumberOfStates ( const char * deviceLabel )

Returns the total number of available positions (states).

For legacy reasons, an exception is not thrown on error. Instead, -1 is returned if deviceLabel is not a valid state device.

◆ getParentLabel()

std::string CMMCore::getParentLabel	(	const char *	label	)
throw	(	CMMError
	)

Returns parent device.

◆ getPixelSizeAffine() [1/2]

std::vector< double > CMMCore::getPixelSizeAffine	(		)
throw	(	CMMError
	)

Returns the current Affine Transform to related camera pixels with stage movement.. This function returns the stored affine transform corrected for binning

References getPixelSizeAffine().

Referenced by getPixelSizeAffine(), CoreCallback::OnMagnifierChanged(), and CoreCallback::OnPropertyChanged().

◆ getPixelSizeAffine() [2/2]

std::vector< double > CMMCore::getPixelSizeAffine	(	bool	cached	)
throw	(	CMMError
	)

Returns the current Affine Transform to related camera pixels with stage movement.. This function returns the stored affine transform corrected for binning and known magnification devices

◆ getPixelSizeAffineByID()

std::vector< double > CMMCore::getPixelSizeAffineByID	(	const char *	resolutionID	)
throw	(	CMMError
	)

Returns the Affine Transform to related camera pixels with stage movement for the requested pixel size group The raw affine transform without correction for binning and magnification will be returned.

◆ getPixelSizeConfigData()

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

Returns the configuration object for a give pixel size preset.

Returns: The configuration object

Referenced by CoreCallback::OnPropertyChanged().

◆ getPixelSizeUm() [1/2]

double CMMCore::getPixelSizeUm ( )

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

References getPixelSizeUm().

Referenced by getPixelSizeUm(), CoreCallback::OnMagnifierChanged(), and CoreCallback::OnPropertyChanged().

◆ getPixelSizeUm() [2/2]

double CMMCore::getPixelSizeUm ( bool cached )

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

For legacy reasons, an exception is not thrown if there is an error. Instead, 0.0 is returned if any property values cannot be read, or if no pixel size preset matches the property values.

References ConfigGroupBase< T >::Find(), getCurrentPixelSizeConfig(), and getMagnificationFactor().

◆ getPixelSizeUmByID()

double CMMCore::getPixelSizeUmByID	(	const char *	resolutionID	)
throw	(	CMMError
	)

Returns the pixel size in um for the requested pixel size group

◆ getPosition() [1/2]

double CMMCore::getPosition	(		)
throw	(	CMMError
	)

Returns the current position of the stage in microns. Uses the current Z positioner (focus) device.

Returns: the position in microns

References getFocusDevice(), and getPosition().

Referenced by getPosition().

◆ getPosition() [2/2]

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

Returns the current position of the stage in microns.

Returns: the position in microns

Parameters

label the single-axis drive device label

◆ getPrimaryLogFile()

std::string CMMCore::getPrimaryLogFile ( ) const

Return the name of the primary Core log file.

◆ getProperty()

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

Returns the property value for the specified device.

Returns: the property value

Parameters

label	the device label
propName	the property name

Referenced by detectDevice().

◆ getPropertyFromCache()

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

Returns the cached property value for the specified device.

Returns: the property value

Parameters

label	the device label
propName	the property name

References PropertySetting::getPropertyValue().

◆ getPropertyLowerLimit()

double CMMCore::getPropertyLowerLimit	(	const char *	label,
		const char *	propName
	)
throw	(	CMMError
	)

Returns the property lower limit value, if the property has limits - 0 otherwise.

◆ getPropertySequenceMaxLength()

long CMMCore::getPropertySequenceMaxLength	(	const char *	label,
		const char *	propName
	)
throw	(	CMMError
	)

Queries device property for the maximum number of events that can be put in a sequence

Parameters

label	the device name
propName	the property label

◆ getPropertyType()

MM::PropertyType CMMCore::getPropertyType	(	const char *	label,
		const char *	propName
	)
throw	(	CMMError
	)

Returns the intrinsic property type.

◆ getPropertyUpperLimit()

double CMMCore::getPropertyUpperLimit	(	const char *	label,
		const char *	propName
	)
throw	(	CMMError
	)

Returns the property upper limit value, if the property has limits - 0 otherwise.

◆ getRemainingImageCount()

long CMMCore::getRemainingImageCount ( )

Returns number ofimages available in the Circular Buffer

◆ getROI() [1/2]

void CMMCore::getROI	(	const char *	label,
		int &	x,
		int &	y,
		int &	xSize,
		int &	ySize
	)
throw	(	CMMError
	)

Return the current hardware region of interest for a camera. If multiple ROIs are set, this method instead returns a rectangle that describes the image that the camera will generate.

Parameters

label	camera label
x	coordinate of the top left corner
y	coordinate of the top left corner
xSize	number of horizontal pixels
ySize	number of vertical pixels

◆ getROI() [2/2]

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

Return the current hardware region of interest for a camera. If multiple ROIs are set, this method instead returns a rectangle that describes the image that the camera will generate.

The coordinates are in units of binned pixels. That is, conceptually, binning is applied before the ROI.

Parameters

x	coordinate of the top left corner
y	coordinate of the top left corner
xSize	number of horizontal pixels
ySize	number of horizontal pixels

◆ getSerialPortAnswer()

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

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

Referenced by CoreCallback::GetSerialAnswer().

◆ getShutterDevice()

std::string CMMCore::getShutterDevice ( )

Returns the label of the currently selected shutter device.

Returns: shutter name

Referenced by getShutterOpen().

◆ getShutterOpen() [1/2]

bool CMMCore::getShutterOpen	(		)
throw	(	CMMError
	)

Returns the state of the currently selected (default) shutter.

References getShutterDevice(), and getShutterOpen().

Referenced by getShutterOpen().

◆ getShutterOpen() [2/2]

bool CMMCore::getShutterOpen	(	const char *	shutterLabel	)
throw	(	CMMError
	)

Returns the state of the specified shutter.

Parameters

shutterLabel the name of the shutter

◆ getSLMBytesPerPixel()

unsigned CMMCore::getSLMBytesPerPixel	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Returns the number of bytes per SLM pixel

Parameters

deviceLabel name of the SLM

◆ getSLMDevice()

std::string CMMCore::getSLMDevice ( )

Returns the label of the currently selected SLM device.

Returns: slm name

◆ getSLMExposure()

double CMMCore::getSLMExposure	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Returns the exposure time that will be used by the SLM for illumination

◆ getSLMHeight()

unsigned CMMCore::getSLMHeight	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Returns the height (in "pixels") of the SLM

Parameters

deviceLabel name of the SLM

◆ getSLMNumberOfComponents()

unsigned CMMCore::getSLMNumberOfComponents	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Returns the number of components (usually these depict colors) of the SLM For instance, an RGB projector will return 3, but a grey scale SLM returns 1

Parameters

deviceLabel name of the SLM

◆ getSLMSequenceMaxLength()

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

For SLMs that support sequences, returns the maximum length of the sequence that can be uploaded to the device

Parameters

deviceLabel name of the SLM

◆ getSLMWidth()

unsigned CMMCore::getSLMWidth	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Returns the width (in "pixels") of the SLM

Parameters

deviceLabel name of the SLM

◆ getStageSequenceMaxLength()

long CMMCore::getStageSequenceMaxLength	(	const char *	label	)
throw	(	CMMError
	)

Gets the maximum length of a stage's position sequence. This should only be called for stages that are sequenceable

Parameters

label the stage device label

Returns: the maximum length (integer)

◆ getState()

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

Returns the current state (position) on the specific device. The command will fail if the device does not support states.

Returns: the current state

Parameters

deviceLabel the device label

◆ getStateFromLabel()

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

Obtain the state for a given label.

Returns: the state (an integer)

Parameters

deviceLabel	the device label
stateLabel	the label for which the state is being queried

◆ getStateLabel()

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

Returns the current state as the label (string).

Returns: the current state's label

Parameters

deviceLabel the device label

◆ getStateLabels()

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

Return labels for all states

Returns: an array of state labels

Parameters

deviceLabel the device label

◆ getSystemState()

Configuration CMMCore::getSystemState ( )

Returns the entire system state, i.e. the collection of all property values from all devices.

For legacy reasons, this function does not throw an exception if there is an error. If there is an error, properties may be missing from the return value.

Returns: Configuration object containing a collection of device-property-value triplets

References Configuration::addSetting().

Referenced by updateSystemStateCache().

◆ getSystemStateCache()

Configuration CMMCore::getSystemStateCache ( ) const

Returns the entire system state, i.e. the collection of all property values from all devices. This method will return cached values instead of querying each device

Returns: Configuration object containing a collection of device-property-value triplets

◆ getVersionInfo()

std::string CMMCore::getVersionInfo ( ) const

Displays core version.

◆ getXPosition() [1/2]

double CMMCore::getXPosition	(		)
throw	(	CMMError
	)

Obtains the current position of the X axis of the XY stage in microns. Uses the current XY stage device.

Returns: the x position

Parameters

label the stage device label

References getXPosition(), and getXYStageDevice().

Referenced by getXPosition().

◆ getXPosition() [2/2]

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

Obtains the current position of the X axis of the XY stage in microns.

Returns: the x position

Parameters

label the stage device label

◆ getXYPosition() [1/2]

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

Obtains the current position of the XY stage in microns.

Parameters

label	the stage device label
x	a return parameter yielding the X position in microns
y	a return parameter yielding the Y position in microns

◆ getXYPosition() [2/2]

void CMMCore::getXYPosition	(	double &	x,
		double &	y
	)
throw	(	CMMError
	)

Obtains the current position of the XY stage in microns. Uses the current XY stage device.

Parameters

x	a return parameter yielding the X position in microns
y	a return parameter yielding the Y position in microns

◆ getXYStageDevice()

std::string CMMCore::getXYStageDevice ( )

Returns the label of the currently selected XYStage device.

Referenced by getXPosition(), getYPosition(), setOriginX(), setOriginXY(), and setOriginY().

◆ getXYStageSequenceMaxLength()

long CMMCore::getXYStageSequenceMaxLength	(	const char *	label	)
throw	(	CMMError
	)

Gets the maximum length of an XY stage's position sequence. This should only be called for XY stages that are sequenceable

Parameters

label the XY stage device label

Returns: the maximum allowed sequence length

◆ getYPosition() [1/2]

double CMMCore::getYPosition	(		)
throw	(	CMMError
	)

Obtains the current position of the Y axis of the XY stage in microns. Uses the current XY stage device.

Returns: the y position

Parameters

label the stage device label

References getXYStageDevice(), and getYPosition().

Referenced by getYPosition().

◆ getYPosition() [2/2]

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

Obtains the current position of the Y axis of the XY stage in microns.

Returns: the y position

Parameters

label the stage device label

◆ hasProperty()

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

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

◆ hasPropertyLimits()

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

Queries device if the specific property has limits.

Parameters

label	the device name
propName	the property label

◆ home()

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

Perform a hardware homing operation for an XY or focus/Z stage.

Not all stages support this operation. The user should be warned before calling this method, as it can cause large stage movements, potentially resulting in collision (e.g. with an expensive objective lens).

Parameters

label the stage device label (either XY or focus/Z stage)

◆ incrementalFocus()

void CMMCore::incrementalFocus	(		)
throw	(	CMMError
	)

Performs incremental focus for the one-shot focusing device.

References getCoreErrorText(), and getDeviceName().

◆ initializeAllDevices()

void CMMCore::initializeAllDevices	(		)
throw	(	CMMError
	)

Calls Initialize() method for each loaded device. Parallel implemnetation should be faster

References isFeatureEnabled().

◆ initializeCircularBuffer()

void CMMCore::initializeCircularBuffer	(		)
throw	(	CMMError
	)

Initialize circular buffer based on the current camera settings.

References getCoreErrorText(), and getDeviceName().

◆ initializeDevice()

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

Initializes specific device.

Parameters

label the device label

Parameters

label the device to initialize

◆ isBufferOverflowed()

bool CMMCore::isBufferOverflowed ( ) const

Indicates whether the circular buffer is overflowed

◆ isConfigDefined()

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

References ConfigGroupCollection::Find().

Referenced by reset().

◆ isContinuousFocusDrive()

bool CMMCore::isContinuousFocusDrive	(	const char *	stageLabel	)
throw	(	CMMError
	)

Check if a stage has continuous focusing capability (positions can be set while continuous focus runs).

◆ isContinuousFocusEnabled()

bool CMMCore::isContinuousFocusEnabled	(		)
throw	(	CMMError
	)

Checks if the continuous focusing hardware device is ON or OFF.

References getDeviceName().

◆ isContinuousFocusLocked()

bool CMMCore::isContinuousFocusLocked	(		)
throw	(	CMMError
	)

Returns the lock-in status of the continuous focusing device.

◆ isExposureSequenceable()

bool CMMCore::isExposureSequenceable	(	const char *	cameraLabel	)
throw	(	CMMError
	)

Queries camera if exposure can be used in a sequence

Parameters

cameraLabel the camera device label

Returns: true if exposure can be sequenced

◆ isFeatureEnabled()

bool CMMCore::isFeatureEnabled	(	const char *	name	)
throw	(	CMMError
	)

static

Return whether the given Core feature is currently enabled.

See enableFeature() for the available features.

Parameters

name	the feature name.

Returns: whether the feature is enabled.

Exceptions

CMMError if the feature name is null or unknown.

Referenced by initializeAllDevices().

◆ isGroupDefined()

bool CMMCore::isGroupDefined ( const char * groupName )

Checks if the group already exists.

Returns: true if the group is already defined

References ConfigGroupCollection::isDefined().

◆ isMultiROIEnabled()

bool CMMCore::isMultiROIEnabled	(		)
throw	(	CMMError
	)

Queries the camera to determine if multiple ROIs are currently set.

References getCoreErrorText().

◆ isMultiROISupported()

bool CMMCore::isMultiROISupported	(		)
throw	(	CMMError
	)

Queries the camera to determine if it supports multiple ROIs.

References getCoreErrorText().

◆ isPixelSizeConfigDefined()

bool CMMCore::isPixelSizeConfigDefined	(	const char *	resolutionID	)	const
throw	(	CMMError
	)

Checks if the Pixel Size Resolution already exists

Returns: true if the configuration is already defined

◆ isPropertyPreInit()

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

Tells us whether the property must be defined prior to initialization.

Returns: true for pre-init property

Parameters

label	the device label
propName	the property name

◆ isPropertyReadOnly()

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

Tells us whether the property can be modified.

Returns: true for a read-only property

Parameters

label	the device label
propName	the property name

◆ isPropertySequenceable()

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

Queries device if the specified property can be used in a sequence

Parameters

label	the device name
propName	the property label

◆ isSequenceRunning() [1/2]

bool CMMCore::isSequenceRunning	(	)
throw	(
	)

Check if the current camera is acquiring the sequence Returns false when the sequence is done

◆ isSequenceRunning() [2/2]

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

Check if the specified camera is acquiring the sequence Returns false when the sequence is done

◆ isStageLinearSequenceable()

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

Queries if the stage can be used in a linear sequence A linear sequence is defined by a stepsize and number of slices

Parameters

label the stage device label

Returns: true if the stage supports linear sequences

◆ isStageSequenceable()

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

Queries stage if it can be used in a sequence

Parameters

label the stage device label

Returns: true if the stage can be sequenced

◆ isXYStageSequenceable()

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

Queries XY stage if it can be used in a sequence

Parameters

label the XY stage device label

◆ loadDevice()

void CMMCore::loadDevice	(	const char *	label,
		const char *	moduleName,
		const char *	deviceName
	)
throw	(	CMMError
	)

Loads a device from the plugin library.

Parameters

label	assigned name for the device during the core session
moduleName	the name of the device adapter module (short name, not full file name)
deviceName	the name of the device. The name must correspond to one of the names recognized by the specific plugin library.

◆ loadExposureSequence()

void CMMCore::loadExposureSequence	(	const char *	cameraLabel,
		std::vector< double >	exposureTime_ms
	)
throw	(	CMMError
	)

Transfer a sequence of exposure times to the camera. This should only be called for cameras where exposure time is sequenceable

Parameters

cameraLabel	the camera device label
exposureTime_ms	sequence of exposure times the camera will use during a sequence acquisition

◆ loadGalvoPolygons()

void CMMCore::loadGalvoPolygons	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Load a set of galvo polygons to the device

◆ loadPropertySequence()

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

Transfer a sequence of events/states/whatever to the device This should only be called for device-properties that are sequenceable

Parameters

label	the device name
propName	the property label
eventSequence	the sequence of events/states that the device will execute in response to external triggers

◆ loadSLMSequence()

void CMMCore::loadSLMSequence	(	const char *	deviceLabel,
		std::vector< unsigned char * >	imageSequence
	)
throw	(	CMMError
	)

Load a sequence of images into the SLM

Parameters

deviceLabel	name of the SLM
imagesequence	pointers to the images to be used in the sequence

◆ loadStageSequence()

void CMMCore::loadStageSequence	(	const char *	label,
		std::vector< double >	positionSequence
	)
throw	(	CMMError
	)

Transfer a sequence of events/states/whatever to the device This should only be called for device-properties that are sequenceable

Parameters

label	the device label
positionSequence	a sequence of positions that the stage will execute in response to external triggers

◆ loadSystemConfiguration()

void CMMCore::loadSystemConfiguration	(	const char *	fileName	)
throw	(	CMMError
	)

Loads the system configuration from the text file conforming to the MM specific format. The configuration contains a list of commands to build the desired system state: devices, labels, properties, and configurations.

Format specification: Each line consists of a number of string fields separated by "," (comma) characters. Lines beginning with "#" are ignored (can be used for comments). Each line in the file will be parsed by the system and as a result a corresponding command will be immediately executed. The first field in the line always specifies the command from the following set of values: Device - executes loadDevice() Label - executes defineStateLabel() command Property - executes setPropertyCommand() Configuration - ignored for backward compatibility

The remaining fields in the line will be used for corresponding command parameters. The number of parameters depends on the actual command used.

References CMMError::getFullMsg().

◆ loadSystemState()

void CMMCore::loadSystemState	(	const char *	fileName	)
throw	(	CMMError
	)

Loads the system configuration from the text file conforming to the MM specific format. The configuration contains a list of commands to build the desired system state from read-write properties.

Format specification: the same as in loadSystemConfiguration() command

◆ loadXYStageSequence()

void CMMCore::loadXYStageSequence	(	const char *	label,
		std::vector< double >	xSequence,
		std::vector< double >	ySequence
	)
throw	(	CMMError
	)

Transfer a sequence of stage positions to the xy stage. xSequence and ySequence must have the same length. This should only be called for XY stages that are sequenceable

Parameters

label	the XY stage device label
xSequence	the sequence of x positions that the stage will execute in response to external triggers
ySequence	the sequence of y positions that the stage will execute in response to external triggers

◆ logMessage() [1/2]

void CMMCore::logMessage ( const char * msg )

Record text message in the log file.

◆ logMessage() [2/2]

void CMMCore::logMessage	(	const char *	msg,
		bool	debugOnly
	)

Record text message in the log file.

◆ noop()

static void CMMCore::noop ( )

inlinestatic

A static method that does nothing.

This method can be called as a sanity check when dynamically loading the Core library (e.g. through a foreign function interface for a high-level language).

◆ pointGalvoAndFire()

void CMMCore::pointGalvoAndFire	(	const char *	deviceLabel,
		double	x,
		double	y,
		double	pulseTime_us
	)
throw	(	CMMError
	)

Set the Galvo to an x,y position and fire the laser for a predetermined duration.

◆ popNextImage()

void * CMMCore::popNextImage	(		)
throw	(	CMMError
	)

Gets and removes the next image from the circular buffer. Returns 0 if the buffer is empty.

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 the format is BGRA888 (see: https://en.wikipedia.org/wiki/RGBA_color_model).

References getCoreErrorText().

◆ popNextImageMD() [1/2]

void * CMMCore::popNextImageMD	(	Metadata &	md	)
throw	(	CMMError
	)

Gets and removes the next image (and metadata) from the circular buffer

◆ popNextImageMD() [2/2]

void * CMMCore::popNextImageMD	(	unsigned	channel,
		unsigned	slice,
		Metadata &	md
	)
throw	(	CMMError
	)

Gets and removes the next image (and metadata) from the circular buffer channel indicates which cameraChannel image should be retrieved. slice has not been implement and should always be 0

◆ prepareSequenceAcquisition()

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

Prepare the camera for the sequence acquisition to save the time in the StartSequenceAcqusition() call which is supposed to come next.

◆ readFromSerialPort()

std::vector< char > CMMCore::readFromSerialPort	(	const char *	portLabel	)
throw	(	CMMError
	)

Reads the contents of the Rx buffer.

◆ registerCallback()

void CMMCore::registerCallback ( MMEventCallback * cb )

Register a callback (listener class). MMCore will send notifications on internal events using this interface

◆ renameConfig()

void CMMCore::renameConfig	(	const char *	groupName,
		const char *	oldConfigName,
		const char *	newConfigName
	)
throw	(	CMMError
	)

Renames a configuration within a specified group. The command will fail if the configuration was not previously defined.

◆ renameConfigGroup()

void CMMCore::renameConfigGroup	(	const char *	oldGroupName,
		const char *	newGroupName
	)
throw	(	CMMError
	)

Renames a configuration group.

◆ renamePixelSizeConfig()

void CMMCore::renamePixelSizeConfig	(	const char *	oldConfigName,
		const char *	newConfigName
	)
throw	(	CMMError
	)

Renames a pixel size configuration. The command will fail if the configuration was not previously defined.

◆ reset()

void CMMCore::reset	(		)
throw	(	CMMError
	)

Unloads all devices from the core, clears all configuration data.

References isConfigDefined(), setConfig(), unloadAllDevices(), and waitForSystem().

Referenced by ~CMMCore().

◆ runGalvoPolygons()

void CMMCore::runGalvoPolygons	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Run a loop of galvo polygons

◆ runGalvoSequence()

void CMMCore::runGalvoSequence	(	const char *	deviceLabel	)
throw	(	CMMError
	)

Run a sequence of galvo positions

◆ saveSystemConfiguration()

void CMMCore::saveSystemConfiguration	(	const char *	fileName	)
throw	(	CMMError
	)

Saves the current system configuration to a text file of the MM specific format. The configuration file records only the information essential to the hardware setup: devices, labels, pre-initialization properties, and configurations. The file format is the same as for the system state.

References PropertySetting::getDeviceLabel(), PropertySetting::getPropertyName(), PropertySetting::getPropertyValue(), Configuration::getSetting(), and Configuration::size().

◆ saveSystemState()

void CMMCore::saveSystemState	(	const char *	fileName	)
throw	(	CMMError
	)

Saves the current system state to a text file of the MM specific format. The file records only read-write properties. The file format is directly readable by the complementary loadSystemState() command.

References PropertySetting::getDeviceLabel(), PropertySetting::getPropertyName(), PropertySetting::getPropertyValue(), Configuration::getSetting(), and Configuration::size().

◆ setAdapterOrigin() [1/2]

void CMMCore::setAdapterOrigin	(	const char *	label,
		double	newZUm
	)
throw	(	CMMError
	)

Enable software translation of coordinates for the given focus/Z stage.

The current position of the stage becomes Z = newZUm. Only some stages support this functionality; it is recommended that setOrigin() be used instead where available.

Parameters

label	the stage device label
newZUm	the new coordinate to assign to the current Z position

◆ setAdapterOrigin() [2/2]

void CMMCore::setAdapterOrigin	(	double	newZUm	)
throw	(	CMMError
	)

Enable software translation of coordinates for the current focus/Z stage.

The current position of the stage becomes Z = newZUm. Only some stages support this functionality; it is recommended that setOrigin() be used instead where available.

Parameters

newZUm the new coordinate to assign to the current Z position

◆ setAdapterOriginXY() [1/2]

void CMMCore::setAdapterOriginXY	(	const char *	label,
		double	newXUm,
		double	newYUm
	)
throw	(	CMMError
	)

Enable software translation of coordinates for the given XY stage.

The current position of the stage becomes (newXUm, newYUm). It is recommended that setOriginXY() be used instead where available.

Parameters

label	the XY stage device label
newXUm	the new coordinate to assign to the current X position
newYUm	the new coordinate to assign to the current Y position

◆ setAdapterOriginXY() [2/2]

void CMMCore::setAdapterOriginXY	(	double	newXUm,
		double	newYUm
	)
throw	(	CMMError
	)

Enable software translation of coordinates for the current XY stage.

The current position of the stage becomes (newXUm, newYUm). It is recommended that setOriginXY() be used instead where available.

Parameters

newXUm	the new coordinate to assign to the current X position
newYUm	the new coordinate to assign to the current Y position

◆ setAutoFocusDevice()

void CMMCore::setAutoFocusDevice	(	const char *	autofocusLabel	)
throw	(	CMMError
	)

Sets the current auto-focus device.

◆ setAutoFocusOffset()

void CMMCore::setAutoFocusOffset	(	double	offset	)
throw	(	CMMError
	)

Applies offset the one-shot focusing device.

◆ setAutoShutter()

void CMMCore::setAutoShutter ( bool state )

If this option is enabled Shutter automatically opens and closes when the image is acquired.

Parameters

state true for enabled

References Configuration::addSetting().

◆ setCameraDevice()

void CMMCore::setCameraDevice	(	const char *	cameraLabel	)
throw	(	CMMError
	)

Sets the current camera device.

Parameters

camera the camera device label

◆ setChannelGroup()

void CMMCore::setChannelGroup	(	const char *	chGroup	)
throw	(	CMMError
	)

Specifies the group determining the channel selection.

◆ setCircularBufferMemoryFootprint()

void CMMCore::setCircularBufferMemoryFootprint	(	unsigned	sizeMB	)
throw	(	CMMError
	)

Reserve memory for the circular buffer.

Parameters

sizeMB n megabytes

◆ setConfig()

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

Applies a configuration to a group. The command will fail if the configuration was not previously defined.

Parameters

groupName	the configuration group name
configName	the configuration preset name

Referenced by reset().

◆ setDeviceAdapterSearchPaths()

void CMMCore::setDeviceAdapterSearchPaths ( const std::vector< std::string > & paths )

Set the device adapter search paths.

Upon subsequent attempts to load device adapters, these paths (and only these paths) will be searched. Calling this function has no effect on device adapters that have already been loaded.

If you want to simply add to the list of paths, you must first retrieve the current paths by calling getDeviceAdapterSearchPaths().

Parameters

paths the device adapter search paths

◆ setDeviceDelayMs()

void CMMCore::setDeviceDelayMs	(	const char *	label,
		double	delayMs
	)
throw	(	CMMError
	)

Overrides the built-in value for the action delay. Some devices ignore this setting.

Parameters

label	the device label
delayMs	the desired delay in milliseconds

◆ setExposure() [1/2]

void CMMCore::setExposure	(	const char *	label,
		double	dExp
	)
throw	(	CMMError
	)

Sets the exposure setting of the specified camera in milliseconds.

Parameters

label	the camera device label
dExp	the exposure in milliseconds

◆ setExposure() [2/2]

void CMMCore::setExposure	(	double	dExp	)
throw	(	CMMError
	)

Sets the exposure setting of the current camera in milliseconds.

Parameters

dExp	the exposure in milliseconds

◆ setFocusDevice()

void CMMCore::setFocusDevice	(	const char *	focusLabel	)
throw	(	CMMError
	)

Sets the current focus device.

Parameters

focus the focus stage device label

◆ setFocusDirection()

void CMMCore::setFocusDirection	(	const char *	stageLabel,
		int	sign
	)

Set the focus direction of a stage.

The sign should be +1 (or any positive value), zero, or -1 (or any negative value), and is interpreted in the same way as the return value of getFocusDirection().

Once this method is called, getFocusDirection() for the stage will always return the set value.

For legacy reasons, an exception is not thrown if there is an error. Instead, nothing is done if stageLabel is not a valid focus stage.

◆ setGalvoDevice()

void CMMCore::setGalvoDevice	(	const char *	galvoLabel	)
throw	(	CMMError
	)

Sets the current galvo device.

◆ setGalvoIlluminationState()

void CMMCore::setGalvoIlluminationState	(	const char *	deviceLabel,
		bool	on
	)
throw	(	CMMError
	)

Set the galvo's illumination state to on or off

◆ setGalvoPolygonRepetitions()

void CMMCore::setGalvoPolygonRepetitions	(	const char *	deviceLabel,
		int	repetitions
	)
throw	(	CMMError
	)

Set the number of times to loop galvo polygons

◆ setGalvoPosition()

void CMMCore::setGalvoPosition	(	const char *	deviceLabel,
		double	x,
		double	y
	)
throw	(	CMMError
	)

Set the Galvo to an x,y position

◆ setImageProcessorDevice()

void CMMCore::setImageProcessorDevice	(	const char *	procLabel	)
throw	(	CMMError
	)

Sets the current image processor device.

◆ setMultiROI()

void CMMCore::setMultiROI	(	std::vector< unsigned >	xs,
		std::vector< unsigned >	ys,
		std::vector< unsigned >	widths,
		std::vector< unsigned >	heights
	)
throw	(	CMMError
	)

Set multiple ROIs for the current camera device. Will fail if the camera does not support multiple ROIs, any widths or heights are non-positive, or if the vectors do not all have the same length.

Parameters

xs	X indices for the upper-left corners of each ROI.
ys	Y indices for the upper-left corners of each ROI.
widths	Width in pixels for each ROI.
heights	Height in pixels for each ROI.

◆ setOrigin() [1/2]

void CMMCore::setOrigin	(		)
throw	(	CMMError
	)

Zero the current focus/Z stage's coordinates at the current position.

The current position becomes the new origin (Z = 0). Not to be confused with setAdapterOrigin().

References getFocusDevice(), and setOrigin().

Referenced by setOrigin().

◆ setOrigin() [2/2]

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

Zero the given focus/Z stage's coordinates at the current position.

The current position becomes the new origin (Z = 0). Not to be confused with setAdapterOrigin().

Parameters

label the stage device label

◆ setOriginX() [1/2]

void CMMCore::setOriginX	(		)
throw	(	CMMError
	)

Zero the given XY stage's X coordinate at the current position.

The current position becomes the new X = 0.

References getXYStageDevice(), and setOriginX().

Referenced by setOriginX().

◆ setOriginX() [2/2]

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

Zero the given XY stage's X coordinate at the current position.

The current position becomes the new X = 0.

Parameters

label the xy stage device label

◆ setOriginXY() [1/2]

void CMMCore::setOriginXY	(		)
throw	(	CMMError
	)

Zero the current XY stage's coordinates at the current position.

The current position becomes the new origin. Not to be confused with setAdapterOriginXY().

References getXYStageDevice(), and setOriginXY().

Referenced by setOriginXY().

◆ setOriginXY() [2/2]

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

Zero the given XY stage's coordinates at the current position.

The current position becomes the new origin. Not to be confused with setAdapterOriginXY().

Parameters

label the stage device label

◆ setOriginY() [1/2]

void CMMCore::setOriginY	(		)
throw	(	CMMError
	)

Zero the given XY stage's Y coordinate at the current position.

The current position becomes the new Y = 0.

References getXYStageDevice(), and setOriginY().

Referenced by setOriginY().

◆ setOriginY() [2/2]

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

Zero the given XY stage's Y coordinate at the current position.

The current position becomes the new Y = 0.

Parameters

label the xy stage device label

◆ setParentLabel()

void CMMCore::setParentLabel	(	const char *	label,
		const char *	parentLabel
	)
throw	(	CMMError
	)

Sets parent device label

◆ setPixelSizeAffine()

void CMMCore::setPixelSizeAffine	(	const char *	resolutionID,
		std::vector< double >	affine
	)
throw	(	CMMError
	)

Sets the raw affine transform for the specific pixel size configuration The affine transform consists of the first two rows of a 3x3 matrix, the third row is alsways assumed to be 0.0 0.0 1.0. The transform should be valid for binning 1 and no magnification device (as given by the getMagnification() function). Order: row[0]col[0] row[0]c[1] row[0]c[2] row[1]c[0] row[1]c[1] row[1]c[2] The given vector has to have 6 doubles, or bad stuff will happen

◆ setPixelSizeConfig()

void CMMCore::setPixelSizeConfig	(	const char *	resolutionID	)
throw	(	CMMError
	)

Applies a Pixel Size Configuration. The command will fail if the configuration was not previously defined.

Parameters

groupName	the configuration group name
configName	the configuration preset name

References CMMError::getCode().

◆ setPixelSizeUm()

void CMMCore::setPixelSizeUm	(	const char *	resolutionID,
		double	pixSize
	)
throw	(	CMMError
	)

Sets pixel size in microns for the specified resolution sensing configuration preset.

◆ setPosition() [1/2]

void CMMCore::setPosition	(	const char *	label,
		double	position
	)
throw	(	CMMError
	)

Sets the position of the stage in microns.

Parameters

label	the stage device label
position	the desired stage position, in microns

◆ setPosition() [2/2]

void CMMCore::setPosition	(	double	position	)
throw	(	CMMError
	)

Sets the position of the stage in microns. Uses the current Z positioner (focus) device.

Parameters

position the desired stage position, in microns

◆ setPrimaryLogFile()

void CMMCore::setPrimaryLogFile	(	const char *	filename,
		bool	truncate = `false`
	)
throw	(	CMMError
	)

Set the primary Core log file.

Parameters

filename The log filename. If empty or null, the primary log file is disabled.