The COM interface

The methods and classes directly represent the COM objects exposed by the Scripting interface. The interface is described in detail in the scripting manual of your microscope (usually in the file scripting.pdf located in the C:\Titan\Tem_help\manual or C:\Tecnai\tem_help\manual directories).

The manual is your ultimate reference, this documentation will only describe the python wrapper to the COM interface.

The COM apartment model will automatically be initialized as COINIT_APARTMENTTHREADED (this changed in Version 2.1.0, it was COINIT_MULTITHREADED before). However, if the apartment model was already initialized as COINIT_MULTITHREADED before temscript was imported, temscript will also work. If you want a specific apartment model, set the variable sys.coinit_flags before importing temscript.

Enumerations

Many of the attributes return values from enumerations. These enumerations can be found in the temscript.enums module.

Changed in version 2.0: All methods of the COM interface now directly return the enumeration objects. The constants from temscript version 1.x are not defined anymore. The numerical values still can be accessed by querying the corresponding enum, e.g. psmSA corresponds to ProjectionSubMode.SA.

Vectors

Some object attributes handle with two dimensional vectors (e.g. ImageShift). These attributes return (x, y) like tuples and expect iterable objects (tuple, list, …) with two floats when written (numpy arrays with two entries also work).

Interface classes

Instrument - The entry point…

temscript.GetInstrument()

Creates a new instance of the Instrument class. If your computer is not the microscope’s PC or you don’t have the Scripting option installed on your microscope, this method will raise an exception (most likely of the OSError type).

class temscript.Instrument

Top level object representing the microscope. Use the GetInstrument() function to create an instance of this class.

Gun

(read) Instance of Gun for access to gun related functionalities

Illumination

(read) Instance of Illumination for access to illumination system and condenser related functionalities

Projection

(read) Instance of Projection for access to projection system related functionalities

Stage

(read) Instance of Stage for stage control

Acquisition

(read) Instance of Acquisition for image acquisition

Vacuum

(read) Instance of Vacuum for access to vacuum system related functionalities

InstrumentModeControl

(read) Instance of InstrumentModeControl for TEM/STEM switching.

BlankerShutter

(read) Instance of BlankerShutter for blanker control.

Configuration

(read) Instance of Configuration for microscope identification.

Camera

(read) Instance of Camera for fluscreen / plate camera control.

Added in version 2.0.

AutoNormalizeEnabled

(read/write) bool Enable/Disable autonormalization procedures

NormalizeAll()

Normalize all the lenses

Added in version 2.0.

Gun - Gun stuff

class temscript.Gun

Tilt

(read/write) (X,Y) tuple in the range of -1.0 to +1.0 (logical units). This attribute is inaccessable when the beamblanker (see Illumination) is active.

Shift

(read/write) (X,Y) tuple in the range of -1.0 to +1.0 (logical units).

HTState

(read/write) HighTensionState State of accelerator

Changed in version 2.0: Returns HighTensionState instance instead of integer.

HTValue

(read/write) float Current acceleration voltage (Volts)

Warning

Be careful when writing this attribute, it allows you to change the high tension.

HTMaxValue

(read) float Max. HT Value of the microscope (Volts)

Illumination - Condenser sytem

class temscript.Illumination

The functionality of some methods/attributes depend on the mode the illumination is in (see the manual for details).

Mode

(read/write) IlluminationMode Setting of minicondensor lens

Changed in version 2.0: Returns IlluminationMode instance instead of integer.

DFMode

(read/write) DarkFieldMode Dark field mode.

Changed in version 2.0: Returns DarkFieldMode instance

DarkFieldMode

(read/write) Alias of DFMode

BeamBlanked

(read/write) bool Setting of beam blanker. The beam blanker puts a large current to the gun tilt coils to blank the beam before it is entering the condenser system.

CondenserStigmator

(read/write) (X,Y) tuple in the range of -1.0 to +1.0 (logical units).

SpotSizeIndex

