Dave Mitchell's DigitalMicrograph™ Scripting Website

Microscope Commands

Gatan have provided a series of generic commands for interacting with microscopes. There are also instrument specific commands which may work. For example, I have written a large number of scripts for communicating with JEOL 2000FXII and 2010 instruments via a serial interface (eg 'Save JEOL Microscope Configuration'). These scripts worked by simply sending JEOL commands to the microscope via the serial interface. These are the same commands that you can type directly into the microscope (up to about JEM-2011 vintage). The JEOL command language is rather arcane, and of course serial communications are notoriously unreliable. Fortunately, modern microscopes (eg JEOL 1400, 2100, 2200) communicate via ethernet and the high level Gatan generic commands are handled by the communications interface with the specific microscope. You need this interface working before these commands will work. If your DigitalMicrograph system sources such things as magnification automatically, then you have working communications. In principal, using these generic commands should be straightforward. Since Gatan support them, you should find they continue to work through software updates. If you can possibly use the generic commands in preference to the instrument specific ones, please do so.

For an example of the use of EM commands, see my TEM Control script. I have used these EM commands on a modern JEOL 2100 with ethernet communication. I found I didn't need to bother with any of the communication set up/close functions or with the prepare commands. It may be that these are necessary for systems using Serial communication only. Try using the EM functions without invoking these in the first instance to see if it works. A Faux Microscope Library containing all the GMS 2.x microscope control commands has been created. Install this library to allow the initial development of microscope-control scripts offline. The library contains a listing of all the microscope control functions available making it a useful reference during offline script development. A listing of the commands also follows.

 

DigiScan Commands

DigiScan commands have been assembled into a convenient library script called Faux DigiScan Library. By installing this script onto an offline system as a library, you will be able to develop code to talk to a DigiScan, without errors being reported. This enables early development of scripts to be done offline, to get the basic framework, function and layout working. The script can then be moved to a microscope-based version of DigitalMicrograph (with a DigiScan attached), to adjust the final operation of the script. This greatly reduces the amount of microscope time the developer needs, to get a working script. The script library also contains extensive notes on what the various DigiScan functions do, making it a useful reference during development.

 

Imaging Filter Commands

A Faux Imaging Filter Library has been created. This contains a listing of all the GIF-based functions available, making it a useful reference for script development. When installed as a library, it permits the initial development of GIF-based scripts to be done on an offline installation of DigitalMicrograph. The script under development need only be moved to the microscope for final testing and tuning.

 

CL Commands

A CL Library has been created. This contains a listing of all the CL-based functions available, making it a useful reference for script development. When installed as a library, it permits the initial development of Gatan Cathodoluminescence-based scripts to be done on an offline installation of DigitalMicrograph. The script under development need only be moved to the microscope for final testing and tuning.

 

Generic (Gatan supported) EM Commands (GMS 1.x)

I am indebted to Phil Ahrenkiel, Gareth Vaughn, Christoph Gammer and others for expanding my original list quite significantly.This list now looks like a useful set of tools. Note double refers to a two-byte number variable. Where variables are referred to as just 'number' these too may be double precision, but I have not tested this. The same applies to number variables described as long - the lack of consistency reflects the varied sources of this information. An * denotes a variable passed into the function eg in the various 'get' functions where the passed in variable has the relevant value assigned to it ie this is a variable not a direct numeric value such as 42 (which is, after all, the answer to life, the universe and everything). In the 'set' functions either a variable can be provided which contains the value, or a direct numeric value can be supplied to set the value. This notation is not used consistently below - so use context as a guide). If you discover any more EM commands, please let me know, and I'll keep this list updated. The support status of these commands by Gatan is not clear, so functions may change or stop working when software gets updated - but probably not.

Focus

void EMSetFocus( long focus )
long EMGetFocus( void )
void EMChangeFocus(number df)            //Change the focus by df

Magnification

number EMGetMagIndex()
EMSetMagIndex(number index)

EMGetMagnification( void )
void EMSetMagnification( double mag )
Boolean EMGetMagnification( float *mag )
Boolean EMCanGetMagnification()
Boolean EMCanGetMagnification( Boolean *can )
number EMGetMagnification(void)

Brightness

void EMSetBrightness( long brightness )
long EMGetBrightness( void )

Spot Size

number EMGetSpotSize(void)    ; // Spot Size-1
void EMSetSpotSize(number nSpot)            //nSpot=SpotSize-1

Tilt

void EMPrepareTilt( )
void EMChangeTilt(number x,number y)            //Change the tilt by x,y
void EMSetBeamTilt( long tiltX, long tiltY )
void EMGetBeamTilt( long *tiltX, long *tiltY )

