PyJEM.detector

This package controls the function of the detector.

PyJEM.detector.set_ip(val)

Set the IP address used by this package.

Parameters:

val (str) – IP address.

Return type:

None

Examples

>>> set_ip("127.0.0.1")

PyJEM.detector.set_port(val)

Set the port number used by this package.

Parameters:

val (int) – Port number.

Return type:

None

Warning

Please do not use this except for JEOL service staff.

Examples

>>> set_ip("127.0.0.1")

PyJEM.detector.get_config()

Get this package connection settings.

Returns:

Service configuration dictionary.

Return type:

dict

PyJEM.detector.check_connection(timeout=3.0)

Check whether the target service is running.

Parameters:

timeout (float) – timout in seconds for the connection check. Default is 3.0 seconds.

Returns:

True if the target service is running. False if the service is not running or the IP address or port number may be incorrect.

Return type:

bool

Examples

>>> check_connection()
True

PyJEM.detector.get_attached_detector()

Acquire the list of available ADF1 detectors in TEMCenter.

Returns:

List of available detectors.

Return type:

list of str

Examples

>>> detector.get_attached_detector()
[
    "HAADF",
    "LAADF",
    "BF",
    "None"
]

PyJEM.detector.assign_channel(detectorName, channel=0)

Assign the selected detector to a channel.

Parameters:

• detectorName (str) – Detector name such as “HAADF”.

• channel (int) – Channel number to assign. Default is 0.

Returns:

Execution result.

Return type:

dict

Examples

>>> detector.assign_channel("HAADF", 1)
{"status": "OK"}

PyJEM.detector.get_assignChannels()

Get the list of active detectors.

Returns:

Dictionary of active detector assignments.

Return type:

dict

Examples

>>> detector.get_assignChannels()
{
    "0": "BF",
    "1": "HAADF",
    "2": "LAADF",
    "3": "None"
}

PyJEM.detector.snapshotall()

Acquire all available detectors.

Returns:

Execution result.

Return type:

dict

Note

• This function is only for STEM mode.

• To obtain the acquired image data, use snapshotframe().

Examples

>>> detector.snapshotall()
{"status": "OK"}
>>> det = detector.Detector("HAADF")
>>> img = detector.snapshotframe("bmp")
>>> type(img)
<class 'bytes'>

PyJEM.detector.start_accumulate_image_cache()

Enable caching of Live image raw data.

Returns:

Execution result.

Return type:

dict

Examples

>>> detector.start_accumulate_image_cache()
{"status": "OK"}

PyJEM.detector.stop_accumulate_image_cache()

Disable caching of Live image raw data.

Returns:

Execution result.

Return type:

dict

Examples

>>> detector.stop_accumulate_image_cache()
{"status": "OK"}

class PyJEM.detector.Detector(det)

Bases: object

This class wraps REST calls for a specific detector (ADF/Camera/etc.) and provides convenience methods for live acquisition, snapshots, and parameter configuration.

Parameters:

det (str) – Detector identifier (e.g. “HAADF”, “LAADF”, “BF”, “Camera”).

Note

Methods generally return a dictionary with execution status or raw bytes for image data. Many settings are model-dependent; consult the TEM API or set_detectorsetting() for available keys.

livestart()

Start live acquisition.

Returns:

Execution result.

Return type:

dict

Examples

>>> det = detector.Detector("HAADF")
>>> det.livestart()
{"status": "OK"}

livestop()

Stop live acquisition.

Returns:

Execution result.

Return type:

dict

Examples

>>> det=detector.Detector("HAADF")
>>> det.livestop()
{"status":"OK"}

snapshot(ext, save=False, filename=None, show=False)

Acquire an image with the specified extension.

Parameters:

• ext (str) – Image format: “jpg”, “bmp”, “tif”.

• save (bool) – If True, save the captured file.

• filename (str) – File name or absolute path. Used only when save=True.

• show (bool) – Display the image.

Returns:

• If only ext is provided: image data stream (bytes).

• Otherwise: saved file name.

Return type:

bytes or str

Examples

Acquire image bytes and write to a file:

>>> det = detector.Detector("HAADF")
>>> img = det.snapshot("bmp")
>>> with open("temp.bmp", "wb") as f:
...     f.write(img)

Acquire and save using an autogenerated filename (service returns path):

>>> det.snapshot("bmp", save=True)
'.../20230217174244.bmp'

Acquire and save using a specified filename:

>>> det.snapshot("bmp", save=True, filename="test")
'.../test.bmp'

snapshotframe(ext, save=False, filename=None, show=False)

Return previously captured image frame (from snapshotall()).

Parameters:

• ext (str) – Image extension/format. Supported: "jpg", "bmp", "tif".

• save (bool) – If True, save the captured file, by default False.