(read/write) int The spot size (1-11).

SpotsizeIndex

(read/write) Alias of SpotSizeIndex

Intensity

(read/write) float Value corresponding to the C2-Knob setting, range between 0.0 to 1.0 (logical units)

IntensityZoomEnabled

(read/write) bool Enable intensity zoom

IntensityLimitEnabled

(read/write) bool Enable Intensity limit

Note

Reading this property raises an exception (E_UNEXPECTED, “Catastrophic failure”) on Titan 1.1

Shift

(read/write) (X,Y) tuple of shift value (Meters). This corresponds to the User (Beam) Shift setting (which is displayed in logical units) in the System Status page. The scaling between the Meters and logical units depend on the calibration value stored in the aligment.

Tilt

(read/write) Meaning depends on the setting of DFMode

• in DarkFieldMode.CARTESIAN mode: (X, Y) tuple of shift value (Radians).

• in DarkFieldMode.CONICAL mode: (theta, phi) tuple of angles (Radians).

This corresponds to the DF Tilt setting (which is displayed in logical units) in the System Status page. The scaling between the Radians and the logical units depend on the calibration value stored in the aligment.

RotationCenter

(read/write) (X,Y) tuple of tilt value (Radians). This corresponds to the Rot. Center setting (which is displayed in logical units) in the System Status page. The scaling between the Radians and the logical units depend on the calibration value stored in the aligment.

StemMagnification

(read/write) float Magnification in STEM. As the magnification must be one of the discret values (as displayed on the micrsocope), the value is rounded to the next available value on write.

Note

On Titan 1.1, reading this attribute fails, if STEM is not available. See Restrictions.

StemRotation

(read/write) float Rotation in STEM (radians).

Note

On Titan 1.1, reading this attribute fails, if STEM is not available. See Restrictions.

CondenserMode

(read/write) CondenserMode Condenser mode (Available only on Titan).

Changed in version 2.0: Returns CondenserMode instance

IlluminatedArea

(read/write) float Illuminated area (meters? Is diameter meant? still to check). Requires parallel condensor mode. (Available only on Titan and only in CondenserMode.PARALLEL mode).

ProbeDefocus

(read/write) float Probe defocus (meters) Requires probe condenser mode. (Available only on Titan and only in CondenserMode.PROBE mode).

ConvergenceAngle

(read/write) float Convergence angle (radians) Requires probe condenser mode. (Available only on Titan and only in CondenserMode.PROBE mode).

Normalize(mode)

Normalizes condenser lenses. norm specifies what elements to normalize, see IlluminationNormalization

Projection - Projective system

class temscript.Projection

Depending on the mode the microscope is in not all properties are accessable at all times (see scripting manual for details).

Mode

(read/write) ProjectionMode Mode

Changed in version 2.0: Returns ProjectionMode instance instead of integer.

Note

On Titan 1.1 software changing the mode from IMAGING to DIFFRACTION and back again changes the magnification. See Restrictions.

SubMode

(read) ProjectionSubMode SubMode

Changed in version 2.0: Returns ProjectionSubMode instance instead of integer.

SubModeString

(read) str Textual description of Submode.

LensProgram

(read/write) LensProg Lens program

Changed in version 2.0: Returns LensProg instance instead of integer.

Magnification

(read) float Magnification as seen be plate camera. Use MagnificationIndex to change.

Note

On Titan 1.1 software this property reads 0.0 regardless of used mode. See Restrictions.

MagnificationIndex

(read/write) int Magnification setting

ImageRotation

(read) float Rotation of image/diffraction pattern with respect to specimen (radians)

DetectorShift

(read/write) ProjectionDetectorShift Set shift of diffraction pattern to specified axis.

Changed in version 2.0: Returns ProjectionDetectorShift instance instead of integer.

DetectorShiftMode

(read/write) ProjDetectorShiftMode Shift mode

Changed in version 2.0: Returns ProjDetectorShiftMode instance instead of integer.

Focus

