PyJEM.detectorext¶

This package is used to control the detector functions of the FEMTUS.

Caution:

This package supports some functions published by the FEMTUS. Therefore, this package cannot be used under the following conditions.

The FEMTUS is not configured in the network.
The FEMTUS is not running.

PyJEM.detectorext.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.detectorext.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.detectorext.get_config()¶

Get this package connection settings.

Returns:: Service configuration dictionary.
Return type:: dict

PyJEM.detectorext.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.detectorext.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.detectorext.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.detectorext.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.detectorext.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 = detectorext.Detector("HAADF")
>>> img = detector.snapshotframe("bmp")
>>> type(img)
<class 'bytes'>

class PyJEM.detectorext.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 = detectorext.Detector("HAADF")
>>> det.livestart()
{"status": "OK"}

livestop()¶

Stop live acquisition.

Returns:: Execution result.
Return type:: dict

Examples

>>> det=detectorext.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

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

Examples

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

Examples

>>> 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=detectorext.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=detectorext.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 = detectorext.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

>>> detectorext.Detector("HAADF").get_detectorsetting()
{
    "AreaModeImagingArea": {
        "Y": 0,
        "X": 0,
        "Width": 16-4095,
        "Height": 16-4095
    },
    "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,
    "MultiDetectorMode": 1, // Not to be used.
    "CanOffset": true,
    "OffsetIndex": 1,
    "OffsetIndexMaximum": 4095,
    "OffsetIndexMinimum": 0,
    "OutputImageInformation": {
        "DataBits": 16,
        "EffectBits": 16,
        "Channels": 1,
        "ImageSize": {
        "Width": 16-4095,
        "Height": 16-4095
        },
        "PixelsPerMeter": {
        "Horizontal": 2560.0,
        "Vertical": 2560.0
        }
    },
    "scanMode": 1,
    "ScanRotation": 0-359.9,
    "scanRotationMaximum": 359.9,
    "scanRotationMinimum": 0,
    "scanRotationStep": 0.1,
    "SpotPosition": {
        "X": 0-4095,
        "Y": 0-4095
    },
    "spotPositionMaximum": 4095,
    "spotPositionMinimum": 0,
    "LiveStatus": "LiveStarted",
    "ScanFrameTime": {
        "FrameTime50Hz": 82080,
        "FrameTime60Hz": 68400,
        "LineTime50Hz": 40.0
        "LineTime60Hz": 33.33333333
    },
    "SyncMode": 1,
    "Version": "1.0"
    "MdpEnable": "false"
}
**Camera settings**

>>> detectorext.Detector("Camera").get_detectorsetting()
{
    "ExposureTimeValue": 123456,
    "ExposureTimeValueMaximum": 15000000,
    "ExposureTimeValueMinimum": 1000,
    "ExposureTimeString": "123.456 ms",
    "frameIntegration": 1,
    "BinningSize": {
        "Width": 2,
        "Height": 2
    },
    "ImagingAreaFullSize": {
        "X": 0,
        "Y": 0,
        "Width": 2048,
        "Height": 2048
    },
    "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
        }
    },
    "ShutterDelayTime": 10,
    "BurstBufferSize": 4294967296,
    "HardwareIntegration": 1,
    "OptionSettings" : {
        "Pixel Clock": "20MHz",
        "Gain": "5.0",
        "Offset": "4",
        "Sharpen Filter": "false"
    }
}

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 detectorext
>>> param = {
...     "ExposureTimeValue": 100,
...     "GainIndex": 8000,
...     "OffsetIndex": 8000
... }
>>> detectorext.Detector("HAADF").set_detectorsetting(param)

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

>>> detectorext.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

>>> detectorext.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

>>> detectorext.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

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

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

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

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

>>> detectorext.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

>>> detectorext.Detector("HAADF").set_scanmode(1)  # Set to Spot mode
>>> detectorext.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

>>> detectorext.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_syncmode(value)¶

Set the Syncmode.

Parameters:: value (int) – 0=Power, 1=Inside, 4-7=External.
Returns:: The value set on the TEM.
Return type:: dict

Note

only available for MDP.

Examples

>>> detector.Detector("HAADF").set_syncmode(1)
{"SyncMode": 1}

get_linedata(start, end)¶

Get image data for a range of lines.

Parameters:

start (int) – Start line number.
end (int) – End line number.

Returns:

Raw bytes for the requested lines. One pixel is two bytes (little-endian).

Return type:

bytes

Note

Data order corresponds to LUTScanSetting.LookUpTable. Only available for MDP.

Examples

detector.Detector("Camera").get_linedata(0, 10)

get_selectdata(start, end)¶

