specpy 2026.20.24464

Python Interface for Imspector

Imspector comes with a Python Interface named SpecPy which can be used either from the embedded Python console or from an external Python console running on the same computer (to enable sharing of measurement data) or even running on a different computer.

It can be used for remote control of microscopes, reading/writing data from/to running Imspector instances, and subscribing to change notifications. Essentially, all Imspector settings can be read and manipulated.

It can also be used as a standalone file reader to read .obf and .msr files in Python.

Start

• Working from an external Python console you need to start the Imspector Server (which requires Administrator privileges the first time)

• To load the Python Interface just say

from specpy import *

Examples

Open an .obf file in Python without Imspector running.

import specpy as sp
import numpy as np
from matplotlib import pyplot as plt

file = sp.File(r"C:\path\to\your\file.obf", sp.File.Read)

number_of_stacks = file.number_of_stacks()
metadata = file.metadata()

for i_stack in range(number_of_stacks):
    stack = file.read(i_stack)
    stack_name = stack.name()
    stack_data = stack.data()

    if stack_data.dtype == "uint16":
        fig, ax = plt.subplots()
        ax.set_title(stack_name)
        ax.imshow(stack_data)

Remote control an Imspector instance to open a Stack and calculate some statistics

import specpy as sp
import numpy as np

imspector = sp.get_application()
measurement = imspector.open(r"C:\path\to\your\file.obf")

threshold = 410

for name in measurement.stack_names():
  stack = measurement.stack(name)
  data = stack.data()

  mean = data.mean()
  standard_deviation = data.std()
  print(name, mean, standard_deviation)

  masked_data = np.ma.masked_less(data, threshold)
  mean = masked_data.mean()
  standard_deviation = masked_data.std()
  print(name, mean, standard_deviation)

  np.putmask(data, data < threshold, 4095)
  measurement.update()  # Update Imspector display after modifying stack data

Interface

Imspector

get_application()

first tries to return the local Imspector object (living in the same process) or else returns a proxy Imspector object connected to the Imspector Application running on localhost.

get_application(host)

where host is a host name returns a proxy Imspector object connected to the Imspector Application running on the corresponding host.

If imspector is an Imspector object then

imspector.host()

returns the name of the host the Imspector Application is running on or an empty string in case the Imspector object is local (living in the same process),

imspector.version()

returns the current Imspector version,

imspector.device_drivers()

returns the Imspector device drivers as a dictionary of name value pairs,

imspector.value_at(path, specpy.ValueTree.Hardware).get()

where path is of the form device/…/parameter_name returns the corresponding Imspector parameter value (the empty path returns a dictionary of name value pairs of all parameters).

imspector.value_at(path, specpy.ValueTree.Hardware).set(value)

where path is of the form device/…/parameter_name and value is a value, sets the corresponding Imspector parameter value (the empty path sets a dictionary of name value pairs of all parameters).

imspector.value_at(path, specpy.ValueTree.Status).get()

where path is of the form device/…/state_name returns the corresponding Imspector state value (the empty path returns a dictionary of name value pairs of all states).

imspector.value_at(path, specpy.ValueTree.Status).set(value)

where path is of the form device/…/state_name and value is a value, sets the corresponding Imspector state value (the empty path sets a dictionary of name value pairs of all states).

imspector.measurement_names()

returns the list of names of all open measurements in Imspector,

imspector.active_measurement()

for the currently active measurement in Imspector, returns the corresponding Measurement object or throws a RuntimeError if no measurement is active,

imspector.measurement(name)

where name is the name of an open measurement in Imspector, returns the corresponding Measurement object,

imspector.create_measurement()

creates an empty measurement in Imspector and returns the corresponding Measurement object,

imspector.open(path)

where path is the path to a measurement file, opens it in Imspector (if it is not already open) and returns the corresponding Measurement object,

imspector.activate(measurement)

where measurement is a Measurement object, activates the corresponding measurement in Imspector,

imspector.start(measurement)

where measurement is a Measurement object, starts the corresponding measurement in Imspector and returns immediately,

imspector.pause(measurement)

where measurement is a Measurement object, pauses the corresponding measurement in Imspector,

imspector.run(measurement)

where measurement is a Measurement object, runs the corresponding measurement in Imspector (starts it and returns when it has finished),

imspector.close(measurement)

where measurement is a Measurement object, closes the corresponding measurement in Imspector,

imspector.active_stack()

for the currently active stack (from the currently active measurement) in Imspector, returns the corresponding Stack object or throws a RuntimeError if no stack is active,

imspector.connect_measurement_cb(callable, signal)

where callable is a callable Python object and signal is one of specpy.MeasurementSignal.beg_measurement, specpy.MeasurementSignal.end_measurement, specpy.MeasurementSignal.beg_step, or specpy.MeasurementSignal.end_step, connects the callable to the corresponding signal in Imspector,

imspector.disconnect_measurement_cb(callable, signal)

where callable is a callable Python object and signal is one of specpy.MeasurementSignal.beg_measurement, specpy.MeasurementSignal.end_measurement, specpy.MeasurementSignal.beg_step, or specpy.MeasurementSignal.end_step, disconnects the callable from the corresponding signal in Imspector.

Measurement

If measurement is a Measurement object then

measurement.name()

returns the name of the measurement,

measurement.number_of_configurations()

returns the number of configurations in the measurement,

measurement.configuration_names()

