Getting Started

Installation

Please see README.md

Desktop Shortcut

To create a desktop shortcut for FibsemUI, simply run the shortcut.py file.

System Configuration

The system configuration is defined by a system.yaml file. This defines various system settings, including connection details, beam, imaging, and stage settings.

You will need to change the ip_address to connect to your microscope.

The default file can be found in fibsem/config/system.yaml. When you call utils.setup_session() with no arguments, the default file is used. You can either edit the default file, or provide the config_path to your own system.yaml file in setup_session.

WIP: update for v2

# system
system:
  ip_address: 10.0.0.1
  application_file: autolamella
  manufacturer: Thermo # Thermo or Tescan
  # beams
  ion:
    voltage: 30000
    current: 20.e-12
    plasma_gas: "Argon" # proper case, e.g. Argon, Oxygen
    eucentric_height: 16.5e-3
    detector_type: ETD
    detector_mode: SecondaryElectrons
  electron:
    voltage: 2000
    current: 1.0e-12
    eucentric_height: 4.0e-3
    detector_type: ETD
    detector_mode: SecondaryElectrons
  # stage
  stage:
    rotation_flat_to_electron: 50 # degrees
    rotation_flat_to_ion: 230 # degrees
    tilt_flat_to_electron: 35 # degrees (pre-tilt)
    tilt_flat_to_ion: 52 # degrees
    pre_tilt: 35
    needle_stage_height_limit: 3.7e-3
# user config settings
user:
  imaging_current: 20.e-12
  milling_current: 2.e-9
  resolution: "1536x1024"
  hfw: 150.e-6  
  beam_type: "Electron"
  autocontrast: True
  dwell_time: 1.e-6
  save: False
  gamma: # gamma correction parameters
    enabled: True
    min_gamma: 0.15
    max_gamma: 1.8
    scale_factor: 0.01
    threshold: 46 # px

Note: setup_session will not automatically switch to these settings. To do so, you need to call validation.validate_initial_microscope_state.

Example

Once you have changed your system.yaml file, you should be able to run example/example.py to take images with both beams, and plot.

from fibsem import utils, acquire
import matplotlib.pyplot as plt


def main():

    # connect to microscope
    microscope, settings = utils.setup_session()

    # take image with both beams
    eb_image, ib_image = acquire.take_reference_images(microscope, settings.image)

    # show images
    fig, ax = plt.subplots(1, 2, figsize=(7, 5))
    ax[0].imshow(eb_image.data, cmap="gray")
    ax[1].imshow(ib_image.data, cmap="gray")
    plt.show()

if __name__ == "__main__":
    main()

The Basics

Microscope Connection

The microscope is a client connection to the Microscope Server. At the moment, only ThermoFisher AutoScript Client is supported.

MicroscopeSettings

MicroscopeSettings is a large structure containing the settings for the different microscope systems.

A data class representing the settings for a microscope system.

Attributes:

Name	Type	Description
system	SystemSettings	An instance of the SystemSettings class that holds the system settings.
image	ImageSettings	An instance of the ImageSettings class that holds the image settings.
protocol	dict	A dictionary representing the protocol settings. Defaults to None.
milling	FibsemMillingSettings	An instance of the FibsemMillingSettings class that holds the fibsem milling settings. Defaults to None.

Methods:

Name	Description
__to_dict__	Returns a dictionary representation of the MicroscopeSettings object.
__from_dict__	dict, protocol: dict = None) -> "MicroscopeSettings": Returns an instance of the MicroscopeSettings class from a dictionary.

Source code in fibsem/structures.py

@dataclass
class MicroscopeSettings:

    """
    A data class representing the settings for a microscope system.

    Attributes:
        system (SystemSettings): An instance of the `SystemSettings` class that holds the system settings.
        image (ImageSettings): An instance of the `ImageSettings` class that holds the image settings.
        protocol (dict, optional): A dictionary representing the protocol settings. Defaults to None.
        milling (FibsemMillingSettings, optional): An instance of the `FibsemMillingSettings` class that holds the fibsem milling settings. Defaults to None.

    Methods:
        __to_dict__(): Returns a dictionary representation of the `MicroscopeSettings` object.
        __from_dict__(settings: dict, protocol: dict = None) -> "MicroscopeSettings": Returns an instance of the `MicroscopeSettings` class from a dictionary.
    """

    system: SystemSettings
    image: ImageSettings
    protocol: dict = None
    milling: FibsemMillingSettings = None
    hardware: FibsemHardware = None


    def __to_dict__(self) -> dict:

        settings_dict = {
            "system": self.system.__to_dict__(),
            "user": self.image.__to_dict__(),
            "protocol": self.protocol,
            "milling": self.milling.__to_dict__(),
            "hardware": self.hardware.__to_dict__(),

        }

        return settings_dict

    @staticmethod
    def __from_dict__(settings: dict, protocol: dict = None, hardware: dict = None) -> "MicroscopeSettings":

        return MicroscopeSettings(
            system=SystemSettings.__from_dict__(settings["system"]),
            image=ImageSettings.__from_dict__(settings["user"]),
            protocol=protocol if protocol is not None else settings["protocol"],
            milling=FibsemMillingSettings.__from_dict__(settings["milling"]),
            hardware=FibsemHardware.__from_dict__(hardware) if hardware is not None else FibsemHardware.__from_dict__(settings["hardware"]),

        )

