Microscope Commands Documentation

Microscope Control Software version 3.0.1.65

JSON command protocol
TCP/IP port: 16951
Message format: message length (4 bytes, int32) followed by JSON message

Field	Type/Value	Description	Required	Default
Common for all components
Common	command	Represent a command that can be executed on a source.
ComponentName	string	Name of the component to which command is addressed.	Yes
CommandName	string	Name of the command.	Yes
	response
Success	bool	Indicates if command was successful.	Yes
ErrorMessage	string	Error message describing command error.	Yes
Time	double?	Time in ms it took to execute command or null if unknown.	Yes

Ping	command	Ping to check that component is able to receive commands.
	response

Common for all devices
Connect	command	Connect microscope to the device.
	response

Disconnect	command	Disconnect microscope from device.
	response

Ping	command	Ping to check that component is able to receive commands.
	response

WaitReady	command	Wait for a device to be ready.
	response

AcquisitionController
Acquire	command	Generate acquisition controller signals.
IlluminationSettings	string	Name of the illumination settings to use.	Yes
ExposureSettings	string	Name of the exposure settings to use.	Yes
	response

GetTiltFactors	command	Get the tilt factors associated with the current objective block.
	response
Illumin1TiltFactor	double	The factor of scanner 1 to tilt the scan plane for illumination 1.	Yes
Illumin2TiltFactor	double	The factor of scanner 1 to tilt the scan plane for illumination 2.	Yes

SaveTiltFactors	command	Save the tilt factors associated with the current objective block to persistent storage.
	response

SetTiltFactors	command	Set the tilt factors associated with the current objective block.
Illumin1TiltFactor	double?	The new factor of scanner 1 to tilt the scan plane for illumination 1 or null to keep the current value.	No	null
Illumin2TiltFactor	double?	The new factor of scanner 1 to tilt the scan plane for illumination 2 or null to keep the current value.	No	null
	response

Camera
DisplayedViewSet	command	Set the displayed view in image viewer.
View	int	The index of the view to display, one based.	Yes
	response

GetSensorInfo	command	Get sensor information.
	response
Width	int	Width of the sensor in pixels.	Yes
Height	int	Height of the sensor in pixels.	Yes
Temperature	double?	Current temperature of the sensor in degree Celsius if available.	No	null

ImageGet	command	Get image from the camera buffer.
Plane	int	Plane to get (1 based).	No	1
ChannelIndex	int	Index of channel to get (1 based).	No	1
ViewIndex	int	Index of View to get (1 based).	No	1
Top	int?	Index of top most pixel to get (0 based), null to center.	No	null
Left	int?	Index of left most pixel to get (0 based), null to center.	No	null
Width	int?	Width of the image in pixels or null to get full width.	No	null
Height	int?	Height of the image in pixels or null to get full height.	No	null
	response
Width	int	Width of the image.	Yes
Height	int	Height of the image.	Yes
ImageData	string	Image data represented in base64 encoding.	Yes

ImageInfoGet	command	Get info on imaging setup.
	response
Width	int	Width of the image in pixels.	Yes
Height	int	Height of the image in pixels.	Yes
Planes	int	Number of planes.	Yes
Channels	int	Number of channels.	Yes
Views	int	Number of views.	Yes
Position	string	Name of position (or null if not known).	Yes
Settings	string	Name of settings.	Yes
TimePoint	int?	Time point starting at 1.	Yes
VoxelX	double?	Size of Voxel X in um.	Yes
VoxelY	double?	Size of Voxel Y in um.	Yes
VoxelZ	double?	Size of Voxel Z in um (or null if no stack).	Yes
NumericalAperture	double	Numerical aperture of objective.	Yes

OffsetGet	command	Get offset between camera views.
	response
OffsetX	int	The offset between views along X-axis.	Yes
OffsetY	int	The offset between views along Y-axis.	Yes

OffsetSet	command	Set the offset between camera views.
OffsetX	int	The offset between views along X-axis.	Yes
OffsetY	int	The offset between views along Y-axis.	Yes
	response

FilterWheel
Move	command	Move filter wheel to specified filter.
FilterName	string	Name of the filter settings to move device to.	Yes
Force	bool	Whether to force the filter wheel to move (even if already at correct position).	No	false
	response

MoveTo	command	Move filter wheel to specified position.
Position	int	Position to move the device to.	Yes
Force	bool	Whether to force the filter wheel to move (even if already at correct position).	No	false
	response

IlluminationModule
CurrentIlluminationGet	command	Get values currently applied on the hardware.
	response
Name	string	Name of illumination settings.	Yes
TranslationX	double	The translation along X-axis in um.	Yes
RotationX	double	The rotation along X-axis in degrees.	Yes
TranslationZ	double	The translation along Z-axis in um.	Yes
RotationZ	double	The rotation along Z-axis in degrees.	Yes

GetIlluminationList	command	Get the list of illumination settings.
	response