Shift

void EMPrepareImageShift( )
void EMPrepareShift( )
void EMImageShift(number x,number y)            //Shift the image by x,y.
void EMBeamShift( number x,number y)            //Shift the beam by x, y

void EMSetImageShift( long shiftX, long shiftY )
void EMGetImageShift( long *shiftX, long *shiftY )
void EMSetBeamShift( long shiftX, long shiftY )
void EMGetBeamShift( long *shiftX, long *shiftY )

Camera Length

void EMSetCameraLength( double cam )
double EMGetCameraLength( void )
Boolean EMCanGetCameraLength( void)

High Tension

void EMSetBeamEnergy( double beamEnergy )
void EMGetHighTensionOffsetRange( double *minVal, double *maxVal )
void EMSetHighTensionOffset( double offset )
double EMGetHighTensionOffset( void )

void EMSetHighTensionOffsetEnabled( Boolean )
Boolean EMGetHighTensionOffsetEnabled( void )
threadsafe Boolean EMHasHighTensionOffset( void )
double EMGetHighTension( void )
Boolean EMCanGetHighTension( void )

Stage

EMStopStage()
void EMSetStagePositions(long axisFlags, double x, double y, double z, double a, double b)
void EMGetStagePositions(long axisFlags, double *x, double *y, double *z, double *a, double *b)
number EMGetStageXY(double x, double y)
void EMSetStageXY(double x, double y

double EMGetStageX(void)            //um
double EMGetStageY(void)            //um
number EMGetStageZ(void)            //um

void EMSetStageX(number X)            //um
void EMSetStageY(number Y)            //um
void EMSetStageZ(number Z)            //um

number EMGetStageAlpha(void)            //deg
number EMGetStageBeta(void)            //deg
void EMSetStagealpha(double a)
void EMSetStageBeta(double b)

Stigmation

void EMPrepareStigmation( )
void EMChangeStigmation(number x,number y)// Change the stigmation by x, y.

EMGetObjectiveStigmation(number stigX, number stigY)
EMSetObjectiveStigmation(number stigX, number stigY)

EMGetCondensorStigmation(number stigX, number stigY)
EMSetCondensorStigmation(number stigX, number stigY)

Column modes/settings//utility etc.

dm_string EMGetOperationMode( void )
void EMSetIlluminationMode( dm_string mode )
void EMSetImagingOpticsMode( dm_string mode )
void EMSetMicroscope( dm_string microscopeName)

Boolean EMUnitTest( dm_string test_options)
Boolean EMIsReady( void )
void EMWaitUntilReady( void )
Boolean EMInitialize( void )
Boolean EMIsMicroscopeInitialized( void )

TagGroup EMGetImagingOpticsModes( void )
dm_string EMGetImagingOpticsMode( void )
Boolean EMCanGetImagingOpticsMode( void )

Boolean EMIsSTEMMode( char *mode )
Boolean EMIsTEMMode( char *mode )
Boolean EMIsDiffractionMode( char *mode )
Boolean EMIsImagingMode( char *mode )

Communication

void EMSetupCommunication( void )
void EMCloseCommunication( void ) //Close communication to the microscope.

Low-level access to serial port

number EMGetSerialReadQueue(void)
string EMSerialReadHex(number numBytes )
void EMSerialWriteHex(string hexMessage )

 

Generic (Gatan-supported) EM Commands (GMS 2.x)

(see Faux Microscope Library). When I first started writing DM scripts to control a microscope it was around the late 90's and I was working with serial controlled JEOL TEMs. This class of microscope had their own internal command language. Commands could be entered at the internal JEOL keyboard. Although the syntax was a bit clunky and the response slow, I could control virtually any aspect of the microscope, from raising the screen to ramping the HT. The DM script simply had to squirt the relevant JEOL command along the serial line as text and off the microscope went and did its thing. Oh happy days. Gatan built into DM a series of generic microscope control commands (the EM commands). These allowed one to do many things. The microscope interface plugin (JEOLCOMM in the case of JEOL microscopes) took care of converting these commands into something which the microscope could understand. All well and good, as it meant scripters could write code which should work on all brands of microscope. However, the rot seems to have set in. In my last job I was trying to control an FEI Osiris microscope and some functionality was locked out by the manufacturer. What I was trying to do was control the HT, and so perhaps it was deemed that external code changing HT on a FEG is a bad idea - hence the lockout. What appears below is the current listing of EM Commands as of GMS 2.30. As you will see some of the functionality which used to be available in GMS 1.x is gone. For example the ability to change the microscope mode (TEM/Diffraction). I don't know whether this is down to Gatan or the microscope vendors. Either way, I have to say this is a retrograde step. Microscopy grows ever more sophisticated and users wish to have ever better control over their microscopes and microscopy experiments. If anyone who reads this is in any position to do anything about it, please do so. I want full control external over everything on my microscope. OK I could forego being able to change the extraction voltage on the FEG and opening and closing vacuum valves - but everything else I want to control - including the HT, the microscope mode, individual lenses, deflectors and stigmators. I know I am not alone in this.

 

Boolean EMCanGetCameraLength( )
Boolean EMCanGetHighTension( )
Boolean EMCanGetIlluminationMode( )
Boolean EMCanGetImagingOpticsMode( )
Boolean EMCanGetMagnification( )

void EMChangeBeamShift( Number xAmount, Number yAmount )
void EMChangeBeamTilt( Number xAmount, Number yAmount )
void EMChangeCalibratedBeamShift( Number xAmount, Number yAmount )
void EMChangeCalibratedBeamTilt( Number xAmount, Number yAmount )
void EMChangeCalibratedFocus( Number amount )

void EMChangeCalibratedImageShift( Number xAmount, Number yAmount )
void EMChangeCalibratedObjectiveStigmation( Number xAmount, Number yAmount )
void EMChangeCondensorStigmation( Number xAmount, Number yAmount )
void EMChangeFocus( Number amount )
void EMChangeImageShift( Number xAmount, Number yAmount )

void EMChangeObjectiveStigmation( Number xAmount, Number yAmount )
void EMGetBeamShift( NumberVariable shiftX, NumberVariable shiftY )
void EMGetBeamTilt( NumberVariable tiltX, NumberVariable tiltY )
Number EMGetBrightness( )
void EMGetCalibratedBeamShift( NumberVariable shiftX, NumberVariable shiftY )

void EMGetCalibratedBeamTilt( NumberVariable tiltX, NumberVariable tiltY )
Number EMGetCalibratedCameraLength( String deviceLocation, TagGroup stateInfo, NumberVariable calCL, Number matchOptions )
Number EMGetCalibratedFieldOfView( String deviceLocation, TagGroup stateInfo, NumberVariable calFOV, Number matchOptions )
Number EMGetCalibratedFocus( )
void EMGetCalibratedImageShift( NumberVariable shiftX, NumberVariable shiftY )

Number EMGetCalibratedMag( String deviceLocation, TagGroup stateInfo, NumberVariable calMag, Number matchOptions )
void EMGetCalibratedObjectiveStigmation( NumberVariable stigX, NumberVariable stigY )
TagGroup EMGetCalibrationStateTags( )
Number EMGetCameraLength( )
void EMGetCondensorStigmation( NumberVariable stigX, NumberVariable stigY )

Number EMGetFocus( )
Number EMGetHighTension( )
String EMGetIlluminationMode( )
TagGroup EMGetIlluminationModes( )
EMGetIlluminationModes().TagGroupOpenBrowserWindow("Available Illumination Modes",0)void EMGetImageShift( NumberVariable shiftX, NumberVariable shiftY )
String EMGetImagingOpticsMode( )

TagGroup EMGetImagingOpticsModes( )
TagGroup modes = EMGetImagingOpticsModes()
Number EMGetMagIndex( )
Number EMGetMagnification( )
String EMGetMicroscopeName( )
void EMGetObjectiveStigmation( NumberVariable stigX, NumberVariable stigY )

String EMGetOperationMode( )
Number EMGetScreenPosition( )
Number EMGetSpotSize( )
Number EMGetStageAlpha( )
Number EMGetStageBeta( )

void EMGetStagePositions( Number axisFlags, NumberVariable x, NumberVariable y, NumberVariable z, NumberVariable a, NumberVariable b )
void EMGetStageXY( NumberVariable x, NumberVariable y )
Number EMGetStageX( )
Number EMGetStageY( )
Number EMGetStageZ( )

Boolean EMIsReady( )
void EMSetBeamShift( Number shiftX, Number shiftY )
void EMSetBeamTilt( Number tiltX, Number tiltY )
void EMSetBrightness( Number brightness )
void EMSetCalibratedBeamShift( Number shiftX, Number shiftY )

void EMSetCalibratedBeamTilt( Variable tiltX, Variable tiltY )
void EMSetCalibratedFocus( Number focus )
void EMSetCalibratedImageShift( Number shiftX, Number shiftY)

void EMSetCalibratedObjectiveStigmation( Number stigX, Number stigY )
void EMSetCondensorStigmation( Number stigX, Number stigY )
Number EMSetFocus( Number focus )
void EMSetImageShift( Number shiftX, Number shiftY )
void EMSetMagIndex( Number index )

void EMSetObjectiveStigmation( Number stigX, Number stigY )
void EMSetScreenPosition( Number pos )
void EMSetSpotSize( Number spotSize )
void EMSetStageAlpha( Number a )
void EMSetStageBeta( Number b )

void EMSetStagePositions( Number axisFlags, Number x, Number y, Number z, Number a, Number b )
void EMSetStageXY( Number x, Number y )
void EMSetStageX( Number x )
void EMSetStageY( Number y )
void EMSetStageZ( Number z )
void EMUpdateCalibrationState( )
void EMWaitUntilReady( )

 

Gatan Camera Manager commands

A Faux Camera Library has been created. This contains a listing of all the Camera-based functions available, making it a useful reference for script development. When installed as a library, it permits the initial development of Gatan camera-based scripts to be done on an offline installation of DigitalMicrograph. The script under development need only be moved to the microscope for final testing and tuning.

I am indebted to Phil Ahrenkiel for the information in the quick reference section below. This contains many of the commonly used Camera Manager (CM) commands. Previously the SSC-series of commands would have been used for camera access. This new set of commands provides a wealth of extra functionality and control. The SSC commands are probably still supported, but I have not tested this.

A more complete listing of all the CM commands (courtesy of Gatan) along with additional supporting information can be downloaded as a text file. The file is a .s file. This is plain text, the same as a DM script. It can be opened in any text editor or in DigitalMicrograph.

 

Overview:

• Objects
• CameraManager
  • Maintains list of cameras and the current camera.
• Camera
  • Controls the physical camera
• CameraAcquisitionParameters
  • Specifies the parameters needed to generate an image from reads of the CCD. ( May be result of multiple reads if frames are summed or auto-exposure is turned on )

CameraManager:

• Object CM_GetCameraManager();
  • Returns the camera manager object.
• Object CM_GetCameras( Object cam_mgr );
  • Returns an 'ObjectList' object containing a list of the available cameras.
• void CM_SelectCamera( Object cam_mgr, Object camera );
  • Sets the specified camera as the currently selected camera.
• Object CM_GetCurrentCamera();
  • Returns the currently selected camera.

Camera

• Coordinates:

There are two main coordinate systems used when specifying readout area on a CCD, raw coordinates

and binned coordinates. Raw coordinates for a CCD map the accessible active area of the CCD and

are not affected by camera orientation, binning, or readout transposition. The coordinates are

label the effective CCD pixels with values in [0,ccd_width-1]x[0,ccd_height-1], where the effective

active area of the CCD has size (ccd_width,ccd_height). An effective CCD pixel is the smallest

grouping of CCD pixels distinguishable via the controller ( for some MSC's, for example, the controller

bins the CCD pixels by '2' to get an effective CCD area of 2048x2048 from a 4096x4096 CCD ).

Binned coordinates for a given set of acquisition parameters are affected by the default camera

orientation and the binning and transpose in the acquisition parameters. The coordinates are

determined by the largest image that can be read by enlarging the raw CCD coordinates of the acquisition

parameters, but leaving all other settings constant. This is the coordinate system used when

specifying read area in old-style 'SSC*Acquire' commands. Note if a CCD dimension is not divisible

by the binning in that dimension, then there is some ambiguity about which CCD pixels make up

each binned pixel: for ccd size (ccd_width,ccd_height) and binning '(bin_x,bin_y)', binned pixel

(0,0) can have any CCD pixel in the range [0,mod(ccd_width,bin_x))x[0,mod(ccd_height,bin_y)) as its

top-left pixel. When setting the read area of a set of acquisition parameters in terms of binned pixels

the ambiguity is resolved using the alignment of the top-left binned pixel in the current read area in CCD

coordinates.

Camera orientation and image transpositions are described by a number which encodes a transformation generated

by 90 degree rotations and reflections. The number consists of three flags at bits '0', '1', and '8', where

• 0 - horizontal flip
• 1 - vertical flip
• 8 - diagonal flip

with any diagonal flip performed after any horizontal or vertical flip. In terms of rotation followed

by a horizontal flip, the values represent

• 0 - no rotation , no flip
• 1 - no rotation , horizontal flip
• 2 - rotate right by 180, horizontal flip
• 3 - rotate right by 180, no flip
• 256 - rotate right by 90 , horizontal flip
• 257 - rotate right by 270, no flip
• 258 - rotate right by 90 , no flip
• 259 - rotate right by 270, horizontal flip

General:

• String CM_GetCameraName( Object camera );
• void CM_SetCameraName( Object camera, String new_camera_name );
  • Gets/Sets the user name associated with the camera. If the string is not empty, this name is used in menus and dialogs to designate the camera. If it is empty, the camera identifier is used instead.
• String CM_GetCameraControllerClass( Object camera );
  • Returns a string describing the electronics/driver combination controlling the camera. The current possible values are "FirstLight", "MSC", "PICM", "FAUX"
• String CM_GetCameraIdentifier( Object camera );
  • Returns a unique string identifying the camera. It typically contains a string identifying the camera configuration followed by the index of the camera in the list of configured cameras.

CCD:

• void CM_CCD_GetSize( Object camera, Number &ccd_width, Number &ccd_height );
  • Sets into '(ccd_width,ccd_height)' the size in effective CCD pixels of the active area of the CCD. This is not affected by the default camera orientation.
• void CM_CCD_GetPixelSize_um( Object camera, Number &pix_width, Number &pix_height );
  • Sets into '(pix_width,pix_height)' the size of a CCD pixel in microns ( Note: this is not the active area of the pixel, but the distance between the top-left corners of adjacent pixels ). This is not affected by the default camera orientation.

Orientation:

The camera orientation is specified in the camera by a default transpose. By default, after an acquisition the resulting image is transposed by the default transpose before being placed in an image.

• Number CM_Config_GetDefaultTranspose( Object camera );
• void CM_Config_SetDefaultTranspose( Object camera, Number trans );
  • Get/Set the default transpose
• void CM_CalcFrameSize( Object camera, Number transpose, Number adj_x, Number adj_y, Number bin_x, Number bin_y, Number &dst_width_out, Number &dst_height_out );
  • Calculate the largest image '(dst_width_out,dst_height_out)' that can be acquired from 'camera' with binning '(bin_x,bin_y)', transpose 'transpose' applied in addition to the default camera orientation, and binned pixels aligned with CCD pixel '(adj_x,adj_y)'.

Shutters:

• Number CM_CountShutters( Object camera
  • Returns the number of shutters available for controlling exposure of the CCD during readout.

The following are only available for cameras with controller class "MSC" or "FirstLight"

• void CM_GetIdleShutterState( Object camera, Number shutter_index, Number &is_closed );
• void CM_SetIdleShutterState( Object camera, Number shutter_index, Number is_closed );
  • Get/Set whether the shutter specified by 'shutter_index' should be opened or closed when the camera is not reading out. Note that the shutters might not be independently controllable, in which case closing one might implicitly open the other.
• void CM_SetCurrentShutterState( Object camera, Number shutter_index, Number is_closed );
  • If outside a readout, specify whether the shutter specified by 'shutter_index' is open or closed. If within a readout, the behavior is camera-specific, but whatever happens the state will be replaced by the idle state at the end of the readout.

Insert/Retract:

• Number CM_IsCameraRetractable( Object camera );
• Number CM_GetCameraInserted( Object camera );
• void CM_SetCameraInserted( Object camera, Number inserted );
• void CM_Config_GetInsertabilityDelays( Object camera, Number &insert_delay, Number &retract_delay );
• void CM_Config_SetInsertabilityDelays( Object camera, Number insert_delay, Number retract_delay );
  • insertibility delays specify the times in seconds from the start of insertion to when a good image can be acquired ( 'insert_delay' ) and the time from the start of retraction to when the camera no longer blocks the beam ( 'retract_delay' ).

Antiblooming:

• Number CM_CanSetAntiblooming( Object camera );
  • Returns 'true' if antiblooming can be turned on/off.

Temperature:

Currently, there are two levels of software control of temperature: none and full. Full control

basically means the camera supports reading the current temperature, specifying a set point temperature,

and checking whether the temperature has stabilized at the set point ( currently only cameras with

controller class "PICM" support this ). On top of this are implemented 'startup', 'shutdown' and 'target'

temperatures. While the camera is active, if a 'target' temperature is set, the camera temperature is

brought to the target temperature in the background at a maximum rate specified by the maximum temperature

change rate. The 'startup' temperature if specified is used as the initial target temperature, and the

'shutdown' temperature is made the set point of the camera when the camera is deactivated.

• Number CM_DoesCameraNeedToBeCooled( Object camera );
• Number CM_HasTemperatureControl( Object camera );
• Number CM_GetTemperatureResolution_C( Object camera );
• Number CM_GetMinimumTemperature_C( object camera );
• Number CM_GetMaximumTemperature_C( Object camera );
• Number CM_GetActualTemperature_C( Object camera );
  • Return the measured temperature of the CCD
• void CM_SetTargetTemperature_C( Object camera, Number use_target_temp, Number temp_C );
• Number CM_GetTargetTemperature_C( Object camera, Number &temp_C );
  • For 'Set', set the target temperature to 'temp_C', and set whether to actually use the temperature as a target to 'use_target_temp'. For 'Get', put the target temperature in 'temp_C', and return whether 'temp_C' is actually to be used as a target.
• void CM_SetStartupTemperature_C( Object camera, Number use_startup_temp, Number temp_C );
• Number CM_GetStartupTemperature_C( Object camera, Number &temp_C );
• void CM_SetShutdownTemperature_C( Object camera, Number use_shutdown_temp, Number temp_C );
• Number CM_GetShutdownTemperature_C( Object camera, Number &temp_C );
  • Similar to 'CM_{Get|Set}TargetTemperature_C' for startup and shutdown temperatures respectively.
• Number CM_GetLocalTargetTemperature_C( Object camera, Number &temp_C );
  • If the hardware is currently trying to attain a set point temperature, return 'true' and set 'temp_C' to that temperature. ( Note, this is not necessarily the target temperature, but more likely a nearby temperature goal in the direction of the target ).
• Number CM_IsTemperatureStable( Object camera, Number &targ_temp_C );
  • Return whether the CCD temperature has stabilized the target temperature if one is specified, or stabilized at all if one is not specified. Set 'targ_temp_C' to the target temperature if one is specified, or the current set point in the hardware if it is not.
• Number CM_GetTemperatureMaxChangeRate( Object camera );
• void CM_SetTemperatureMaxChangeRate( Object camera, Number maxTempChange );

CameraAcquisitionParameters:

• Creation/Persistence:

The following functions are used to create a base camera acquisition parameter set. The parameters specify

an unprocessed ( except for defect correction ), unbinned read of the entire CCD with exposure '1.0' seconds.

Most of the remainaing parameters in effect are copied from the 'Record' parameter set, except that all extra

processing ( including auto-exposure and frame summing ) is turned off. The only exceptions are that the

functions containing 'View' are set to prefer continuous readout, and if the camera has a range of readout

qualities the 'Low', 'Medium', and 'High' specify a level.

• Object CM_GetCameraAcquisitionParameterSet_LowQualityImagingView( Object camera );
• Object CM_GetCameraAcquisitionParameterSet_MediumQualityImagingView( Object camera );
• Object CM_GetCameraAcquisitionParameterSet_HighQualityImagingView( Object camera );
• Object CM_GetCameraAcquisitionParameterSet_LowQualityImagingAcquire( Object camera );
• Object CM_GetCameraAcquisitionParameterSet_MediumQualityImagingAcquire( Object camera );
• Object CM_GetCameraAcquisitionParameterSet_HighQualityImagingAcquire( Object camera );
• Object CM_CreateAcquisitionParameters_FullCCD( Object camera, Number processing, Number exposure, Number binning_x, Number binning_y );
  • Create a camera acquisition parameters set based on 'CM_GetCameraAcquisitionParameterSet', but with the specified exposure, binning, and processing.

The following functions are for manipulating the standard, persisted camera acquisition parameters, currently

just 'Search', 'Focus', and 'Record'. In general, persistent parameter sets can be created using the first

function by specifying a mode name, style name, and parameter set name. Parameter sets so created are linked

to a location in the global tags, so calling 'CM_LoadCameraAcquisitionParameterSet' will initialize the parameter

set with settings from tags, and 'CM_SaveCameraAcquisitionParameterSet' will save the parameter set to tags.

Parameter sets created by other means are not linked to a tag location and will fail if either of those functions

are called. To create a parameter set linked to one of the standard persisted sets, use the following:

• mode_name style_name param_set_name
• Search "Imaging" "View" "Search"
• Focus "Imaging" "View" "Focus"
• Record "Imaging" "Acquire" "Record"

• Object CM_GetCameraAcquisitionParameterSet( Object camera, String mode_name, String style_name, String param_set_name, Number do_create );
  • Get a parameter set initialized from the tags associated with the specified 'mode_name', 'style_name', and 'param_set_name' if the tags exist. If the tags do not exist, return 'NULL' if 'do_create' is false, otherwise create a parameter set linked to the appropriate tag path. ( Note that if the parameter set is created, the contents are not saved to tags until 'CM_SaveCameraAcquisitionParameters' is called on the object ).
• void CM_LoadCameraAcquisitionParameterSet( Object camera, Object acq_params );
• void CM_SaveCameraAcquisitionParameterSet( Object camera, Object acq_params );
  • Loads/Saves 'acq_params' from/to the linked persistent parameters.

Acquisition Parameters:

• Common Readout Parameters
  • Number CM_GetExposure( Object acq_params );
  • void CM_SetExposure( Object acq_params, Number exposure );
    • Get/Set the exposure
  • void CM_GetBinning( Object acq_params, Number &bin_x, Number &bin_y );
  • void CM_SetBinning( Object acq_params, Number bin_x, Number bin_y );
    • Get/Set the binning
  • void CM_GetCCDReadArea( Object acq_params, Number &top, Number &left, Number &bottom, Number &right );
  • void CM_SetCCDReadArea( Object acq_params, Number top, Number left, Number bottom, Number right );
    • Get/Set the read area in raw CCD coordinates
  • void CM_GetBinnedReadArea( Object camera, Object acq_params, Number &bin_area_t, Number &bin_area_l, Number &bin_area_b, Number &bin_area_r );
  • void CM_SetBinnedReadArea( Object camera, Object acq_params, Number bin_area_t, Number bin_area_l, Number bin_area_b, Number bin_area_r );
    • Get/Set the read area in binned CCD coordinates
  • void CM_SetProcessing( Object acq_params, Number processing );
  • Number CM_GetProcessing( Object acq_params );
    • Get/Set part of the corrections. Possible values are:
    • 1 - No dark or gain correction
    • 2 - Dark correction only
    • 3 - Dark and gain correction.
• Number CM_GetCorrections( Object acq_params, Number corr_mask );
• void CM_SetCorrections( Object acq_params, Number corr_mask, Number corrections );
  • Turn on and off corrections individually. The corrections are specified by a bitfield 'corrections', and 'corr_mask' specify which corrections are to be returned or modified. The possible correction bits are:
  • 0 - defect correction
  • 4 - bias correction
  • 5 - linearization
  • 8 - dark correction
  • 9 - gain correction ( Currently, if specified, dark correction must be specified too ).
• Number CM_GetDoContinuousReadout( Object acq_params );
• void CM_SetDoContinuousReadout( Object acq_params, Number dcr );
  • Get/Set whether the readout should be optimized for continuous acquisition.
• void CM_SetStandardParameters( Object acq_params\
• , Number processing, Number exposure\
• , Number bin_x, Number bin_y\
• , Number ccd_area_t, Number ccd_area_l, Number ccd_area_b, Number ccd_area_r );
  • Set the specified processing, exposure, binning, and ccd read area. The binning does not take into account the camera orientation, and the read area is in raw CCD coordinates.
• void CM_SetStandardParameters_Dst( Object camera, Object acq_params\
• , Number processing, Number exposure\
• , Number bin_x_dst, Number bin_y_dst\
• , Number bin_area_t, Number bin_area_l, Number bin_area_b, Number bin_area_r );
  • Set the specified processing, exposure, binning, and binned read area. The binning takes into account the camera orientation and any transpose set in 'acq_params' ( i.e. a diagonal flip in the composed transpose means that 'bin_x_dst' is in the vertical direction in raw CCD coordinates ), and the read area is in binned CCD coordinates. Thus, the parameters have the same meaning as the corresponding ones in the old 'SSC*Read' commands.

Antiblooming:

• Number CM_GetDoAntiblooming( Object acq_params );
• void CM_SetDoAntiblooming( Object acq_params, Number do_antiblooming );
  • Get/Set whether to do antiblooming.

Shutter-Related Readout Parameters

• Number CM_GetShutterExposure( Object acq_params );
• void CM_SetShutterExposure( Object acq_params, Number do_shutter_exposure );
  • Get/Set whether the shutter should be closed during exposure. Note that simply closing the shutter during exposure for an acquisition might not create a good dark reference. ( For example for the enfina, the shutter must be closed, then the dark reference acquired after a delay ).
• Number CM_GetSettling( Object acq_params );
• void CM_SetSettling( Object acq_params, Number settling );
• Number CM_GetShutterIndex( Object acq_params );
• void CM_SetShutterIndex( Object acq_params, Number index );
  • Specify which shutter to use during readout. ( For "MSC" and "FirstLight", 0 is the standard and 1 is the alternate shutter ).
• Number CM_GetShutterClosedBetweenFrames( Object acq_params )
• void CM_SetShutterClosedBetweenFrames( Object acq_params, Number is_closed );
  • Specify whether the shutter used for readout is to be opened or closed during any delay between frames of a continuous readout. ( Only available on "MSC", equivalent to the 'Normally Closed' acquisition parameter setting ).

Extra processing

• Number CM_GetAcqTranspose( Object acq_params )
• void CM_SetAcqTranspose( Object acq_params, Number transform )
  • Transform applied to an image in addition to that induced by the camera orientation.
• void CM_SetNumberToSum( Object acq_params, Number num );
• Number CM_GetNumberToSum( Object acq_params );
  • Specify that resulting image is from sum of 'num' images from the camera.
• void CM_SetAutoExpose( Object camera, Object acq_params, Number has_auto_expose, number do_auto_expose );
  • Turn auto-exposure on or off based on value of 'do_auto_expose. ( 'has_auto_expose' should be 'true' )
• number CM_IsAutoExposeOn( Object camera, Object acq_params );
  • Returns whether auto-exposure is turned on for 'acq_params'

Acquisition:

Given a 'camera' and an arbitrary set of acquisition parameters 'acq_params', 'CM_Validate_AcquisitionParameters'

can be used to ensure that the parameters have appropriate settings, and 'CM_CameraCalcImageForm' can be used

to determine an appropriate size and data type. 'CM_AcquireImage' can be used to acquire a single image as

specified by 'acq_params'.

• Number CM_Validate_AcquisitionParameters( Object camera, Object acq_params );
  • If 'camera' can acquire an image as specified by 'acq_params', return 'true'. Otherwise, modifiy 'acq_params' so it specifies a valid readout from 'camera'. The validation tries to change as little as possible, preferring changing the read area to changing the binning.
• Number CM_IsValid_AcquisitionParameters( Object camera, Object acq_params );
  • Return 'true' if 'camera' can acquire in image as specified by 'acq_params', 'false' otherwise.
• void CM_CameraCalcImageForm( Object camera, Object acq_params, Number &data_type, Number &width, Number &height );
  • Set 'data_type' to a type of an image that can hold the values produced by a readout from 'camera' using parameters 'acq_params', and set '(width,height)' to the appropriate size of the image.
• Image NewImage( String title, Number data_type, Number width, Number height );
  • Create an image with title 'title', data type 'data_type', and size '(width,height)'
• Image CM_CreateImageForAcquire( Object camera, Object acq_params, String name );
• Image CM_AcquireImage( Object camera, Object acq_params );
  • Acquire and return an image from 'camera' using parameter set 'acq_params'.
• void CM_AcquireImage( Object camera, Object acq_params, Image img );
  • Acquire an image from 'camera' using parameter set 'acq_params', and place the result in 'img'. Fail if 'img' is not the appropriate size.
• void CM_AcquireDarkReference( Object camera, Object acq_params, Image img, Object frame_set_info );
  • Acquire a dark reference appropriate for images acquired from 'camera' using parameters 'acq_params'. Fail if 'img' is not an appropriate size. Pass 'NULL' into 'frame_set_info'.

 

JEOL-Specific Commands

(I'm sure there must be more?)

JEOLCOM_SetScreen(0) //set fluorescent to 0°
JEOLCOM_SetScreen(1) //set fluorescent to 7°
JEOLCOM_SetScreen(2) //set fluorescent to 90°

 

Philips-Specific Commands

I am indebted to Steffen Meyer of Gatan for compiling this list.

Number CMTurnKnob(Number whichknob, Number steps )

double CM(void)
dm_string CMGetVersion(void)
dm_string CMGetInstrument(void)
void CMShowVers(void)

Number CMSetUpCommunication(void)
Number CMCloseCommunication(void)
Number CMChangeFocus(Number amount)
Number CMChangeMag(Number amount)
Number CMSetSpot(Number amount)
Number CMChangeC2(Number amount)
Number CMSetFine(void)
Number CMSetCoarse(void)
Number CMStigOn(void)
Number CMStigOff(void)
Number CMDfOn(void)
Number CMDfOff(void)
Number CMChangeShift(Number xamount,Number yamount)
Number CMChangeMulti(Number xamount,Number yamount)
Number CMSetMag(Number amount)
Number CMSetLowDose(void)
Number CMBlankOn(void)
Number CMBlankOff(void)
Number CMReset(void)
Number CMReady(void)
Number CMExposure(void)
Number CMPressSoftKey(Number whichkey,Number unmofTimes)

Number CMTiltGoniometerTo(Number degrees)
Number CMXGoniometerTo(Number position)
Number CMYGoniometerTo(Number position)