# 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):

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