Names	list of string	The names of the illumination settings.	Yes

GetObjectiveBlockAlignment	command	Get the objective block alignment associated with the current immersion medium.
Name	string	Name of the illumination settings to get.	Yes
	response
Name	string	Name of illumination settings.	Yes
ImmersionMedium	string	The name of the immersion medium.	Yes
TranslationX	double	The translation along X-axis in um.	Yes
RotationX	double	The rotation along X-axis in degrees.	Yes
TranslationZ	double	The translation along Z-axis in um.	Yes
RotationZ	double	The rotation along Z-axis in degrees.	Yes

IlluminationGet	command	Get current illumination settings.
Name	string	Name of the illumination settings to get.	Yes
	response
Name	string	Name of illumination settings.	Yes
TranslationX	double	The translation along X-axis in um.	Yes
RotationX	double	The rotation along X-axis in degrees.	Yes
TranslationZ	double	The translation along Z-axis in um.	Yes
RotationZ	double	The rotation along Z-axis in degrees.	Yes

IlluminationSet	command	Set the illumination settings.
Name	string	Name of the illumination settings to set.	Yes
TranslationX	double?	The translation along X-axis or null to keep original value.	No	null
RotationX	double?	The rotation along X-axis or null to keep original value.	No	null
TranslationZ	double?	The translation along Z-axis or null to keep original value.	No	null
RotationZ	double?	The rotation along Z-axis or null to keep original value.	No	null
SetDevice	bool	Whether to apply the new settings on device.	No	false
	response

OffsetBaseGet	command	Get base offset values.
	response

OffsetsBaseSet	command	Set base offsets, all current settings are overwritten.
OffsetsBase	list of dict	The list of base offsets. Keys of dict listed below.	Yes
Branch	int	Unique number of illumination branch (value 1, 2 or 3).	Yes
Scanner1Offset	double	Voltage on scanner 1.	Yes
Scanner2Offset	double	Voltage on scanner 2.	Yes
Scanner3Offset	double	Voltage on scanner 3.	Yes
Scanner4Offset	double	Voltage on scanner 4.	Yes
	response

PositionAlignmentGet	command	Get position specific Z-alignment.
Name	string	Name of the position alignment settings to get.	Yes
	response
Name	string	Name of the position.	Yes
TranslationZ	double	Translation along Z-axis.	Yes
Enable	bool	Whether the alignment is applied.	Yes

PositionAlignmentSet	command	Set position specific Z-alignment and enable the position.
Name	string	Name of the position alignment settings to set.	Yes
TranslationZ	double?	Translation along Z-axis to set or null to keep original value.	No	null
Enable	bool?	Enable to set or null to keep original value.	No	null
	response

SetObjectiveBlockAlignment	command	Set the objective block alignment associated with the current immersion medium. The modified alignment are not persistent, unless the update command is also sent.
Name	string	Name of the illumination settings to set.	Yes
TranslationX	double?	The translation in X in um to apply. If null, keep the current value.	No	null
RotationX	double?	The rotation in X in degrees to apply. If null, keep the current value.	No	null
TranslationZ	double?	The translation in Z in um to apply. If null, keep the current value.	No	null
RotationZ	double?	The rotation in Z in degrees to apply. If null, keep the current value.	No	null
	response

UpdateObjectiveBlockAlignment	command	Update the objective block alignment associated with the current immersion medium based on the current alignment of the given illumination. The updated alignment are persistent.
IlluminationName	string	Name of the illumination settings to update, if null, update all illuminations.	No	null
	response

System
Authenticate	command	Authenticate to the system with a secret key to start a session.
AuthenticationSecretKey	string	The authentication secret key. Software must have been started once to generate this key.	Yes
	response

GetComponentList	command	Get a list of names and types of components connected to the microscope.
	response
ComponentNames	list of string	List of component names.	Yes
ComponentTypes	list of string	List of component types.	Yes

GetComponentType	command	Get the type of a component.
QueryComponentName	string	The name of the component to get the type for.	Yes
	response
ComponentType	string	Type of the component.	Yes

ObjectiveBlock
GetObjectiveBlockInfo	command	Get the current information about the objective block.
	response
ObjectiveBlock	string	The name of the objective block currently used.	Yes
Objective	string	The name of the objective used.	Yes
IsMultiImmersion	bool	Whether the objective supports multiple immersion media.	Yes
Views	enum	The available views for the current objective. Possible values listed below.	Yes
View1	string	View 1	-
View2	string	View 2	-
View1And2	string	View 1 and 2	-
IlluminationMagnification	double	The effective magnification of the illumination objective, taking into account the current immersion medium refractive index.	Yes
DetectionMagnification	double	The effective magnification of the detection objective, taking into account the current immersion medium refractive index.	Yes
DetectionNumericalAperture	double	The effective numerical aperture of the detection objective, taking into account the current immersion medium refractive index.	Yes
ImmersionMedium	string	The current immersion medium.	Yes
RefractiveIndex	double	The refractive index of the current immersion medium.	Yes

