Eiger

Dectris Eiger X-Ray Detector

DESCRIPTION

spec supports the Dectris Eiger detector via the spec server-hardware facility (see the server_hdw help file) using a program called eiger_server along with a special set of macros.

spec's eiger_server is Python based and accesses the Eiger through the HTTP-based RESTlike API provided by Dectris, as documented in the SIMPLON API Reference. eiger_server supports most of the commands and parameters available in the API.

eiger_server currently supports Versions 1.6 and 1.8 of the API. for Eiger or Eiger2 detectors.

INSTALLATION

All the source for eiger_server and the associated macros are included in the standard spec distribution. However, installation of the eiger_server requires the Python development package. The exact name of that package depends on the Linux distribution and the Python version being used. Possible names are python-dev, python2-devel, python3-devel, etc.

Additional required Python modules will be installed, if needed, by the included scripts. These modules are listed in the file servers/eiger/requirements.txt in the spec distribution directory. The modules can be installed before running the scripts using the standard Python pip package manager from the servers directory, as:

pip install -r eiger/requirements.txt

The commands to compile and install the server from the servers directory are:

make eiger_server
make install

By default, the server will be installed in SPECD/servers, where SPECD is the spec auxiliary file directory as set in the install_data file of the parent directory. The default value for SPECD is /usr/local/lib/spec.d.

The make install command will also place the eiger.mac file in SPECD/macros. The eiger help file is installed with the standard spec distribution, but can be recreated with the command:

make eiger_help

although that requires the Python docutils package be installed.

CONFIGURATION

Configure the server-hardware image device along these lines on the Acquisition screen of the configuration editor:

Image          DEVICE            ADDR  <>MODE              <>TYPE
0  YES localhost:5000  192.168.48.110         Server Image Device

The DEVICE field contains the resolvable hostname or IP address of where the server is running, followed by the port number on which the server is listening. The ADDR field is the resolvable hostname or IP address of the Eiger detector itself.

Type p to configure custom parameters. Enter the parameter names and values along the following lines:

Custom Parameters for Image 0 "Server Image Device"

NAME                      VALUE
command                   eiger_server
path                      /usr/local/lib/spec.d/servers
user                      specadm
args                      -P 80

command: The name of the server and a required parameter.
path: Needed if the server executable is not in the standard $PATH or in SPECD/servers.
user: If using a remote server, specifies a user name for the secure shell connection if the current user is not the appropriate value. Public-key secure-shell authentication needs to be set up properly for the named user to be able to start a remote server from spec.
args: Arguments to the server. spec will automatically add the -p port and the -d arguments to set the port number and daemonize the server. Additional arguments are described in the next section.

USAGE

When spec has connected to the Eiger detector, the standard counting and scanning macros can be configured to read the Eiger during data acquisition.

The eigeron and eigeroff macros or alternatively, the eiger_menu configuration macro, can be used to activate or de-activate the automatic Eiger acquisition. When the Eiger detector is activated by the macros, each count interval or scan point will trigger an acquisition. Data will be saved according to the options selected with the eiger_menu macro or with eigerfile and eiger_savemode macros. See the MACROS section below.

Acquisition parameters can also be configured by calling image_par() directly. See GET/SET SERVER PARAMETERS below.

SERVER

eiger_server is based on the server-hardware feature of spec. Refer to the server_hdw help page for general functionality and startup options. If configured as described in the previous section, spec will automatically start the server if required. Usually, the server will remain running even if spec exits.

Usage is:

eiger_server [options]

The following options are recognized:

-a Eiger_IP_address

Specifies the IP address or resolvable host name of the Eiger detector. When the server is started by spec, the value in the ADDR field of the configuration editor will be used and this option is not needed.

-P Eiger_port_number

Specifies the TCP port number where the Eiger listens. If a port other than default port 80 is used on the Eiger, be sure to include this parameter in the custom parameter window of the spec configuration editor.

-p port

Sets the port number on which the eiger_server listens. When the server is started by spec, the value will be sent automatically as taken from the DEVICE field of the configuration editor. The default port number is 5000.

-d

