Microscope class

The Microscope class provides a Python interface to the microscope. Below are the main class properties, each represented by a separate class:

• acquisition = Acquisition()

• apertures = Apertures()

• autoloader = Autoloader()

• energy_filter = EnergyFilter()

• gun = Gun()

• optics = Optics()

  • illumination = Illumination()

  • projection = Projection()

• piezo_stage = PiezoStage()

• stage = Stage()

• stem = Stem()

• temperature = Temperature()

• user_buttons = UserButtons()

• user_door = UserDoor()

• vacuum = Vacuum()

Example usage

class pytemscript.microscope.Microscope(connection: str = 'direct', *args, **kwargs)

Main client interface exposing available methods and properties.

Parameters:

• connection (str) – Client connection: direct, socket or utapi. Defaults to direct.

• host (str) – Remote hostname or IP address

• port (int) – Remote port number

• useLD (bool) – Connect to LowDose server on microscope PC (limited control only)

• useTecnaiCCD (bool) – Connect to TecnaiCCD plugin on microscope PC that controls Digital Micrograph (maybe faster than via TIA / std scripting)

• debug (bool) – Debug mode

Usage:

>>> microscope = Microscope()
>>> curr_pos = microscope.stage.position
>>> print(curr_pos['Y'])
>>> 24.05
>>> microscope.stage.move_to(x=-30, y=25.5)

>>> beam_shift = microscope.optics.illumination.beam_shift
>>> defocus = microscope.optics.projection.defocus
>>> microscope.optics.normalize_all()

property condenser_system: str

Returns the type of condenser lens system: two or three lenses (CondenserLensSystem enum).

disconnect() → None

Disconnects the client.

property family: str

Returns the microscope product family / platform (ProductFamily enum).

Documentation

class pytemscript.modules.Acquisition(client)

Image acquisition functions.

acquire_film(film_text: str, exp_time: float) → None

Expose a film.

Parameters:

• film_text (str) – Film text, 96 symbols

• exp_time (float) – Exposure time in seconds

acquire_stem_image(cameraName: str, size: AcqImageSize = AcqImageSize.FULL, dwell_time: float = 1e-05, binning: int = 1, **kwargs) → Image

Acquire a STEM image.

Parameters:

• cameraName (str) – Camera name

• size (AcqImageSize) – Image size

• dwell_time (float) – Dwell time in seconds. The frame time equals the dwell time times the number of pixels plus some overhead (typically 20%, used for the line flyback)

• binning (int) – Binning factor. Technically speaking these are “pixel skipping” values, since in STEM we do not combine pixels as a CCD does.

• brightness (float) – Brightness setting (0.0-1.0)

• contrast (float) – Contrast setting (0.0-1.0)

Returns:

Image object

Return type:

Image

acquire_tem_image(cameraName: str, size: AcqImageSize = AcqImageSize.FULL, exp_time: float = 1.0, binning: int = 1, **kwargs) → Image | None

Acquire a TEM image.

Parameters:

• cameraName (str) – Camera name

• size (AcqImageSize) – Image size

• exp_time (float) – Exposure time in seconds

• binning (int) – Binning factor

• correction (AcqImageCorrection) – Image correction

• exposure_mode (AcqExposureMode) – CCD exposure mode

• shutter_mode (AcqShutterMode) – CCD shutter mode

• pre_exp_time (float) – The pre-exposure time in seconds.

• pre_exp_pause_time (float) – The time delay after pre-exposure and before the actual CCD exposure in seconds.

• align_image (bool) – Whether frame alignment (i.e. drift correction) is to be applied to the final image as well as the intermediate images. Advanced cameras only.

• electron_counting (bool) – Use counting mode. Advanced cameras only.

• eer (bool) – Use EER mode. Advanced cameras only.

• save_frames (bool) – Use to save movies. Advanced cameras only.

• group_frames (bool) – Group frames into fractions of this size. Advanced cameras only.

• recording (float) – minimum amount of time the acquisition will take, as it will take as much complete frames with the set exposure time as is needed to get to the set RecordingDuration. E.g. if the exposure time is 0.5 and the RecordingDuration is 2.3, there will be an acquisition of 2.5 (5 frames). Advanced cameras only.

• use_tecnaiccd (bool) – Use Tecnai CCD plugin to acquire image via Digital Micrograph, only for Gatan cameras. Requires Microscope() initialized with useTecnaiCCD=True

Returns:

Image object

Return type:

Image

Extra notes:

• Keyword arguments correction, exposure_mode, shutter_mode, pre_exp_time, pre_exp_pause_time are only available for CCD cameras that use standard scripting.