It is populated from your configuration in system.yaml. Most functions take a combination of the microscope client, and settings as arguments.

Taking an Image

The most basic use case for the package is taking an image. Imaging functions are contained in fibsem.acquire, and imaging conditions are controlled by modifying the ImageSettings struct.

Apply the given image settings and acquire a new image.

Parameters:

Name	Type	Description	Default
microscope	FibsemMicroscope	The FibsemMicroscope instance used to acquire the image.	required
settings	ImageSettings	The image settings used to acquire the image.	required

Returns:

Name	Type	Description
FibsemImage	FibsemImage	The acquired image.

Source code in fibsem/acquire.py

def new_image(
    microscope: FibsemMicroscope,
    settings: ImageSettings,
) -> FibsemImage:
    """Apply the given image settings and acquire a new image.

    Args:
        microscope (FibsemMicroscope): The FibsemMicroscope instance used to acquire the image.
        settings (ImageSettings): The image settings used to acquire the image.

    Returns:
        FibsemImage: The acquired image.
    """

    # set label
    if settings.beam_type is BeamType.ELECTRON:
        label = f"{settings.label}_eb"

    if settings.beam_type is BeamType.ION:
        label = f"{settings.label}_ib"

    # run autocontrast
    if settings.autocontrast:
        microscope.autocontrast(beam_type=settings.beam_type)

    # acquire the image
    image = microscope.acquire_image(
        image_settings=settings,
    )

    if settings.gamma_enabled:
        image = auto_gamma(image)

    # save image
    if settings.save:
        filename = os.path.join(settings.save_path, label)
        image.save(save_path=filename)

    return image

A data class representing the settings for an image acquisition.

Attributes:

Name	Type	Description
resolution	list of int	The resolution of the acquired image in pixels, [x, y].
dwell_time	float	The time spent per pixel during image acquisition, in seconds.
hfw	float	The horizontal field width of the acquired image, in microns.
autocontrast	bool	Whether or not to apply automatic contrast enhancement to the acquired image.
beam_type	BeamType	The type of beam to use for image acquisition.
save	bool	Whether or not to save the acquired image to disk.
label	str	The label to use when saving the acquired image.
gamma_enabled	bool	Whether or not to apply gamma correction to the acquired image.
save_path	Path	The path to the directory where the acquired image should be saved.
reduced_area	FibsemRectangle	The rectangular region of interest within the acquired image, if any.

Methods:

Name	Description
__from_dict__	dict) -> ImageSettings: Converts a dictionary of image settings to an ImageSettings object.
__to_dict__	Converts the ImageSettings object to a dictionary of image settings.

Source code in fibsem/structures.py