Daemonize the server. The server will run in the background and not be associated with a control terminal. When daemonized, the server creates a log file, either by the name specified with -l option, or a file in /tmp with a name consisting of the server name appended with a hyphen, the port number and .log. Error messages during start up that would appear on the associated terminal screen are redirected to the log file.

-k

Tells the server to kill an instance of it running with the same name and specified port number. The server then exits. This option is useful for terminating daemonized instances.

-l logfile

Logs output to the specified file. If no log file is used and the server is not daemonized, messages are sent to the standard output.

-v loglevel

Specifies the verbosity of the output messages as follows:

1 - Basic messages

2 - Also include messages exchanged with client

3 - Also include messages showing acquisition progress

4 - Also include additional debugging messages

-V

Shows simplon version number and exits. As this needs to connect with the Eiger, options -a and -P (if not using default port 80) are required:

eiger_server -V -a 192.168.48.110 -P 80

GET/SET SERVER PARAMETERS

The following parameters are accessible with the image_par() command in spec. Read-write parameters are labeled (RW), read-only parameters are labeled with (R).

Most of the parameters included with the SIMPLON API can accessed through the image_par() command. The third column in the tables below indicates which SIMPLON API versions support the parameter. Not all versions support all parameters.

When a parameter name in one SIMPLON subsystem conflicts with the name of a parameter in another subsystem, the following renaming is used:

SIMPLON API SPEC image_par()

mode (FileWriter interface) writer_mode

error (FileWriter interface) writer_error

state (FileWriter interface) writer_state

time (FileWriter interface) writer_time

buffer_free (FileWriter interface) writer_buffer_free

clear (FileWriter interface) writer_clear

initialize (FileWriter interface) writer_initialize

mode (Stream interface) stream_mode

state (Stream interface) stream_state

initialize (Stream interface) stream_initialize

For the specific meaning of any of the parameters refer to the Eiger User Manual or the SIMPLON API Reference Manual. For parameters that have additional considerations when using eiger_server, see the notes that follow.

Name Mode Ver Reference doc

server_version R ALL version

DETECTOR CONFIGURATION

beam_center_x RW ALL SIMPLON API

beam_center_y RW ALL SIMPLON API

bit_depth_image R ALL SIMPLON API

bit_depth_readout R ALL SIMPLON API

chi_increment RW ALL SIMPLON API

chi_start RW ALL SIMPLON API

compression RW ALL SIMPLON API

count_time RW ALL detpars

counting_mode RW >1.7 detpars

countrate_correction_applied RW ALL SIMPLON API

countrate_correction_count_cutoff RW ALL SIMPLON API

data_collection_date R ALL SIMPLON API

desc R ALL detpars

detector_distance RW ALL SIMPLON API

detector_number RW ALL SIMPLON API

detector_readout_time R ALL SIMPLON API

element RW ALL SIMPLON API

frame_time RW ALL SIMPLON API

kappa_increment RW ALL SIMPLON API

kappa_start RW ALL SIMPLON API

nimages RW ALL SIMPLON API

ntrigger RW ALL SIMPLON API

max_trigger R ALL detpars

number_of_excluded_pixels RW ALL SIMPLON API

omega_increment RW ALL SIMPLON API

omega_start RW ALL SIMPLON API

phi_increment RW ALL SIMPLON API

phi_start RW ALL SIMPLON API

photon_energy RW ALL SIMPLON API

roi_mode RW ALL SIMPLON API

sensor_material R ALL SIMPLON API

sensor_thickness R ALL SIMPLON API

software_version R ALL SIMPLON API

threshold_energy RW ALL SIMPLON API

threshold_energy1 RW >1.6 SIMPLON API

threshold_energy2 RW >1.6 SIMPLON API

threshold_difference RW >1.6 detpars

threshold_diff_lower RW >1.6 detpars

threshold_diff_upper RW >1.6 detpars

trigger_mode RW ALL SIMPLON API

trigger_start_delay RW >1.6 SIMPLON API

two_theta_increment RW ALL SIMPLON API

two_theta_start RW ALL SIMPLON API