• Advanced cameras are Ceta 1, Ceta 2, Falcon 3, Falcon 4(i).

• Counting mode and frame saving requires a separate license enabled in TEM software.

• Continuous acquisition with recording is supported only by Ceta 2.

• TecnaiCCD plugin is only available for Gatan CCD cameras.

Usage:

>>> microscope = Microscope()
>>> acq = microscope.acquisition
>>> img = acq.acquire_tem_image("BM-Falcon", AcqImageSize.FULL, exp_time=5.0, binning=1, electron_counting=True, align_image=True)
>>> img.save("aligned_sum.mrc")
>>> print(img.width)
4096

property cameras: Dict

Returns a dict with parameters for all TEM cameras.

supports_csa means single acquisition (Ceta 1, Ceta 2, Falcon 3, Falcon 4(i)); supports_cca means continuous acquisition (Ceta 2 only)

property film_settings: Dict

Returns a dict with film settings.

Note: The plate camera has become obsolete with Windows 7 so most of the existing functions are no longer supported.

property screen_position: str

Fluorescent screen position, ScreenPosition enum. (read/write)

property stem_detectors: Dict

Returns a dict with STEM detectors parameters.

class pytemscript.modules.Apertures(client)

Apertures and VPP controls.

disable(aperture: MechanismId) → None

Disable a specific aperture.

Parameters:

aperture (MechanismId) – Aperture name

enable(aperture: MechanismId) → None

Enable a specific aperture.

Parameters:

aperture (MechanismId) – Aperture name

retract(aperture: MechanismId) → None

Retract a specific aperture.

Parameters:

aperture (MechanismId) – Aperture name

select(aperture: MechanismId, size: int) → None

Select a specific aperture.

Parameters:

• aperture (MechanismId) – Aperture name

• size (int) – Aperture size

show() → Dict

Returns a dict with apertures information.

vpp_next_position() → None

Goes to the next preset location on the VPP aperture.

property vpp_position: int

Returns the index of the current VPP preset position.

class pytemscript.modules.Autoloader(client)

Sample loading functions.

buffer_cycle() → None

Synchronously runs the Autoloader buffer cycle.

dock_cassette() → None

Moves the cassette from the capsule to the docker.

initialize() → None

Initializes / Recovers the Autoloader for further use.

property is_available: bool

Status of the autoloader. Should be always False on Tecnai instruments.

load_cartridge(slot: int) → None

Loads the cartridge in the given slot into the microscope.

Parameters:

slot (int) – Slot number

property number_of_slots: int

The number of slots in a cassette.

run_inventory() → None

Performs an inventory of the cassette. Note: This function takes considerable time to execute.

slot_status(slot: int) → str

The status of the slot specified (CassetteSlotStatus enum).

Parameters:

slot (int) – Slot number

undock_cassette() → None

Moves the cassette from the docker to the capsule.

unload_cartridge() → None

Unloads the cartridge currently in the microscope and puts it back into its slot in the cassette. Does nothing if no cartridge is on stage.

class pytemscript.modules.EnergyFilter(client)

Energy filter controls. Requires advanced scripting.

property ht_shift: float

High Tension energy shift in eV. (read/write)

insert_slit(width: float) → None

Insert energy slit.

Parameters:

width (float) – Slit width in eV

retract_slit() → None

Retract energy slit.

property slit_width: float

Energy slit width in eV. (read/write)

property zlp_shift: float

Zero-Loss Peak (ZLP) energy shift in eV. (read/write)

class pytemscript.modules.Gun(client)

Gun functions.

property beam_current: float

Returns the C-FEG beam current in nanoAmperes.

do_flashing(flash_type: FegFlashingType) → None

Perform cold FEG flashing.

Parameters:

flash_type (FegFlashingType)

property extractor_voltage: float

Returns the extractor voltage.

property feg_state: str

FEG emitter status (FegState enum).

property gun_lens: Tuple[int, int]

Returns coarse and fine gun lens index. Not available on systems with a monochromator.

property ht_state: str

High tension state: HighTensionState enum.

Disabling/enabling can only be done via the button on the system on/off-panel, not via script. When switching on the high tension, this function cannot check if and when the set value is actually reached. (read/write)

is_flashing_advised(flash_type: FegFlashingType) → bool

Check if cold FEG flashing is advised.

Parameters:

flash_type (FegFlashingType)

property shift: Vector

Gun shift. (read/write)

property tilt: Vector

Gun tilt. (read/write)

property voltage: float

The value of the HT setting as displayed in the TEM user interface. Units: kVolts. (read/write)

property voltage_max: float