• filename (str or None) – File name or absolute path to save. Only used when save=True, by default None.

• show (bool) – If True, display the image, by default False.

Returns:

• If only ext is provided: image data stream (bytes).

• If save=True: saved file path (str).

File stream saved with the selected extension

Return type:

bytes or str

Note

This function does not acquire new image, to return the image array acquired with the snapshotall() function.

Examples

>>> ## Acquisition of haadf images
>>> detector.snapshotall()
>>> det=detector.Detector("HAADF")
>>> img = det.snapshotframe("bmp")
>>> with open(r"C:  emp.bmp", "wb") as f:
...     f.write(img)
...
263222
>>> det.snapshotframe("bmp",save=True)
'C:\Users\Public\Documents\JEOL\python\envs\vjem310\Lib\site-packages\PyJEM\image\20230217174244.bmp'
>>> det.snapshotframe("bmp", save=True, filename="test")
'C:\Users\Public\Documents\JEOL\python\envs\vjem310\Lib\site-packages\PyJEM\image\test.bmp'

livesnapshot(ext, save=False, filename=None, show=False)

Capture a live image quickly (faster than snapshot()).

Parameters:

• ext (str) – Image extension/format. Supported: "jpg", "bmp", "tif".

• save (bool) – If True, save the captured file, by default False.

• filename (str or None) – File name or absolute path to save. Only used when save=True, by default None.

• show (bool) – If True, display the image, by default False.

Returns:

• If only ext is provided: image data stream (bytes).

• If save=True: saved file path (str).

Return type:

bytes or str

Examples

>>> ## Acquisition of haadf images
>>> det=detector.Detector("HAADF")
>>> img = det.livesnapshot("bmp")
>>> with open(r"C:  emp.bmp", "wb") as f:
...     f.write(img)
...
263222
>>> det.livesnapshot("bmp",save=True)
'C:\Users\Public\Documents\JEOL\python\envs\vjem310\Lib\site-packages\PyJEM\image\20230217174244.bmp'
>>> det.livesnapshot("bmp", save=True, filename="test")
'C:\Users\Public\Documents\JEOL\python\envs\vjem310\Lib\site-packages\PyJEM\image\test.bmp'

snapshot_rawdata()

Return raw image data for the selected detector.

Returns:

Raw 2-D image byte array returned by the detector.

Return type:

bytes

Examples

Convert raw bytes to a NumPy array and save with PIL:

import numpy as np
from PIL import Image
det = detector.Detector("HAADF")
img = det.snapshot_rawdata()
settings = det.get_detectorsetting()
width = settings["ImagingArea"]["Width"]
height = settings["ImagingArea"]["Height"]
imgarray = np.frombuffer(img, dtype=np.dtype('<i2')).reshape((width, height))
img = Image.fromarray(imgarray, mode="L")
img.save("test.bmp")

get_detectorsetting()

Obtaining setting information of selected detector.

Returns:

dict

Return type:

get the selected detector’s info.

Example

STEM detector settings

>>> detector.Detector("HAADF").get_detectorsetting()
{
    "AreaModeImagingArea": {
        "Y": 0,
        "X": 0,
        "Width": 255,
        "Height": 255
    },
    "AreaModeImagingAreaMaximum": 4096,
    "AreaModeImagingAreaMinimum": 16,
    "CanBinning": False,
    "BinningIndex": 0,  ## Not to be used.
    "BinningIndexMaximum": 0,
    "BinningIndexMinimum": 0,
    "BinningSize": {
        "Width": 1,
        "Hight": 1
    },
    "ExposureTimeIndex": 0-65535,
    "ExposureTimeIndexMaximum": 65535,
    "ExposureTimeIndexMinimum": 0,
    "ExposureTimeString": "0.0"-"1000.0",
    "ExposureTimeValue": 0.0 - 1000.0,
    "frameIntegration": 1,
    "frameIntegrationMaximum": 65535,
    "frameIntegrationMinimum": 1,
    "FrameRate": 10,   ##  Not to be used.
    "CanGain": true,
    "GainIndex": 1,
    "GainIndexMaximum": 4095,
    "GainIndexMinimum": 0,
    "ImagingArea": {
        "Y": 0,
        "X": 0,
        "Width":16-4095,
        "Height":16-4095
    },
    "ImagingAreaMaximum": 4095,
    "ImagingAreaMinimum": 16,
    "CanOffset": true,
    "OffsetIndex": 1,
    "OffsetIndexMaximum": 4095,
    "OffsetIndexMinimum": 0,
    "OutputImageInformation": {
        "DataBits": 16,
        "EffectBits": 16,
        "ImageSize": {
            "Width": 16-4095,
            "Height": 16-4095
        },
        "PixelsPerMeter": {
            "Horizontal": 2560.0,
            "Vertical": 2560.0
        }
    },
    "scanMode": 1,
    "ScanRotation": 0,
    "scanRotationMaximum": 359.9,
    "scanRotationMinimum": 0,
    "scanRotationStep": 0.1,
    "SpotPosition": {
        "X": 0-4095,
        "Y": 0-4095
    },
    "spotPositionMaximum": 4095,
    "spotPositionMinimum": 0,
    "ScanFrameTime": {
        "FrameTime50Hz": 82080,
        "FrameTime60Hz": 68400,
        "LineTime50Hz": 40.0
        "LineTime60Hz": 33.33333333
    },
    "SyncMode": 1
}