wavelength RW ALL SIMPLON API

x_pixel_size R ALL SIMPLON API

x_pixels_in_detector R ALL SIMPLON API

y_pixel_size R ALL SIMPLON API

y_pixels_in_detector R ALL SIMPLON API

DETECTOR STATUS

state R ALL detstatus

simplon_version R ALL detstatus

seqid R ALL detstatus

status R ALL detstatus

detector_status R ALL detstatus

error R ALL SIMPLON API

time R ALL SIMPLON API

humidity R ALL detstatus

temperature R ALL detstatus

buffer_free R <1.7 detstatus

link/n R ALL detstatus

DETECTOR COMMANDS

initialize -- ALL SIMPLON API

arm -- ALL detcmds

disarm -- ALL detcmds

trigger -- ALL detcmds

cancel -- ALL detcmds

abort -- ALL detcmds

check_connections -- >1.7 SIMPLON API

FILEWRITER CONFIGURATION

writer_mode RW ALL filewpars

nimages_per_file RW ALL SIMPLON API

image_nr_start RW ALL SIMPLON API

name_pattern RW ALL filewpars

compression_enabled RW ALL SIMPLON API

files R ALL filewpars

filelist R ALL filewpars

transfer -- ALL filewpars

delete -- ALL filewpars

auto_delete RW ALL filewpars

FILEWRITER STATUS

writer_error R ALL SIMPLON API

writer_state R ALL SIMPLON API

writer_time R 1.6 SIMPLON API

writer_buffer_free R ALL SIMPLON API

writer_files R >1.7 SIMPLON API

FILEWRITER COMMANDS

writer_clear -- ALL SIMPLON API

writer_initialize -- ALL SIMPLON API

STREAM CONFIGURATION

stream_mode RW ALL streampars

stream_version RW >1.8 streampars

stream_autosave RW ALL streampars

stream_latest_file R ALL streampars

header_detail RW ALL SIMPLON API

header_appendix RW ALL SIMPLON API

image_appendix RW ALL SIMPLON API

save -- ALL streampars

overwrite_images RW ALL streampars

STREAM STATUS

stream_state R ALL SIMPLON API

stream_error R ALL SIMPLON API

is_waiting_data R ALL streampars

images_collected R ALL streampars

dropped R ALL SIMPLON API

STREAM COMMANDS

stream_initialize -- ALL SIMPLON API

MONITOR STATUS

monitor_state R >1.7 SIMPLON API

monitor_error R >1.7 SIMPLON API

monitor_dropped R >1.7 SIMPLON API

buffer_fill_level R >1.7 SIMPLON API

MONITOR STATUS

monitor_mode RW >1.7 SIMPLON API

discard_new RW >1.7 SIMPLON API

buffer_size RW >1.7 SIMPLON API

MONITOR COMMANDS

monitor_clear -- >1.7 SIMPLON API

monitor_initialize -- >1.7 SIMPLON API

MONITOR IMAGES

monitor_images -- >1.7 monitorimgs

monitor_save -- >1.7 monitorimgs

monitor_save_threshold -- >1.7 monitorimgs

monitor_pop -- >1.7 monitorimgs

SYSTEM COMMANDS

restart -- ALL syscmds

reboot -- >1.7 syscmds

shutdown -- >1.7 SIMPLON API

delete_logs -- >1.7 SIMPLON API

DATA MANAGEMENT PARAMETERS

prefix RW ALL datapars

stream_prefix RW ALL datapars

stream_autoindex RW ALL datapars

data_directory RW ALL datapars

low_filter RW ALL datapars

high_filter RW ALL datapars

roival R ALL datapars

sum R ALL datapars

maxval R ALL datapars

COMMAND MANAGEMENT

get_command R ALL cmdpars

cmd_executing R ALL cmdpars

get_answer R ALL cmdpars

PIXELMASK HANDLING

pixel_mask_applied RW ALL SIMPLON API

pixelmask_save -- ALL pxmaskpars

pixelmask_load -- ALL pxmaskpars

pixelmask_calibrate -- ALL pxmaskpars

flatfield_correction_applied RW ALL SIMPLON API