returns the list of names of all configurations in the measurement,

measurement.active_configuration()

for the currently active configuration in the measurement, returns the corresponding Configuration object,

measurement.configuration(position)

where position is in the range from zero to the number of configurations in the measurement minus one, returns the corresponding Configuration object,

measurement.configuration(name)

where name is one of the configuration names in the measurement, returns the corresponding Configuration object,

measurement.activate(configuration)

where configuration is a Configuration object, activates the corresponding configuration in the measurement (if the measurement contains only one configuration, this configuration is activated by default),

measurement.clone(configuration)

where configuration is a Configuration object, clones the corresponding configuration in the measurement and activates and returns the clone,

measurement.remove(configuration)

where configuration is a Configuration object, removes the corresponding configuration in the measurement,

measurement.parameters(path)

where path is of the form device/…/parameter_name returns the corresponding measurement parameter value for the currently active configuration (the empty path returns a dictionary of name value pairs of all parameters),

measurement.set_parameters(path, value)

where path is of the form device/…/parameter_name and value is a value, sets the corresponding measurement parameter value for the currently active configuration (the empty path sets a dictionary of name value pairs of all parameters),

measurement.number_of_stacks()

returns the number of stacks in the measurement,

measurement.stack_names()

returns the list of names of all stacks in the measurement,

measurement.stack(position)

where position is in the range from zero to the number of stacks in the measurement minus one, returns the corresponding Stack object,

measurement.stack(name)

where name is one of the stack names in the measurement, returns the corresponding Stack object,

measurement.create_stack(type, sizes)

where type is a NumPy array data type and sizes is a list of exactly four sizes of dimensions, creates a new stack and returns the corresponding Stack object,

measurement.update()

redraws all corresponding stacks in Imspector (useful when the stack content was changed from Python),

measurement.save_as(path[, compression])

where path is a file path and compression is True by default or False saves it into a file.

Configuration

If configuration is a Configuration object then

configuration.name()

returns the name of the configuration,

configuration.parameters(path)

where path is of the form device/…/parameter_name returns the corresponding measurement parameter value for this configuration (the empty path returns a dictionary of name value pairs of all parameters),

configuration.set_parameters(path, value)

where path is of the form device/…/parameter_name and value is a value, sets the corresponding measurement parameter value for this configuration (the empty path sets a dictionary of name value pairs of all parameters),

configuration.number_of_stacks()

returns the number of stacks in this configuration,

configuration.stack_names()

returns the list of names of all stacks in this configuration,

configuration.stack(position)

where position is in the range from zero to the number of stacks in the configuration minus one, returns the corresponding Stack object,

configuration.stack(name)

where name is one of the stack names in this configuration, returns the corresponding Stack object.

File

File(path, mode)

where path is the path to an .obf or .msr file and mode is either File.Read or File.Write or File.Append opens it and returns the corresponding File object.

If file is a File object then

file.description()

returns the description of the file,

file.set_description(string)

where string is a string sets the description of the file,

file.number_of_stacks()

returns the number of stacks in the file,

file.read(position)

where position is in the range from zero to the number of stacks in the file minus one, reads and returns the corresponding Stack object,

file.write(stack[, compression])

where stack is a Stack object and compression is True by default or False writes it to the file,

del file

closes the file.

Stack

Stack(array)

where array is a NumPy ndarray returns a new local Stack object with data values from the array.

Stack(type, sizes)

where type is a NumPy array data type and sizes is a list of sizes of all dimensions returns a new local Stack object.

If stack is a Stack object then

stack.name()

returns the name of the stack,

stack.set_name(string)

where string is a string sets the name of the stack. If another stack in the same measurement already has the same name, suffixes of the form [1], [2], .. are added.

stack.description()

returns the description of the stack,

stack.set_description(string)

where string is a string, sets the description of the stack,

stack.type()

returns the type of the stack elements as NumPy array data type,

stack.number_of_elements()

returns the number of elements of the stack,

stack.shape()

returns the list of sizes of all dimensions of the stack,

stack.label(dimension)

where dimension is one of the dimensions returns the corresponding label of the stack,

stack.set_label(dimension, string)

where dimension is one of the dimensions and string is a string sets the corresponding label of the stack,

stack.labels()

returns the list of labels of all dimensions of the stack,

stack.set_labels(strings)

where strings is a list of strings for all dimensions sets the corresponding labels of the stack,

stack.length(dimension)

where dimension is one of the dimensions returns the corresponding length of the stack,

stack.set_length(dimension, number)

where dimension is one of the dimensions and number is a number sets the corresponding length of the stack,

stack.lengths()

returns the list of lengths of all dimensions of the stack,

stack.set_lengths(numbers)

where numbers is a list of numbers for all dimensions sets the corresponding lengths of the stack,

stack.offset(dimension)

where dimension is one of the dimensions returns the corresponding offset of the stack,

stack.set_offset(dimension, number)

where dimension is one of the dimensions and number is a number sets the corresponding offset of the stack,

stack.offsets()

returns the list of offsets of all dimensions of the stack,

stack.set_offsets(numbers)

where numbers is a list of numbers for all dimensions sets the corresponding offsets of the stack,

stack.parameters(path)

where path is of the form …/parameter_name returns the corresponding stack parameter value (the empty path returns a dictionary of name value pairs of all parameters),

stack.data()

returns the data of the stack as a NumPy ndarray.