SetShading	command	Set the shading information for the current immersion medium.
ShadingCorrectionFactors	list of dict	The shading correction factors for each view. The factors allow the reconstruction of a polynomial function that maps the measured intensity to the corrected intensity. Keys of dict listed below.	Yes
C	double	The constant term.	Yes
HL	double	The horizontal linear coefficient.	Yes
VL	double	The vertical linear coefficient.	Yes
TQ	double	The tilted quadratic coefficient.	Yes
HQ	double	The horizontal quadratic coefficient.	Yes
VQ	double	The vertical quadratic coefficient.	Yes
	response

Photomanipulation
OffsetsBaseGet	command	Get base offset values from photomanipulation laser.
	response
OffsetsBase	dict	The base offsets. Keys of dict listed below.	Yes
Scanner1Offset	double	Voltage on scanner 1 (closest to scan lens).	Yes
Scanner2Offset	double	Voltage on scanner 2.	Yes
Scanner3Offset	double	Voltage on scanner 3.	Yes
Scanner4Offset	double	Voltage on scanner 4 (furthest from scan lens).	Yes

OffsetsBaseSet	command	Set base offsets for photomanipulation laser, all current settings are overwritten.
OffsetsBase	dict	The baser offsets. Keys of dict listed below.	Yes
Scanner1Offset	double	Voltage on scanner 1 (closest to scan lens).	Yes
Scanner2Offset	double	Voltage on scanner 2.	Yes
Scanner3Offset	double	Voltage on scanner 3.	Yes
Scanner4Offset	double	Voltage on scanner 4 (furthest from scan lens).	Yes
	response

StageXYZ
ForgetCurrentPosition	command	Make stage forget position name on which it's located.
	response

GetCoordinates	command	Get current coordinates of the stage.
	response
Coordinates	list of 3 doubles	The current coordinates of the stage.	Yes

Move	command	Move stage to a position.
Name	string	Name of the position settings.	Yes
ZStackName	string	Name of the Z-stack settings to use or null to move to center.	No	null
Plane	int?	Plane of the Z-stack to move to or null to move to center.	No	null
Offset	list of 3 doubles?	List of relative X, Y, Z offsets to add to the position.	No	null
	response

MoveTo	command	Move stage to specified position.
Coordinates	list of 3 doubles	The target coordinates to move to.	Yes
MoveOrder	string	The order in which to move the axes (e.g., "XYZ", "XZY").	No	"XYZ"
	response

PositionGet	command	Get position settings.
Name	string	Name of the position settings.	Yes
	response
Name	string	Name of the position.	Yes
PositionX	double	Position on X-axis.	Yes
PositionY	double	Position on Y-axis.	Yes
PositionZ	double	Position on Z-axis.	Yes
SkipPosition	bool	Whether the position is skipped.	Yes

PositionNamesGet	command	Get a list of position names.
	response
Names	list of string	List of position names.	Yes

PositionSet	command	Set position settings.
Name	string	Name of the position settings to set.	Yes
PositionX	double?	Position on X-axis to set or null to keep original value.	No	null
PositionY	double?	Position on Y-axis to set or null to keep original value.	No	null
PositionZ	double?	Position on Z-axis to set or null to keep original value.	No	null
SkipPosition	bool?	Whether to skip the position or null to keep original value.	No	null
	response

TimeLapseController
ContinueFromPause	command	Continue from pause after a position.
	response

NoPauseAfterPosition	command	Disable pause after every position has been acquired.
	response

PauseAfterPosition	command	Ask time-lapse to pause after each position has been acquired.
	response

Snap	command	Snap an image.
Illumination1	bool?	If not null override user settings and enable or disable illumination 1.	No	null
Illumination2	bool?	If not null override user settings and enable or disable illumination 2.	No	null
ExposureTime	int?	If not null override user settings and set the exposure time in milliseconds.	No	null
ScanRange	int?	If not null override user settings and set the scan range in micrometers.	No	null
ScanFullFOV	bool?	If not null override user settings and set whether to scan the full field of view.	No	null
Views	enum?	If not null override user settings and set the view(s) to acquire. Possible values listed below.	No	null
View1	string	View 1	-
View2	string	View 2	-
View1And2	string	View 1 and 2	-
SettableDeviceSettings	dict (string => string)	If not null override user settings and set the defined settable device.	No	null
Fast	bool	Whether to bypass setting of settable devices (for example filter wheels will not move to defined settings).	No	false
	response

Start	command	Start a time-lapse.
	response

Stop	command	Stop time-lapse.
	response

WaitForPause	command	Wait until time-lapse controller is paused after a position.
Timeout	int	Waiting timeout in ms, -1 to wait indefinitely.	No	-1
	response
Position	string	Position which was paused.	Yes
TimePoint	int	Time point which was paused.	Yes
Timeout	bool	True if timeout, if paused false	Yes