flatfield_save -- ALL pxmaskpars

COLLECTION HANDLING

collection_start -- ALL collectpars

collection_end -- ALL collectpars

collection_add_roi W ALL collectpars

collection_roi R ALL collectpars

collection_roi_list R ALL collectpars

collection_reset -- ALL collectpars

collection_get -- ALL collectpars

collection_npoints R ALL collectpars

is_collecting R ALL collectpars

image_par(unit, "server_version"): Returns the server version number and the version of the python executable used to run it.

Detector Configuration Parameters

image_par(unit, "count_time" [, secs])

For standard spec acquisitions, it is recommended to use the spec parameter "preset" to program the count time of the detector. The "preset" value will be used for both "count_time" and "frame_time".

The SIMPLON "count_time" and "frame_time" parameters may be useful when a deadtime is required between frames, in which case custom macros will be needed.

image_par(unit, "desc")

Returns the detector description as reported by the SIMPLON interface.

Detector Status Parameters

Detector status reporting varies slightly between different versions of the SIMPLON API. The spec implementation tries to unify calls where possible.

image_par(unit, "state"|"status"|"detector_status"): Returns the state value as described in the SIMPLON API manual.
image_par(unit, "simplon_version"): Returns the SIMPLON API version.
image_par(unit, "seqid"): Returns the sequence ID value.
image_par(unit, "humidity"): Returns humidity for SIMPLON Version 1.7 and board_000/th0_humidity with Version 1.6.
image_par(unit, "temperature"): Returns temperature for SIMPLON Version 1.7 and board_000/th0_temp with Version 1.6.
image_par(unit, "buffer_free"): Returns the builder/dcu_buffer_free parameter for SIMPLON Version 1.6. Not available with Version 1.7.
image_par(unit, "link/n"): Not available with SIMPLON Version 1.6.

Detector Commands

To reduce overhead and improve performance, spec generally only programs values when they have changed.

As described in the SIMPLON documentation, after all acquisition parameters have been selected, the acquisition of images in internal triggering mode requires issuing "arm" and "trigger" commands in sequence.

In a typical spec scan, where acquisition parameters do not change, performance improves significantly by issuing the "arm" command just once, followed by "trigger" commands for every new acquisition. That is the default behaviour implemented by the eiger_server in spec.

image_par(unit, "arm"): Enables the detector for acquisition.
image_par(unit, "disarm"): Disables the detector for acquisition.
image_par(unit, "trigger"): Sends a software trigger signal to the detector to start a new acquisition.
image_par(unit, "max_trigger"): Returns the maximum number of triggers that can be programmed in the detector.
image_par(unit, "threshold/1/mode" [, "enabled"|"disabled"]): Enables (1) or disables (0) data generation on threshold 1.
image_par(unit, "threshold/2/mode" [, "enabled"|"disabled"]): Enables (1) or disables (0) data generation on threshold 2.
image_par(unit, "threshold/difference/mode" [, "enabled"|"disabled"]): Enables (1) or disables (0) data generation on threshold difference.
image_par(unit, "threshold_difference" [, 1|0]): Enables (1) or disables (0) threshold difference mode.
image_par(unit, "cancel"): Stops the current series of acquisitions after the image being acquired is completed.
image_par(unit, "abort"): Stops the acquisition immediately.

Filewriter Parameters

image_par(unit, "writer_mode" [, 1|0]): Enables (1) or disables (0) the filewriter subsystem.
image_par(unit, "name_pattern"|"prefix" [, pattern]): Sets (or returns) the name pattern used to save HDF5 images.
image_par(unit, "stream_prefix" [, prefix]): Sets (or returns) the filename (or prefix) used to save TIFF images obtained through the stream interface.
image_par(unit, "files"): Returns the list of all the files in the Eiger DCU buffer.
image_par(unit, "filelist" [, pattern]): Returns the list of all the files in the Eiger DCU buffer with a name matching pattern.
image_par(unit, "transfer", filename|pattern): Transfers (saves) the file with the given filename or the set of files matching pattern from the Eiger to the local file system directory declared with "data_directory".
image_par(unit, "delete", filename|pattern): Deletes file filename or the set of files matching pattern from the Eiger DCU buffer.
image_par(unit, "auto_delete" [, 1|0]): Automatically deletes HDF5 files from the Eiger DCU buffer after transferring them with the command "transfer".