@dataclass
class ImageSettings:
    """A data class representing the settings for an image acquisition.

    Attributes:
        resolution (list of int): The resolution of the acquired image in pixels, [x, y].
        dwell_time (float): The time spent per pixel during image acquisition, in seconds.
        hfw (float): The horizontal field width of the acquired image, in microns.
        autocontrast (bool): Whether or not to apply automatic contrast enhancement to the acquired image.
        beam_type (BeamType): The type of beam to use for image acquisition.
        save (bool): Whether or not to save the acquired image to disk.
        label (str): The label to use when saving the acquired image.
        gamma_enabled (bool): Whether or not to apply gamma correction to the acquired image.
        save_path (Path): The path to the directory where the acquired image should be saved.
        reduced_area (FibsemRectangle): The rectangular region of interest within the acquired image, if any.

    Methods:
        __from_dict__(settings: dict) -> ImageSettings:
            Converts a dictionary of image settings to an ImageSettings object.
        __to_dict__() -> dict:
            Converts the ImageSettings object to a dictionary of image settings.
    """

    resolution: list = None
    dwell_time: float = None
    hfw: float = None
    autocontrast: bool = None
    beam_type: BeamType = None
    save: bool = None
    label: str = None
    gamma_enabled: bool = None
    save_path: Path = None
    reduced_area: FibsemRectangle = None
    line_integration: int = None # (int32) 2 - 255
    scan_interlacing: int = None # (int32) 2 - 8
    frame_integration: int  = None # (int32) 2 - 512
    drift_correction: bool = False # (bool) # requires frame_integration > 1

    def __post_init__(self):

        assert isinstance(self.resolution,list) or self.resolution is None, f"resolution must be a list, currently is {type(self.resolution)}"
        assert isinstance(self.dwell_time,float) or self.dwell_time is None, f"dwell time must be of type float, currently is {type(self.dwell_time)}"
        assert isinstance(self.hfw, float) or isinstance(self.hfw,int) or self.hfw is None, f"hfw must be int or float, currently is {type(self.hfw)}"
        assert isinstance(self.autocontrast, bool) or self.autocontrast is None, f"autocontrast setting must be bool, currently is {type(self.autocontrast)}"
        assert isinstance(self.beam_type,BeamType) or self.beam_type is None, f"beam type must be a BeamType object, currently is {type(self.beam_type)}"
        assert isinstance(self.save,bool) or self.save is None, f"save option must be a bool, currently is {type(self.save)}"
        assert isinstance(self.label,str) or self.label is None, f"label must b str, currently is {type(self.label)}"
        assert isinstance(self.gamma_enabled,bool) or self.gamma_enabled is None, f"gamma enabled setting must be bool, currently is {type(self.gamma_enabled)}"
        assert isinstance(self.save_path,(Path,str)) or self.save_path is None, f"save path must be Path or str, currently is {type(self.save_path)}"
        assert isinstance(self.reduced_area,FibsemRectangle) or self.reduced_area is None, f"reduced area must be a fibsemRectangle object, currently is {type(self.reduced_area)}"


    @staticmethod
    def __from_dict__(settings: dict) -> "ImageSettings":


        if "reduced_area" in settings and settings["reduced_area"] is not None:
            reduced_area = FibsemRectangle.__from_dict__(settings["reduced_area"])
        else:
            reduced_area = None


        image_settings = ImageSettings(
            resolution=settings.get("resolution", (1536, 1024)),
            dwell_time=settings.get("dwell_time", 1.0e-6),
            hfw=settings.get("hfw", 150e-6),
            autocontrast=settings.get("autocontrast", False),
            beam_type=BeamType[settings.get("beam_type", "Electron").upper()],
            gamma_enabled=settings.get("gamma_enabled", False),
            save=settings.get("save", False),
            save_path=settings.get("save_path", os.getcwd()),
            label=settings.get("label", "default_image"),
            reduced_area=reduced_area,
            line_integration=settings.get("line_integration", None),
            scan_interlacing=settings.get("scan_interlacing", None),
            frame_integration=settings.get("frame_integration", None),
            drift_correction=settings.get("drift_correction", False),
        )

        return image_settings

    def __to_dict__(self) -> dict:

        settings_dict = {
            "beam_type": self.beam_type.name if self.beam_type is not None else None,
            "resolution": self.resolution if self.resolution is not None else None,
            "dwell_time": self.dwell_time if self.dwell_time is not None else None,
            "hfw": self.hfw if self.hfw is not None else None,
            "autocontrast": self.autocontrast
            if self.autocontrast is not None
            else None,
            "gamma_enabled": self.gamma_enabled if self.gamma_enabled is not None else None,
            "save": self.save if self.save is not None else None,
            "save_path": str(self.save_path) if self.save_path is not None else None,
            "label": self.label if self.label is not None else None,
            "reduced_area": {
                "left": self.reduced_area.left,
                "top": self.reduced_area.top,
                "width": self.reduced_area.width,
                "height": self.reduced_area.height,
            }
            if self.reduced_area is not None
            else None,
            "line_integration": self.line_integration,
            "scan_interlacing": self.scan_interlacing,
            "frame_integration": self.frame_integration,
            "drift_correction": self.drift_correction,
        }

        return settings_dict

    @staticmethod
    def fromFibsemImage(image: 'FibsemImage') -> "ImageSettings":
        """Returns the image settings for a FibsemImage object.

        Args:
            image (FibsemImage): The FibsemImage object to get the image settings from.

        Returns:
            ImageSettings: The image settings for the given FibsemImage object.
        """
        from fibsem import utils
        from copy import deepcopy
        image_settings = deepcopy(image.metadata.image_settings)
        image_settings.label = utils.current_timestamp()
        image_settings.save = True

        return image_settings

fromFibsemImage(image) staticmethod

Returns the image settings for a FibsemImage object.

Parameters:

Name	Type	Description	Default
image	FibsemImage	The FibsemImage object to get the image settings from.	required

Returns:

Name	Type	Description
ImageSettings	ImageSettings	The image settings for the given FibsemImage object.

Source code in fibsem/structures.py

@staticmethod
def fromFibsemImage(image: 'FibsemImage') -> "ImageSettings":
    """Returns the image settings for a FibsemImage object.

    Args:
        image (FibsemImage): The FibsemImage object to get the image settings from.

    Returns:
        ImageSettings: The image settings for the given FibsemImage object.
    """
    from fibsem import utils
    from copy import deepcopy
    image_settings = deepcopy(image.metadata.image_settings)
    image_settings.label = utils.current_timestamp()
    image_settings.save = True

    return image_settings

ImageSettings is part of the MicroscopeSettings, and can be accessed by settings.image. For example, to change the hfw of the image and take an image (snippet):

# change hfw to 400e-6
settings.image.hfw = 400e-6

# take image
image = acquire.new_image(microscope, settings.image)

Movement

...

Milling

...