(read/write) float Focus setting relative to focus preset (logical units). Range -1.0 (underfocus) to +1.0 (overfocus).

Defocus

(read/write) float Defocus (meters), relative to defocus set with ResetDefocus().

ObjectiveExcitation

(read) float Objective lens excitation in percent.

CameraLength

(read) float Camera length as seen by plate camera (meters). Use CameraLengthIndex to change.

CameraLengthIndex

(read/write) int Camera length setting

ObjectiveStigmator

(read/write) (X,Y) tuple in the range of -1.0 to +1.0 (logical units).

DiffractionStigmator

(read/write) (X,Y) tuple in the range of -1.0 to +1.0 (logical units).

DiffractionShift

(read/write) (X,Y) tuple of shift value (radians). This corresponds to the User Diffraction Shift setting (which is displayed in logical units) in the System Status page. The scaling between the radians and logical units depend on the calibration value stored in the aligment.

ImageShift

(read/write) (X,Y) tuple of shift value (meters). This corresponds to the User (Image) Shift setting (which is displayed in logical units) in the System Status page. The scaling between the Meters and logical units depend on the calibration value stored in the aligment.

ImageBeamShift

(read/write) (X,Y) tuple of shift value (meters). Shifts image and while compensating for the apparent beam shift. From the manual: Don’t intermix ImageShift and ImageBeamShift, reset one of them ot zero before using the other.

ImageBeamTilt

(read/write) (X,Y) tuple of tilt value. Tilts beam and compensates tilt by diffraction shift.

ProjectionIndex

(read/write) int Corresponds to MagnificationIndex or CameraLengthIndex depending on mode.

SubModeMinIndex

(read) int Smallest projection index of current submode.

SubModeMaxIndex

(read) int Largest projection index of current submode.

ResetDefocus()

Sets the Defocus of the current focus setting to zero (does not actually change the focus).

ChangeProjectionIndex(steps)

Changes the current ProjectionIndex by steps.

Normalize(norm)

Normalize projection system. norm specifies what elements to normalize, see ProjectionNormalization

Stage - Stage control

class temscript.Stage

Status

(read) StageStatus Status of the stage

Changed in version 2.0: Returns StageStatus instance instead of integer.

Position

(read) Current position of stage. The function returns a dict object with the values of the individual axes (‘x’, ‘y’, ‘z’, ‘a’, and ‘b’).

Holder

(read) StageHolderType Type of holder

Changed in version 2.0: Returns StageHolderType instance instead of integer.

AxisData(axis)

Returns tuple with information about that axis. Returned tuple is of the form (min, max, unit), where min is the minimum value, max the maximum value of the particular axis, and unit is a string containing the unit the axis is measured in (either ‘meters’ or ‘radians’). The axis must be one of the axes (‘x’, ‘y’, ‘z’, ‘a’, or ‘b’).

GoTo(x=None, y=None, z=None, a=None, b=None, speed=None)

Moves stage to indicated position. Stage is only moved along the axes that are not None.

Optionally the keyword speed can be given, which allows to set the speed of the movement. 1.0 correspond to the default speed.

Note

At least with Titan 1.1 software, moving the stage along multiple axes with speed keyword set fails. Thus movement with speed set, must be done along a single axis only. See Restrictions.

Changed in version 1.0.10: “speed” keyword added.

Changed in version 2.0: Internally the GoToWithSpeed method is used, when the speed keyword is given. Previous to version 2.0, the GoToWithSpeed method was only used if the speed keyword was different from 1.0.

MoveTo(x=None, y=None, z=None, a=None, b=None)

Moves stage to indicated position. Stage is only moved along the axes that are not None. In order to avoid pole-piece touch, the movement is carried out in the following order:

b->0; a->0; z->Z; (x,y)->(X,Y); a->A; b->B

Changed in version 2.0: Invalid keywords raise ValueError (instead of TypeError)

Vacuum related classes

class temscript.Vacuum

Status