Stream Configuration Parameters

image_par(unit, "stream_mode" [, 1|0]): Enables (1) or disables (0) use of the stream subsystem.
image_par(unit, "stream_version" [, "V1"|"V2"]): Selects stream version to use. Stream V2 is available from Simplon version 1.8 and later. If V2 is selected, separate images are saved depending on the selection of active threshold filters. See parameters threshold/1/mode, threshold/2/mode and threshold/difference/mode on how to select active data.
image_par(unit, "stream_autosave" [, 1|0]): If enabled, automatically saves images read through the stream interface to disk. The parameters "data_directory" and "prefix" are used to choose the file location.
image_par(unit, "stream_latest_file"): Returns the name of file containing the latest image saved by the stream interface.
image_par(unit, "stream_autoindex" [, 1|0]): Sets (or returns) the autoindex option for stream image saving. If set, the output TIFF file will be built by adding an index number to the prefix. The index number will be reset to 0 when stream_prefix is changed.
image_par(unit, "acq_mode" [, SINGLE|ACCUM]): Sets (or returns) the acquisition mode value. Acquisition mode can be set to SINGLE or ACCUM (accumulation). In accumulation mode the detector is programmed to acquire several images during each acquisition cycle. The stream facility will then sum up the data of those images to create a single final image as result. ROI calculation or saving will be done on the resulting image. The number of images to be acquired in accumulation mode is selected using the parameters "acc_maxtime" or "acc_nimages" described below.
image_par(unit, "acc_maxtime" [, secs]): Sets (or returns) the maximum acquisition time for each individual image in accumulation mode. The actual exposure time for each image will be less than or equal to "acc_maxtime" in order to acquire the fewest images needed to complete the requested total acquisition (preset) time.
image_par(unit, "acc_nimages" [, nimages]): Sets (or returns) the number of individual images in accumulation mode used to compose the final image. When this value is set, it will take precedence over the calculation used when "acc_maxtime" is set. When "acc_maxtime" is set, this function will return the number of individual images used to compose the most recent accumulated image.
image_par(unit, "images_collected"): Returns the number of images collected through the stream interface from the start of the current acquisition. At the end of the acquisition the number should match the number of images programmed with "nimages".
image_par(unit, "is_waiting_data"): Checks whether the expected image count ("nimages") equals the number of images_collected`. If all expected images are collected returns 0. Returns 1 if more images are expected.
image_par(unit, "save", filename): Save the latest image acquired via the stream interface to file filename
image_par(unit, "overwrite_images" [, 1|0]): Allow overwriting images when the stream subsystem saves files to disk. If "overwrite_images" is set to 0, a new filename will be created by adding a sequence number to the existing filename.

Monitor Images

eiger_server supports the monitor data handler interface provided with SIMPLON version 1.8 and later. The monitor handler is not supported with SIMPLON version 1.6.

The monitor handler is currently the only way to save individual threshold images when two thresholds are enabled or when threshold difference mode is in effect.

image_par(unit, "monitor_images"): Returns a list of images available in the monitor interface in the format: [[series, [id,id,..]], ...].
image_par(unit, "monitor_save [ *series id* [ threshold_number]]"): If no parameters are given, the latest acquired image is saved. Otherwise the image to be saved is selected with the series and id parameters. If multiple thresholds are available, each threshold image can be saved independently by providing the threshold number.
image_par(unit, "monitor_save_threshold threshold_number"): Saves the latest image for the threshold number provided.
image_par(unit, "monitor_pop"): Save the oldest image in the monitor buffer (first in buffer) and deletes it from the buffer. The "data_directory" and "prefix" are used to decide filename location for saving. This function returns the name of the generated file.

System Commands

image_par(unit, "restart"): Restarts the detector SIMPLON API manager.
image_par(unit, "reboot"): Restarts the Eiger detector DCU (only available for SIMPLON Version 1.7)

Data Management Parameters and Commands

image_par(unit, "data_directory" [, folder]): Sets (or returns) the name of the directory used by both the filewriter and stream interface for saving acquired images.
image_par(unit, "name_pattern"|"prefix" [, pattern]): Sets (or returns) the name pattern used to save images. The pattern is shared with the filewriter interface.
image_par(unit, "high_filter" [, filter_value]): Sets a high pass filter. All values greater than the value set as high_filter will be set to zero when reading images (stream mode only).
image_par(unit, "low_filter" [, filter_value]): Sets a low pass filter. All values smaller than the value set as low_filter will be set to zero when reading images (stream mode only).
image_par(unit, "roisum", row_beg, col_beg, row_end, col_end): Returns the sum of all pixels included in the range given (stream mode only). The arguments are the pixel coordinates of the range.
image_par(unit, "sum"): Returns the sum of all pixels in the most recent image (stream mode only).
image_par(unit, "maxval"): Returns the maximum value in the most recent image (stream mode only).

Command Management Parameters

Due to a long execution time, some commands are run as a background task. The eiger_server handles the execution while other parameters can be read. If a return value is expected from the command, the value is kept in the server and can be retrieved at a later time.

image_par(unit, "get_command"): Get the name of the latest command being executed.
image_par(unit, "cmd_executing"): Return (1) if a command is being executed, (0) otherwise.
image_par(unit, "get_answer"): Return the value produced by the latest command execution.

Pixelmask (and Flatfield) Handling

image_par(unit, "pixelmask_save" [, filename])

Saves the current pixel mask to the named file or to a file named /tmp/pixelmask.npy if no file name is given. The binary .npy format is associated with the Python numpy module. (See numpy_save and numpy_load.)

image_par(unit, "pixelmask_load", filename)

Load the pixel mask contained in filename on to the detector. The binary .npy format is associated with the Python numpy module. (See numpy_save and numpy_load.)

image_par(unit, "pixelmask_calibrate")

Start a calculation on the latest acquired image (by the stream subsystem) to generate a new pixelmask. The process assumes the image contains no X-ray data and tries to set all pixels to zero. The pixels that have values different from zero are flagged and added to the existing pixelmask.

As as result, a new pixelmask is loaded in the Eiger detector. The previous pixelmask is saved as /tmp/pixelmask.bck.

image_par(unit, "flatfield_save" [, filename])

The flatfield array can be saved in the same way as with the "pixel_mask" parameter described above. The current flatfield is saved to the named file or to a file named /tmp/flatfield.npy if no file name is provided. spec does not currently provide a way to load a flatfield correction table to the Eiger detector.

MACROS

eiger_menu

Displays a menu with interactive configuration options.

eigeron

Enables using the Eiger detector in the standard spec counting and scanning macros.

eigeroff

Disables use of the Eiger detector in the standard spec acquisition macros.

eigerfile [prefix image_folder]

Selects the prefix and image_folder used during Eiger detector acquisition. When stream mode is selected, the image_folder directory will be used for saving TIFF image data files. When writer mode is selected, HDF5 image data files that are initially saved in the Eiger DCU data buffer, will be transferred to the image_folder directory with the eiger_transfer macro. The prefix string is used with both stream and writer modes.

eiger_savemode [mode]

Selects the saving mode. Options are: stream, writer, both or off.

eigerct cttime

Triggers one acquisition with the Eiger detector with an exposure time of cttime, using the current acquisition and saving options. eigerct can be used independently of the standard acquisition macros.

eiger_energy [energy [threshold_energy] [threshold_energy2]]

Sets the photon energy and the *threshold energy* of the Eiger detector. If no parameter is provided and a monochromator is in use in spec, prompts whether the current monochromator energy should be used as the photon energy.

For SIMPLON version lower than 1.8 only one threshold is available.

For SIMPLON version 1.8 or greater, two thresholds can be used. Check the Eiger documentation for details. To enable or disable a threshold use macros eiger_threshold_enable and eiger_threshold_disable.

eiger_threshold