Get image data for specified pixel indices.

If scanMode != 4 (LUTScan) this behaves like get_linedata().

Parameters:

start (int) – Start index (byte position).
end (int) – End index (byte position).

Returns:

Raw bytes for the requested pixels. One pixel is two bytes (little-endian).

Return type:

bytes

Note

Data order corresponds to LUTScanSetting.LookUpTable. Only available for MDP.

Examples

detector.Detector("Camera").get_selectdata(0, 1023)

acquire_image(burst_number)¶

Perform continuous (burst) capture on a camera.

Parameters:: burst_number (int) – Number of frames to acquire in the burst.
Returns:: Execution result, typically {"status": "OK"} on success.
Return type:: dict

Note

Call get_acquired_images() on the client side to retrieve the captured frames.

Warning

Not supported for STEM detectors.

Examples

name = '_Camera_1'
cam = detectorext.Detector(name)
cam.acquire_image(4)

get_acquired_image_count()¶

Return the number of images acquired by a burst sequence.

Returns:: Dictionary containing the count under the key value.
Return type:: dict

Warning

Not supported for STEM detectors.

Examples

name = '_Camera_1'
cam = detectorext.Detector(name)
cam.get_acquired_image_count()

get_acquired_images(start, end)¶

Retrieve binary image data for acquired frames.

Parameters:

start (int) – Start frame number.
end (int) – End frame number.

Returns:

Binary data containing the requested frames.

Return type:

bytes

Note

Call acquire_image() first to populate the acquired sequence.

Warning

Not supported for STEM detectors.

Examples

from PyJEM import detectorext
import numpy as np
from PIL import Image

name = '_Camera_1'
cam = detectorext.Detector(name)
img = cam.get_acquired_images(0, 0)
arr = np.frombuffer(img, dtype=">u2").reshape((512, 512))
img_arr = Image.fromarray(arr)
img_arr.save(r"sample.png")

PyJEM.detectorext.set_mdp_enable(sw)¶

Enable or disable MDP beam control.

Parameters:: sw (bool) – If True enable MDP; if False disable MDP.
Returns:: Service response (execution result).
Return type:: dict

Examples

set_mdp_enable(True)

PyJEM.detectorext.set_LUT_offset(x, y)¶

Apply an offset to LUTScan image positions (e.g. for drift correction).

Parameters:

x (float) – X offset value.
y (float) – Y offset value.

Returns:

Service response (execution result).

Return type:

dict

Examples

set_LUT_offset(0.1, -0.2)

PyJEM.detectorext.get_LUTscansetting()¶

Return the LUT scan settings.

Returns:: Dictionary describing LUT scan parameters. Keys include LUTScanSetting (with LookUpTable, PixelResolution, Shape, Position), LookUpTableMaximum, LookUpTableMinimum, LookUpTablePointMaximum, and LUTOffset.
Return type:: dict

Note

LookUpTable is used when Shape is Free and contains a list of (X, Y) coordinates. Coordinates are normalized to image edges where center=(0.0, 0.0) and edges are +/-1.0. Values may extend to +/-4.0 in some modes.
PixelResolution controls point density for analytical areas.

Examples

detectorext.get_LUTscansetting()

PyJEM.detectorext.set_LUTscansetting(body)¶

Set LUT scan settings from a dictionary.

Parameters:: body (dict) – Dictionary containing keys to set. Typical structure includes LUTScanSetting with subkeys like LookUpTable, PixelResolution, Shape, Position, IgnorePixelCount, and BlankingCount.
Returns:: Service response (execution result).
Return type:: dict

Examples

body = {
    "LUTScanSetting":{
        "LookUpTable": [[-1,1], [0.5,0.2], [1,1]],
        "PixelResolution": 0,
        "Shape": 0,
        "Position": [[-1.0, -1.0], [1.0, 1.0]],
        "IgnorePixelCount": 1,
        "BlankingCount": 1,
    }
}
detectorext.set_LUTscansetting(body)

PyJEM.detectorext.get_lookuptable()¶

Return the LUT LookUpTable as binary data.

Returns:: Byte array representing the LookUpTable. Size = number_of_coordinates × 2 (X,Y) × 4 (float).
Return type:: bytes

Examples

data = detectorext.get_lookuptable()

PyJEM.detectorext.set_lookuptable(body)¶

Set the LUT LookUpTable using binary data.

Parameters:: body (bytes) – Byte array containing LookUpTable coordinates. Size = number_of_coordinates × 2 (X,Y) × 4 (float).
Returns:: Service response (execution result).
Return type:: dict

Examples

detectorext.set_lookuptable(binary_data)