(read) VacuumStatus Status of the vacuum system

Changed in version 2.0: Returns VacuumStatus instance instead of integer.

PVPRunning

(read) bool Whether the prevacuum pump is running

ColumnValvesOpen

(read/write) bool Status of column valves

Gauges

(read) List of Gauge objects

RunBufferCycle()

Runs a buffer cycle.

class temscript.Gauge

Name

(read) str Name of the gauge

Status

(read) GaugeStatus Status of the gauge

Changed in version 2.0: Returns GaugeStatus instance instead of integer.

Pressure

(read) float Last measured pressure (Pascal)

PressureLevel

(read) GaugePressureLevel Level of the pressure

Changed in version 2.0: Returns GaugePressureLevel instance instead of integer.

Read()

Read the pressure level. Call this before reading the value from Pressure.

Acquisition related classes

class temscript.Acquisition

Note

From the manual:

• TIA must be running

• After changing the detector selection in the UI you must reacquire a new Instrument using the GetInstrument() function.

• In order for detectors/cameras to be available, they must be selected in the UI.

Cameras

(read) List of CCDCamera objects.

Detectors

(read) List of STEMDetector objects.

StemAcqParams

(read/write) STEMAcqParams Acquisition parameters for STEM acquisition.

In the original Scripting interface the STEM acquisition parameters are read/write on the detectors collection returned by the Detectors attribute. obtained via the list of detectors returned by the Acquisition instance.

In version 1.X of the temscript adapter, this parameters were set via the STEMDetector instances itself, however the setting was common to all detectors.

Added in version 2.0.

AddAcqDevice(device)

Adds device to the list active devices. device must be of type CCDCamera or STEMDetector.

AddAcqDeviceByName(deviceName)

Adds device with name deviceName to the list active devices.

RemoveAcqDevice(device)

Removes device to the list active devices. device must be of type CCDCamera or STEMDetector.

RemoveAcqDeviceByName(deviceName)

Removes device with name deviceName to the list active devices.

RemoveAllAcqDevices()

Clears the list of active devices.

AcquireImages()

Acquires image from each active device, and returns them as list of AcqImage.

class temscript.CCDCamera

Info

Information about the camera as instance of CCDCameraInfo

AcqParams

Acquisition parameters of the camera as instance of CCDAcqParams

class temscript.CCDCameraInfo

Name

(read) str Name of CCD camera

Height

(read) int Height of camera (pixels)

Width

(read) int Width of camera (pixels)

PixelSize

(read) (X, Y)-Tuple with physical pixel size (Manual says nothing about units, seems to be meters)

Binnings

(read) List with supported binning values.

Changed in version 2.0: This attribute now returns a list of int (instead of a numpy array).

ShutterModes

(read) List with supported shutter modes (see AcqShutterMode enumeration).

Changed in version 2.0: This attribute now returns a list of AcqShutterMode (instead of a numpy array).

ShutterMode

(read/write) AcqShutterMode Selected shutter mode.

Changed in version 2.0: Returns AcqShutterMode instance instead of integer.

class temscript.CCDAcqParams

ImageSize

(read/write) AcqImageSize Camera area used.

Changed in version 2.0: Returns AcqImageSize instance instead of integer.

ExposureTime

(read/write) float Exposure time (seconds)

Note

On Titan 1.1 software images acquired after setting this property might not be acquired with the new setting, even though this property reflects the new value when read. See Restrictions.

Binning

(read/write) int Binning value

Note

On Titan 1.1 software setting this property also changes the exposure time. See Restrictions.

ImageCorrection

(read/write) AcqImageCorrection Correction mode.

Changed in version 2.0: Returns AcqImageCorrection instance instead of integer.

ExposureMode

(read/write) AcqExposureMode Exposure mode.

Changed in version 2.0: Returns AcqExposureMode instance instead of integer.

MinPreExposureTime

(read) float Smallest pre exposure time (seconds)

MaxPreExposureTime