Camera settings

>>> detector.Detector("Camera").get_detectorsetting()
{
    "ExposureTimeValue": 123456,
    "ExposureTimeValueMaximum": 15000000,
    "ExposureTimeValueMinimum": 1000,
    "ExposureTimeString": "123.456 ms",
    "frameIntegration": 1,
    "BinningSize": {
        "Width": 2,
        "Height": 2
    },
    "ImagingAreaMaximum": {
        "Width": 2048,
        "Height": 2048
    },
    "ImagingArea": {
        "X": 256,
        "Y": 128,
        "Width": 1024,
        "Height": 1024
    },
    "OutputImageInformation": {
        "DataBits": 16,
        "EffectBits": 12,
        "ImageSize": {
            "Width": 512,
            "Height": 512
        },
        "PixelsPerMeter": {
            "Horizontal": 100000,
            "Vertical": 100000
        }
    }
}

set_detectorsetting(body)

Set detector or camera parameters by sending a settings dictionary.

Parameters:

body (dict) –

Settings payload.

key	type	value
AreaModeImagingArea	dict	Imaging area for Area mode. Valid when scanMode == 3. ⇒ See AreaModeImagingArea items.
BinningIndex	int	Pixel binning index.
ExposureTimeIndex	int	Exposure time index.
ExposureTimeValue	float	Exposure time in microseconds.
frameIntegration	int	Number of frame accumulations.
GainIndex	int	Gain value index.
ImagingArea	dict	Imaging area settings. ⇒ See ImagingArea items.
OffsetIndex	int	Offset value index.
scanMode	int	Scan mode. 0: Full, 1: Spot, 3: Area, 4: LUTScan.
ScanRotation	float	Scan rotation angle in degrees.
SpotPosition	dict	Spot position (valid when scanMode == 1). ⇒ See SpotPosition items.
SyncMode	int	Synchronization mode. 0: Power, 1: Inside, 4-7: External input (MDP trigger index).
BinningSize	dict	Camera binning configuration. ⇒ See BinningSize items.
ShutterDelayTime	float	Delay before shutter activation in milliseconds.
BurstBufferSize	int	Buffer size for burst acquisition in bytes.
HardwareIntegration	int	Number of frames integrated by hardware.
OptionSettings	dict	Detector-specific optional settings. Value format depends on model.

AreaModeImagingArea items

key	type	value
X	int	Left edge X coordinate.
Y	int	Top edge Y coordinate.
Width	int	Width in pixels.
Height	int	Height in pixels.

ImagingArea items

key	type	value
X	int	Left edge X coordinate.
Y	int	Top edge Y coordinate.
Width	int	Width in pixels.
Height	int	Height in pixels.

SpotPosition items

key	type	value
X	int	Spot X coordinate.
Y	int	Spot Y coordinate.

BinningSize items

key	type	value
Width	int	Horizontal binning factor.
Height	int	Vertical binning factor.

Returns:

The returned value is a dictionary containing applied detector settings.

Return type:

dict

Examples

>>> from PyJEM import detector
>>> param = {
...     "ExposureTimeValue": 100,
...     "GainIndex": 8000,
...     "OffsetIndex": 8000
... }
>>> detector.Detector("HAADF").set_detectorsetting(param)

set_frameintegration(value)

Set the frame integration (accumulation) count.

Parameters:

value (int) – Frame integration value (model-dependent range; typical 0-255).

Returns:

The value set on the TEM.

Return type:

dict

Example

>>> detector.Detector("HAADF").set_frameintegration(10)
{"frameIntegration": 10}

set_exposuretime_index(value)

Set the exposure time using an index value.

Parameters:

value (int) – Exposure time index (typical range 0-65535).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_exposuretime_index(100)
{"ExposureTimeIndex": 100}

set_exposuretime_value(value)

Set the exposure time by specifying a microsecond value.

Parameters:

value (float) – Exposure time in microseconds (model-dependent range; e.g. 0.0-1000.0).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_exposuretime_value(100)
{"ExposureTimeValue": 100}

set_gainindex(value)

Set the detector gain by index.

Parameters:

value (int) – Gain index (typical range 0-4095, model-dependent).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_gainindex(100)
{"GainIndex": 100}