The maximum possible value of the HT on this microscope. Units: kVolts.

property voltage_offset: float

High voltage offset. (read/write)

property voltage_offset_range: Tuple[float, float]

Returns the high voltage offset range.

class pytemscript.modules.Illumination(client, condenser_type)

Illumination functions.

property C3ImageDistanceParallelOffset: float

C3 image distance parallel offset. Works only on 3-condenser lens systems. (read/write)

This value takes the place previously of the Intensity value. The Intensity value changed the focusing of the diffraction pattern at the back-focal plane (MF-Y in Beam Settings control panel) but was rather independent of the illumination optics. As such it changed the size of the illumination but the illuminated area parameter was not influenced. To get rid of this problematic bypass, the C3 image distance offset has been created which effectively does the same focusing but now from within the illumination optics so the illuminated area remains correct. The range is quite small, +/-0.02

property beam_shift: Vector

Beam shift X and Y in um. (read/write)

property beam_tilt: Vector | float

Dark field beam tilt relative to the origin stored at alignment time. Only operational if dark field mode is active. Units: mrad, either in Cartesian (x,y) or polar (conical) tilt angles. The accuracy of the beam tilt physical units depends on a calibration of the tilt angles. (read/write)

property condenser_mode: str

Mode of the illumination system: parallel or probe. CondenserMode enum (read/write)

property condenser_stigmator: Vector

C2 condenser stigmator X and Y. (read/write)

property convergence_angle: float

Convergence angle. Works only on 3-condenser lens systems in probe mode.

property dark_field: str

Dark field mode: cartesian, conical or off. DarkFieldMode enum (read/write)

property illuminated_area: float

Illuminated area in um. Works only on 3-condenser lens systems. (read/write)

property intensity: float

Intensity / C2 condenser lens value. (read/write)

property intensity_limit: bool

Intensity limit. Set to False to disable. (read/write)

property intensity_zoom: bool

Intensity zoom (AutoZoom on Krios). Set to False to disable. (read/write)

property mode: str

Illumination mode: microprobe or nanoprobe. IlluminationMode enum (read/write)

(Nearly) no effect for low magnifications (LM).

property probe_defocus: float

Probe defocus. Works only on 3-condenser lens systems in probe mode.

property rotation_center: Vector

Rotation center X and Y in mrad. (read/write)

Depending on the scripting version, the values might need scaling by 6.0 to get mrads.

property spotsize: int

Spotsize number, usually 1 to 11. (read/write)

class pytemscript.modules.Optics(client, condenser_type)

Projection, Illumination functions.

beam_blank() → None

Activates the beam blanker.

beam_unblank() → None

Deactivates the beam blanker.

property instrument_mode: str

Current instrument mode: TEM or STEM (InstrumentMode enum).

property is_autonormalize_on: bool

Status of the automatic normalization procedures performed by the TEM microscope. Normally they are active, but for scripting it can be convenient to disable them temporarily.

property is_beam_blanked: bool

Status of the beam blanker.

property is_shutter_override_on: bool

Determines the state of the shutter override function.

WARNING: Do not leave the Shutter override on when stopping the script. The microscope operator will be unable to have a beam come down and has no separate way of seeing that it is blocked by the closed microscope shutter.

normalize(mode: ProjectionNormalization | IlluminationNormalization) → None

Normalize condenser or projection lens system.

Parameters:

mode (ProjectionNormalization or IlluminationNormalization)

normalize_all() → None

Normalize all lenses.

property screen_current: float

The current measured on the fluorescent screen (units: nanoAmperes).

class pytemscript.modules.PiezoStage(client)

Piezo stage functions.

property position: Dict

The current position of the piezo stage (x,y,z in um and a,b in degrees).

property position_range: Tuple[float, float]

Return min and max positions.

property velocity: Dict

Returns a dict with stage velocities (x,y,z are in um/s and a,b in deg/s).

class pytemscript.modules.Projection(client)

Projection system functions.

property camera_length: float

The reference camera length in m (screen up setting).

property camera_length_index: int

The camera length index. (read/write)

property defocus: float

Defocus value in um. (read/write) Changing ‘Defocus’ will also change ‘Focus’ and vice versa.

property detector_shift: str

Detector shift. ProjectionDetectorShift enum. (read/write)

property detector_shift_mode: str

Detector shift mode. ProjDetectorShiftMode enum. (read/write)

property diffraction_shift: Vector

Diffraction shift in mrad. (read/write)

property diffraction_stigmator: Vector

Diffraction stigmator. (read/write)

eftem_off() → None

Switch off EFTEM.

eftem_on() → None