(read) float Largest pre exposure time (seconds)

MinPreExposurePauseTime

(read) float Smallest pre exposure pause time (seconds)

MaxPreExposurePauseTime

(read) float Largest pre exposure pause time (seconds)

PreExposureTime

(read/write) float pre exposure time (seconds)

PreExposurePauseTime

(read/write) float pre exposure pause time (seconds)

class temscript.STEMDetector

Info

Information about the detector as instance of STEMDetectorInfo

AcqParams

Parameters for STEM acquisition as instance of STEMAcqParams. The acquisition parameters of all STEM detectors are identical, so this attribute will return the same instance for all detectors.

Deprecated since version 2.0: Use the StemAcqParams attribute of the Acquisition to set the parameters for STEM acqisition.

class temscript.STEMDetectorInfo

Name

(read) str Name of detector camera

Brightness

(read/write) float Brightness setting of the detector.

Contrast

(read/write) float Contrast setting of the detector.

Binnings

(read) List with supported binning values.

Changed in version 2.0: This attribute now returns a list of int (instead of a numpy array).

class temscript.STEMAcqParams

ImageSize

(read/write) AcqImageSize Area of scan

Changed in version 2.0: Returns AcqImageSize instance instead of integer.

DwellTime

(read/write) float Dwell time (seconds)

Note

On Titan 1.1, reading this attribute fails, if STEM is not available. See Restrictions.

Binning

(read/write) int Binning value

class temscript.AcqImage

Name

(read) unicode Name of camera/detector

Height

(read) int Height of acquired data array (pixels)

Width

(read) int Width of acquired data array (pixels)

Depth

(read) int Unsure: something like dynamic in bits, but not correct on our microscope.

Array

(read) numpy.ndarray Acquired data as numpy array object.

Fluscreen and plate camera

class temscript.Camera

Fluorescent screen and plate camera related methods.

Since the plate camera is not supported anymore on newer Titans most of the methods of the Camera class are meaningless. Nevertheless, the attributes ScreenCurrent MainScreen, and IsSmallScreenDown still are usefull for fluscreen control.

Added in version 2.0.

Stock

(read) int Number of plates still on stock

MainScreen

(read/write) ScreenPosition Position of the fluscreen.

IsSmallScreenDown

(read) bool Whether the focus screen is down.

MeasuredExposureTime

(read) float Measured exposure time (seconds)

FilmText

(read/write) str Text on plate. Up to 96 characters long.

ManualExposureTime

(read/write) float Exposure time for manual exposures (seconds)

PlateuMarker

(read/write) bool

Note

Undocumented property

ExposureNumber

(read/write) int Exposure number. The number is given as a 5 digit number plus 100000 * the ASCII code of one of the characters ‘0’ to ‘9’ or ‘A’ to ‘Z’.

Usercode

(read/write) str Three letter user code displayed on plate.

ManualExposure

(read/write) bool Whether the ManualExposureTime will be used for plate exposure.

PlateLabelDataType

(read/write) PlateLabelDateFormat Format of the date displayed on plate

ScreenDim

(read/write) bool Whether the computer monitor is dimmed

ScreenDimText

(read/write) str Test displayed when the computer monitor is dimmed.

ScreenCurrent

(read) float The current measured on the flu screen (Amperes)

TakeExposure()

Take single plate exposure.

Miscellaneous classes

class temscript.InstrumentModeControl

StemAvailabe

(read) bool Quite self decribing attribute

InstrumentMode

(read/write) InstrumentMode TEM or STEM mode

Changed in version 2.0: Returns InstrumentMode instance instead of integer.

class temscript.BlankerShutter

ShutterOverrideOn

(read/write) bool Overrides shutter control.

Warning

From the manual: If this override is on, there is no way to determine externally, that the override shutter is the active. So always reset this value from script, when finished.

class temscript.Configuration

ProductFamily

(read) ProductFamily Microscope type

Changed in version 2.0: Returns ProductFamily instance instead of integer.