set_offsetindex(value)

Set the detector offset by index.

Parameters:

value (int) – Offset index (typical range 0-4095, model-dependent).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_offsetindex(200)
{"OffsetIndex": 200}

set_digitalrotation(value)

Set the digital rotation angle.

Parameters:

value (float) – Rotation angle in degrees (0.0–360.0).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_digitalrotation(45.0)
{"DigitalRotation": 45.0}

set_scanrotation(value)

Set the scan rotation angle.

Parameters:

value (float) – Scan rotation angle in degrees (0.0–360.0).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_scanrotation(90.0)
{"ScanRotation": 90.0}

set_scanrotation_step(value)

Set the minimum step for scan rotation.

Parameters:

value (float) – Minimum variation step for scan rotation (e.g. 0.0–20.0).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_scanrotation_step(0.1)
{"scanRotationStep": 0.1}

set_imaging_area(Width, Height, X=None, Y=None)

Set imaging area (number of pixels) for the live image.

Parameters:

• Width (int) – Width in pixels (model-dependent range, e.g. 0–4096).

• Height (int) – Height in pixels (model-dependent range, e.g. 0–4096).

• X (int or None) – X coordinate of the starting pixel (default: None, unchanged).

• Y (int or None) – Y coordinate of the starting pixel (default: None, unchanged).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_imaging_area(1024, 1024, X=0, Y=0)
{"ImagingArea": {"X": 0, "Y": 0, "Width": 1024, "Height": 1024}}

set_spotposition(X, Y)

Set beam position for Spot scan mode.

Parameters:

• X (int) – Horizontal coordinate (0–4096, model-dependent).

• Y (int) – Vertical coordinate (0–4096, model-dependent).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_spotposition(100, 120)
{"SpotPosition": {"X": 100, "Y": 120}}

set_areamode_imagingarea(Width, Height, X=None, Y=None)

Set imaging area used when scanMode is Area.

Parameters:

• Width (int) – Width in pixels (model-dependent range).

• Height (int) – Height in pixels (model-dependent range).

• X (int or None) – X coordinate of the starting pixel (default: None, unchanged).

• Y (int or None) – Y coordinate of the starting pixel (default: None, unchanged).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_areamode_imagingarea(512, 512, X=256, Y=128)
{"AreaModeImagingArea": {"X": 256, "Y": 128, "Width": 512, "Height": 512}}

set_scanmode(value)

Set the detector scan mode.

Parameters:

value (int) – Scan mode value: 0 (Scan), 1 (Spot), 3 (Area).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("HAADF").set_scanmode(3)
{"scanMode": 3}

set_binningindex(value)

Set binning index (camera only).

Parameters:

value (int) – Binning index (model-dependent, typical 0-4).

Returns:

The value set on the TEM.

Return type:

dict

Examples

>>> detector.Detector("Camera").set_binningindex(2)
{"BinningIndex": 2}

AutoFocus()

Start the AutoFocus routine.

Returns:

Execution status (e.g. {“status”: “OK”}).

Return type:

dict

Examples

>>> detector.Detector("ADF1").AutoFocus()
{"status": "OK"}

AutoContrastBrightness()

Start Auto Contrast/Brightness adjustment.

Returns:

Execution status.

Return type:

dict

Examples

>>> detector.Detector("ADF1").AutoContrastBrightness()
{"status": "OK"}

AutoStigmator()

Start the AutoStigmator routine.

Returns:

Execution status.

Return type:

dict

Examples

>>> detector.Detector("ADF1").AutoStigmator()
{"status": "OK"}

AutoOrientation()

Start AutoOrientation routine.

Returns:

Execution status.

Return type:

dict

Examples

>>> detector.Detector("ADF1").AutoOrientation()
{"status": "OK"}

AutoZ()

Start Auto Z (focus) routine.

Returns:

Execution status.

Return type:

dict

Examples

>>> detector.Detector("ADF1").AutoZ()
{"status": "OK"}

get_insert_state()

Get detector insertion (in/out) state.

Returns:

Execution status describing insertion state.

Return type:

dict

Examples

>>> detector.Detector("ADF1").get_insert_state()
{"Inserted": True}

insert()

Insert the selected detector.

Returns:

Execution status.

Return type:

dict

Examples

>>> detector.Detector("ADF1").insert()
{"status": "OK"}

retract()

Retract the selected detector.

Returns:

Execution status.

Return type:

dict

Examples

>>> detector.Detector("ADF1").retract()
{"status": "OK"}

get_image_cache()

Return cached live image raw data.

Returns:

Cached image byte array. Requires image cache to be enabled.

Return type:

bytes

Note

This function may not be available on certain instruments.

Examples

>>> detector.start_accumulate_image_cache()
>>> detector.Detector("HAADF").get_image_cache()
b"
..."