Switch on EFTEM.

eucentric_focus() → None

Reset focus to eucentric value.

property focus: float

Absolute focus value. (read/write)

property image_beam_shift: Vector

Image shift with beam shift compensation in um. (read/write)

property image_beam_tilt: Vector

Beam tilt with diffraction shift compensation in mrad. (read/write)

property image_rotation: float

The rotation of the image or diffraction pattern on the fluorescent screen with respect to the specimen. Units: mrad.

property image_shift: Vector

Image shift in um. (read/write)

property is_eftem_on: bool

Check if the EFTEM lens program setting is ON.

property list_magnifications: Dict

List of available magnifications: mag -> (mag_index, submode).

property magnification: int

The reference magnification value (screen up setting). (read/write)

property magnification_index: int

The magnification index. (read/write)

property magnification_range: str

Submode of the projection system (either LM, M, SA, MH, LAD or D).

ProjectionSubMode enum. The imaging submode can change when the magnification is changed.

property mode: str

Main mode of the projection system (either imaging or diffraction). ProjectionMode enum (read/write)

property objective: float

The excitation of the objective lens in percent.

property objective_stigmator: Vector

Objective stigmator. (read/write)

reset_defocus() → None

Reset defocus value in the TEM user interface to zero. Does not change any lenses.

class pytemscript.modules.Stage(client)

Stage functions.

go_to(relative: bool = False, speed: float | None = None, **kwargs) → None

Makes the holder directly go to the new position by moving all axes simultaneously. Keyword args can be x,y,z,a or b. (x,y,z in um and a,b in degrees)

Parameters:

• relative (bool) – Use relative move instead of absolute position.

• speed (float) – fraction of the standard speed setting (max 1.0)

property holder: str

The current specimen holder type. StageHolderType enum.

property limits: Dict

Returns a dict with stage move limits.

move_to(relative: bool = False, **kwargs) → None

Makes the holder safely move to the new position. Keyword args can be x,y,z,a or b (x,y,z in um and a,b in degrees).

Parameters:

relative (bool) – Use relative move instead of absolute position.

property position: Dict

The current position of the stage (x,y,z in um and a,b in degrees).

reset_holder() → None

Reset holder to zero position for all axis.

property status: str

The current state of the stage. StageStatus enum.

class pytemscript.modules.Stem(client)

STEM functions.

disable() → None

Switch back to TEM mode.

enable() → None

Switch to STEM mode.

property is_available: bool

Returns whether the microscope has a STEM system or not.

property magnification: int

The magnification value in STEM mode. (read/write)

property rotation: float

The STEM rotation angle (in degrees). (read/write)

property scan_field_of_view: Vector

STEM full scan field of view in nm.

class pytemscript.modules.Temperature(client)

LN dewars and temperature controls.

dewar_level(dewar: RefrigerantDewar) → float

Returns the LN level (%) in a dewar.

Parameters:

dewar (RefrigerantDewar) – Dewar name

property dewars_time: int

Returns remaining time (seconds) until the next dewar refill. Returns -1 if no refill is scheduled (e.g. All room temperature, or no dewar present).

force_refill() → None

Forces LN refill if the level is below 70%, otherwise returns an error. Note: this function takes considerable time to execute.

property is_available: bool

Status of the temperature control. Should be always False on Tecnai instruments.

property is_dewar_filling: bool

Returns TRUE if any of the dewars is currently busy filling.

property temp_cartridge: float

Returns Cartridge gripper temperature in Kelvins.

property temp_cassette: float

Returns Cassette gripper temperature in Kelvins.

property temp_docker: float

Returns Docker temperature in Kelvins.

property temp_holder: float

Returns Holder temperature in Kelvins.

class pytemscript.modules.UserButtons(client)

User buttons control. Only local client is supported.

show() → Dict

Returns a dict with hand panel buttons labels.

class pytemscript.modules.UserDoor(client)

User door hatch controls. Requires advanced scripting.

close() → None

Close the door.

open() → None

Open the door.

property state: str

Returns door state (HatchState enum).

class pytemscript.modules.Vacuum(client)

Vacuum functions.

column_close() → None

Close column valves.

column_open() → None

Open column valves.

property gauges: Dict

Returns a dict with vacuum gauges information. Pressure values are in Pascals.

property is_buffer_running: bool

Checks whether the pre-vacuum pump is currently running (consequences: vibrations, exposure function blocked or should not be called).

property is_column_open: bool

The status of the column valves.

run_buffer_cycle() → None

Runs a pumping cycle to empty the buffer.

property status: str

Status of the vacuum system. VacuumStatus enum.