General Library Information

All the calls to the EMC Library are very similarly structured. That's why the function descriptions in the library documentation are rather sparse and repetitive. I'll try to describe some of the general ideas here.

The entire library uses an EM Control Structure:

          typedef void EM;

Which, as you can see is a completely opaque data structure. The contents of this structure should only be known to the implementation of the EMC Library. (much like the FILE structure used for ANSI C's standard I/O library).

A pointer to this structure is used to identify the instrument to be controlled (in theory you can control more than one instrument at a time, although this is unlikely to occur in practice unless using a WICS based EMC Library).

The functions emcOpen() and emcClose() are used to create and destroy the EM Control structure (and hence begin and end communication with an instrument).

Each of the remaining functions:

`emcGetGoniometerPosition()`	`emcSetGoniometerPosition()`
`emcGetBeamTilt()`	`emcSetBeamTilt()`
`emcGetIntensity()`	`emcSetIntensity()`
`emcGetDefocus()`	`emcSetDefocus()`
`emcGetAstigmator()`	`emcSetAstigmator()`
`emcGetBeamShift()`	`emcSetBeamShift()`
`emcGetImageShift()`	`emcSetImageShift()`
`emcGetHighTension()`	`emcSetHighTension()`
`emcGetMagnificaition()`	`emcSetMagnification()`
`emcGetDarkField()`	`emcSetDarkField()`
`emcGetBeamBlank()`	`emcSetBeamBlank()`
`emcGetGridAlignments()`	`emcSetGridAlignments()`
`emcGetSpecimenLoadState()`
`emcNormalizeLenses()`

get passed the EM Control structure pointer as their first argument. Again much like the ANSI C Standard I/O functions (generally) pass a FILE structure pointer as their first argument.

Each function returns an integer value indicating whether the function executed properly. A value of 0 (EMC_OK) indicates the function executed as instructed. A value of less than 0 indicates an error. A value of greater than zero is currently not used, may later be considered a "maybe" state where the function performed some action that may not be 100% what was expected.

The majority of the functions are grouped as get/set pairs. The get function retrieves the parameter into memory locations provided by the caller. The set functions attempts to set the instrument parameters to the values passed by the caller.

Each get function typically has three modifying parameters: units, relative and correction which have the following effects on the function's execution.

units

The units the passed (or returned) values are expressed in:

UNCALIBRATED_UNITS Native instrument units for the parameter being accessed.

Distance Units (all or none accepted):

`ANGSTROM_UNITS`	Angstroms
`NANOMETER_UNITS`	Nanometers
`MICRON_UNITS`	Microns
`PIXEL_UNITS`	Pixels in currently active camera

Percentage Units (all or none accepted):

`PERCENTAGE_UNITS`	Value expressed as 0-100%
`NORMAL_UNITS`	Value expressed as 0.0-1.0

Angle Units (all or none accepted):

`RADIAN_UNITS`	Radians
`DEGREE_UNITS`	Degrees

correction

Boolean value which enables correction of known side effects of the function. This includes correction of goniometer movement due to backlash effects and shifts in image due to beam shift and change in apparent beam intensity due to magnification change. What is considered a reasonable "correction" is at the discretion of the EMC Library implementation (or WICS Server implementation).

The thought behind the correction flag is to correct side effects which affect the position or image quality of an image currently being viewed by a camera. So if changing magnification generates a predictable image shift, then we can legitimately correct for it when the magnification is changed. Some changes may not have a predictable correction factor (due to their nature, or misalignment of the instrument). The correction flag is meant as a guideline and indicates you give the EMC Library (or WICS Server) permission to make best effort corrections.

relative

Flags whether a parameter change should be made relative to the parameter's current value or relative to it's base value (usually 0).

`EMC_RELATIVE`	Relative to current value
`EMC_ABSOLUTE`	Relative to base value

Page 4 of 54