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()

detectors = Detectors()

energy_filter = EnergyFilter()

gun = Gun()

optics = Optics()

illumination = Illumination()

projection = Projection()

piezo_stage = PiezoStage()

stage = Stage()

stem = Stem()

temperature = Temperature()

user_door = UserDoor()

vacuum = Vacuum()

Image object

Two acquisition functions: acquire_tem_image() and acquire_stem_image() return an Image object that has the following methods and properties:

class pytemscript.microscope.Image(obj, name=None, isAdvanced=False, **kwargs)[source]

Acquired image object.

property bit_depth: Bit depth.

property data: Returns actual image object as numpy int32 array.

property height: Image height in pixels.

property metadata: Returns a metadata dict for advanced camera image.

property name: Image name.

property pixel_type: Image pixels type: uint, int or float.

save(filename, normalize=False)[source]

Save acquired image to a file.

Parameters:

filename (str) – File path
normalize (bool) – Normalize image, only for non-MRC format

property width: Image width in pixels.

Example 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()

Documentation

class pytemscript.microscope.Acquisition(microscope)[source]

Image acquisition functions.

In order for acquisition to be available TIA (TEM Imaging and Acquisition) must be running (even if you are using DigitalMicrograph as the CCD server).

If it is necessary to update the acquisition object (e.g. when the STEM detector selection on the TEM UI has been changed), you have to release and recreate the main microscope object. If you do not do so, you keep accessing the same acquisition object which will not work properly anymore.

acquire_film(film_text, exp_time, **kwargs)[source]

Expose a film.

Parameters:

film_text (str) – Film text, 96 symbols
exp_time (float) – Exposure time in seconds

acquire_stem_image(cameraName, size, dwell_time=1e-05, binning=1, **kwargs)[source]

Acquire a STEM image.

Parameters:

cameraName (str) – Camera name
size (IntEnum) – Image size (AcqImageSize enum)
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
brightness (float) – Brightness setting
contrast (float) – Contrast setting

Returns:

Image object

acquire_tem_image(cameraName, size=AcqImageSize.FULL, exp_time=1, binning=1, **kwargs)[source]

Acquire a TEM image.

Parameters:

cameraName (str) – Camera name
size (IntEnum) – Image size (AcqImageSize enum)
exp_time (float) – Exposure time in seconds
binning – Binning factor
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.
frame_ranges (list) – List of tuple frame ranges that define the intermediate images, e.g. [(1,2), (2,3)]. 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

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

class pytemscript.microscope.Apertures(microscope)[source]

Apertures and VPP controls.

select(aperture, size)[source]

Select a specific aperture.

Parameters:

aperture (str) – Aperture name (C1, C2, C3, OBJ or SA)
size (float) – Aperture size

property show_all: Returns a dict with apertures information.

vpp_next_position()[source]: Goes to the next preset location on the VPP aperture.

property vpp_position: Returns the index of the current VPP preset position.

class pytemscript.microscope.Autoloader(microscope)[source]

Sample loading functions.

buffer_cycle()[source]: Synchronously runs the Autoloader buffer cycle.

dock_cassette()[source]: Moves the cassette from the capsule to the docker.

initialize()[source]: Initializes / Recovers the Autoloader for further use.

property is_available: Status of the autoloader. Should be always False on Tecnai instruments.

load_cartridge(slot)[source]

Loads the cartridge in the given slot into the microscope.

Parameters:: slot (int) – Slot number

property number_of_slots: The number of slots in a cassette.

run_inventory()[source]: Performs an inventory of the cassette. Note: This function takes considerable time to execute.

slot_status(slot)[source]

The status of the slot specified.

Parameters:: slot (int) – Slot number

undock_cassette()[source]: Moves the cassette from the docker to the capsule.

unload_cartridge()[source]: Unloads the cartridge currently in the microscope and puts it back into its slot in the cassette.

class pytemscript.microscope.Detectors(microscope)[source]

CCD/DDD, film/plate and STEM detectors.

property cameras: Returns a dict with parameters for all cameras.

property film_settings: Returns a dict with film settings. Note: The plate camera has become obsolete with Win7 so most of the existing functions are no longer supported.

property screen: Fluorescent screen position. (read/write)

property stem_detectors: Returns a dict with STEM detectors parameters.

class pytemscript.microscope.EnergyFilter(microscope)[source]

Energy filter controls.

property ht_shift: Returns High Tension energy shift in eV.

insert_slit(width)[source]

Insert energy slit.

Parameters:: width (float) – Slit width in eV

retract_slit()[source]: Retract energy slit.

property slit_width: Returns energy slit width in eV.

property zlp_shift: Returns Zero-Loss Peak (ZLP) energy shift in eV.

class pytemscript.microscope.Gun(microscope)[source]

Gun functions.

property beam_current: Returns the C-FEG beam current in Amperes.

do_flashing(flash_type)[source]

Perform cold FEG flashing.

Parameters:: flash_type (IntEnum) – FEG flashing type (FegFlashingType enum)

property extractor_voltage: Returns the extractor voltage.

property feg_state: FEG emitter status.

property focus_index: Returns coarse and fine gun lens index.

property ht_state: High tension state: on, off or disabled. 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)

property shift: Gun shift. (read/write)

property tilt: Gun tilt. (read/write)

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

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

property voltage_offset: High voltage offset. (read/write)

property voltage_offset_range: Returns the high voltage offset range.

class pytemscript.microscope.Illumination(tem)[source]

Illumination functions.

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

property beam_shift: Beam shift X and Y in um. (read/write)

property beam_tilt: 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: Mode of the illumination system: parallel or probe. (read/write)

property condenser_stigmator: C2 condenser stigmator X and Y. (read/write)

property convergence_angle: Convergence angle. Works only on 3-condenser lens systems. (read/write)

