Imspector Python Interface

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.

Setup

To setup SpecPy you first need to install

  • Python >= 3.5 together with
  • NumPy >= 1.10

Then from the Command Prompt run

python.exe -m pip install --upgrade specpy

Start

  • Working from an external Python console you need to start the Imspector Server (which requires Administrator priviliges the first time):
_images/imspector_run_server.png
  • To load the Python Interface just say
from specpy import *

Interface

SpecPy constants

SpecPy.__version__

contains a version string.

 SpecPy.File.Read
 SpecPy.File.Write

constants for read and write access

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.parameters(path)

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.set_parameters(path, 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.state(path)

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.set_state(path, 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_begin(callable, flag)

where callable is a callable Python object, connects it to the corresponding begin signal in Imspector (if flag is 0 the begin of the whole measurement and if flag if 1 the begin of one measurement step),

imspector.disconnect_begin(callable, flag)

where callable is a callable Python object, disconnects it from the corresponding begin signal in Imspector (if flag is 0 the begin of the whole measurement and if flag if 1 the begin of one measurement step),

imspector.connect_end(callable, flag)

where callable is a callable Python object, connects it to the corresponding end signal in Imspector (if flag is 0 the end of the whole measurement and if flag if 1 the end of one measurement step),

imspector.disconnect_end(callable, flag)

where callable is a callable Python object, disconnects it from the corresponding end signal in Imspector (if flag is 0 the end of the whole measurement and if flag if 1 the end of one measurement step).

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

Stack

Stack(array)

where array is a NumPy array 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.number_of_dimensions()

returns the number of dimensions of the stack (including singleton dimensions, i.e. a shortcut for len(stack.sizes())),

stack.size(dimension)

where dimension is one of the dimensions returns the corresponding size of the stack (the number of steps/positions in that dimension),

stack.sizes()

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 array,

stack.meta_data()

returns the meta data of the stack as a dictionary of name value pairs (amongst others the units of the pixels are given there and are valid for the pixel sizes and well as the stack lengths, i.e. the pixel sizes are the division of the stack lengths by the stack sizes).