property dark_field: Dark field mode: cartesian, conical or off. (read/write)

property illuminated_area: Illuminated area. Works only on 3-condenser lens systems. (read/write)

property intensity: Intensity / C2 condenser lens value. (read/write)

property intensity_limit: Intensity limit. Set to False to disable. (read/write)

property intensity_zoom: Intensity zoom. Set to False to disable. (read/write)

property mode: Illumination mode: microprobe or nanoprobe. (read/write)

property probe_defocus: Probe defocus. Works only on 3-condenser lens systems. (read/write)

property rotation_center: 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: Spotsize number, usually 1 to 11. (read/write)

class pytemscript.microscope.LowDose(microscope)[source]

Low Dose functions.

property is_active: Check if the Low Dose is ON.

property is_available: Return True if Low Dose is available.

off()[source]: Switch OFF Low Dose.

on()[source]: Switch ON Low Dose.

property state: Low Dose state (LDState enum). (read/write)

class pytemscript.microscope.Microscope(useLD=True, useTecnaiCCD=False, useSEMCCD=False, remote=False)[source]

High level interface to the local microscope. Creating an instance of this class already queries COM interfaces for the instrument.

Parameters:

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 (may be faster than via TIA / std scripting)
useSEMCCD (bool) – Connect to SerialEMCCD plugin on Gatan PC that controls Digital Micrograph (may be faster than via TIA / std scripting)

property condenser_system: Returns the type of condenser lens system: two or three lenses.

property family: Returns the microscope product family / platform.

property user_buttons: Returns a dict with assigned hand panels buttons.

class pytemscript.microscope.Optics(microscope)[source]

Projection, Illumination functions.

beam_blank()[source]: Activates the beam blanker.

beam_unblank()[source]: Deactivates the beam blanker.

property is_autonormalize_on: 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: Status of the beam blanker.

property is_shutter_override_on: 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)[source]: Normalize condenser or projection lens system. :param mode: Normalization mode (ProjectionNormalization or IlluminationNormalization enum) :type mode: IntEnum

normalize_all()[source]: Normalize all lenses.

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

class pytemscript.microscope.PiezoStage(microscope)[source]

Piezo stage functions.

property position: The current position of the piezo stage (x,y,z in um).

property position_range: Return min and max positions.

property velocity: Returns a dict with stage velocities.

class pytemscript.microscope.Projection(projection)[source]

Projection system functions.

property camera_length: The reference camera length in m (screen up setting).

property defocus: Defocus value in um. (read/write)

property detector_shift: Detector shift. (read/write)

property detector_shift_mode: Detector shift mode. (read/write)

property diffraction_shift: Diffraction shift in mrad. (read/write)

property diffraction_stigmator: Diffraction stigmator. (read/write)

eftem_off()[source]: Switch off EFTEM.

eftem_on()[source]: Switch on EFTEM.

property focus: Absolute focus value. (read/write)

property image_beam_shift: Image shift with beam shift compensation in um. (read/write)

property image_beam_tilt: Beam tilt with diffraction shift compensation in mrad. (read/write)

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

property image_shift: Image shift in um. (read/write)

property is_eftem_on: Check if the EFTEM lens program setting is ON.

property magnification: The reference magnification value (screen up setting).

property magnification_range: Submode of the projection system (either LM, M, SA, MH, LAD or D). The imaging submode can change when the magnification is changed.

property mode: Main mode of the projection system (either imaging or diffraction). (read/write)

property objective_stigmator: Objective stigmator. (read/write)

reset_defocus()[source]: Reset defocus value in the TEM user interface to zero. Does not change any lenses.

class pytemscript.microscope.Stage(microscope)[source]

Stage functions.

go_to(**kwargs)[source]

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

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

property holder: The current specimen holder type.

property limits: Returns a dict with stage move limits.

move_to(**kwargs)[source]: Makes the holder safely move to the new position. Keyword args can be x,y,z,a or b.

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

property status: The current state of the stage.

class pytemscript.microscope.Stem(microscope)[source]

STEM functions.

disable()[source]: Switch back to TEM mode.

enable()[source]: Switch to STEM mode.

property is_available: Returns whether the microscope has a STEM system or not.

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

property rotation: The STEM rotation angle (in mrad). (read/write)

property scan_field_of_view: STEM full scan field of view. (read/write)

class pytemscript.microscope.Temperature(microscope)[source]

LN dewars and temperature controls.

dewar_level(dewar)[source]

Returns the LN level (%) in a dewar.

Parameters:: dewar (IntEnum) – Dewar name (RefrigerantDewar enum)

property dewars_time: 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()[source]: Forces LN refill if the level is below 70%, otherwise returns an error. Note: this function takes considerable time to execute.

property is_available: Status of the temperature control. Should be always False on Tecnai instruments.

property is_dewar_filling: Returns TRUE if any of the dewars is currently busy filling.

property temp_cartridge: Returns Cartridge gripper temperature in Kelvins.

property temp_cassette: Returns Cassette gripper temperature in Kelvins.

property temp_docker: Returns Docker temperature in Kelvins.

property temp_holder: Returns Holder temperature in Kelvins.

class pytemscript.microscope.UserDoor(microscope)[source]

User door hatch controls.

close()[source]: Close the door.

open()[source]: Open the door.

property state: Returns door state.

class pytemscript.microscope.Vacuum(microscope)[source]

Vacuum functions.

column_close()[source]: Close column valves.

column_open()[source]: Open column valves.

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

property is_buffer_running: Checks whether the prevacuum pump is currently running (consequences: vibrations, exposure function blocked or should not be called).

property is_column_open: The status of the column valves.

run_buffer_cycle()[source]: Runs a pumping cycle to empty the buffer.

property status: Status of the vacuum system.