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

Not available for SIMPLON 1.6.

Shows the current setup for energy thresholds. The enable state and energy are listed for each threshold.

eiger_threshold usage

Not available for SIMPLON 1.6.

Shows usage of the macro and exits

eiger_threshold [1|2|both|diff]

Not available for SIMPLON 1.6.

Selects threshold mode. Activate threshold 1 or 2 only, both, or activates difference mode.

eiger_threshold [1|2] energy_value

Not available for SIMPLON 1.6.

Selects energy for threshold 1 or 2

eiger_threshold energy1_value energy2_value

Not available for SIMPLON 1.6.

Selects energies for both thresholds

eiger_show_energy
Displays current energy settings in the Eiger detector including photon_energy, threshold_energy and countrate correction cutoff.
eigerls [pattern]
Lists the contents of the Eiger DCU data buffer (HDF5 files). If an argument is provided, only file names matching pattern are listed.
eiger_transfer [filename|pattern]
Transfer the file named filename or all the files matching pattern from the Eiger to the directory selected. If no parameter is given, files matching the latest acquisition prefix will be transferred. If the auto_delete option has been enabled in the eiger_menu, files are deleted from the Eiger after they are transferred.
eiger_delete filename|pattern
Delete the file named filename or all the files matching pattern from the Eiger. If the auto_delete option has been enabled in the eiger, files are automatically deleted from the Eiger when they are transferred using the eiger_transfer macro.
eiger_save [filename]
Saves the latest image acquired through the stream interface to filename (TIFF format). If no filename is provided the current prefix will be used.
eiger_read
Loads data from the latest acquired image (stream interface only) to the spec data array EIGER_data.
eigercollect [on|off]
Enables or disables collection acquisition mode. See COLLECTION ACQUISITION MODE below.
eigerplot [roi]
Selects the roi to be plotted in the EIGER collection plot during scans. If no parameters, displays a list of available rois. Only used with Eiger collection mode.

HANDLING EIGER DATA

These macros support both the filewriter and stream subsystems for handling data generated by the EIGER detector API.

The eiger_menu macro prompts for the parameters and options for saving data:

SAVING OPTIONS

Data directory for Eiger images: /tmp/data_eiger
Prefix for Eiger data files: s56_p2
Eiger save mode: [stream] writer both off
Overwrite images in stream mode: NO
Delete files from DCU after transfer: YES

FileWriter Data Handler (HDF5)

The filewriter data handler saves images from the Eiger in HDF5 format. When acquiring several images in one acquisition (see the "nimages" parameter), the images are saved in a single file. It is the responsibility of the user to transfer data from the Eiger DCU to the final disk destination. The user must also ensure the Eiger has enough free space to save images from a new acquisition.

This method is recommended for multi-image acquisitions or when HDF5 format is the required output data format.

The following macros in eiger.mac provide access to filewriter system:

eigerls [pattern]
List all the files currently on the Eiger DCU. If pattern is provided only files that match pattern will be listed.
eiger_transfer [filename|pattern]
Transfer a file with name filename, or all the files matching pattern, from the Eiger to the directory selected. If no parameter is given files corresponding with the latest acquisition prefix will be transferred. It is possible to select the auto_delete option in the eiger_menu to have the files deleted from the Eiger after they are transferred.
eiger_delete filename|pattern
Delete a file with name filename, or all the files matching pattern, from the Eiger. It is possible to select the auto_delete option in the eiger_menu to delete files from the DCU as they are transferred with the eiger_transfer macro.

Stream Data Handler (TIF)

The stream data handler sends data directly from the Eiger to the eiger_server through a dedicated socket connection. This connection is always opened to allow rapid access to data without the need to load files. Statistics and other calculations on data can be done in this way as soon as the data is produced.

Selecting stream as the Eiger save mode in the eiger_menu macro will automatically generate individual tif files for every image collected.

The prefix selected in the eiger_menu will be used to generate appropriate filename numbering during ct or scan acquisitions. All files will be saved in the selected data directory.

The following macros in eiger.mac provide access to stream system:

eiger_save [filename]
Saves latest image acquired to file with name filename. If no filename is provided the current prefix will be used.
eiger_read
Loads data from the latest acquired image to the spec variable named EIGER_data.

Monitor Data Handler

Some versions of the SIMPLON API support the monitor data handler. Data is saved in tif format in a buffer in the Eiger DCU.

When saving data, the monitor macros will check the current threshold configuration for the Eiger detector. If more than one threshold is active, saving operations will save an additional file for each active threshold. If only one threshold is active, only the default image is saved.

For all saving operations filenames are generated from the file settings selected at that moment: data_directory and prefix. The name of the generated filename(s) will include threshold number if applicable. The filename will be displayed when the eiger_monitor_save macro is invoked.

The following macros in eiger.mac provide access to monitor data handler:

eiger_monitor
Provides control over several features of the monitor system. Without parameters shows the current state of the monitor system including the buffer size and the number of images currently in the buffer.
eiger_monitor usage
Shows usage and exits.
eiger_monitor [on|off|auto]
Selects operation mode for monitor system. Parameter on activates the system, parameter off deactivates it. Parameter auto activates the monitor system while at the same time registers for automatic saving during ct, ascan and most other spec acquisition macros.
eiger_monitor list
Prints a list of all images in the monitor buffer. Image series id and image numbers in each series will be shown. For example:
eiger_monitor size <max_images>
Sets the maximum number of images in monitor buffer to max_images. Value buffer_size in SIMPLON API.
eiger_monitor save
Manually saves latest image(s) stored in the monitor system. See eiger_monitor auto for automatic data saving. The data_directory and prefix settings are also used in this case.

ROI (Region of Interest)

ROI (Region of interest) counters can be defined in SPEC to show summed up values over a certain region of the image. For this feature the macro file eiger_roi.mac has to be loaded in spec.

CONFIGURATION

Configure a Macro counter device on the Motor and Counter Device Configuration screen of the configuration editor (D key)

SCALERS        DEVICE   ADDR  <>MODE  NUM                              <>TYPE U#
 [...]
 1  YES         eiger      -            4                       Macro Counter

The DEVICE field contains must be set to eiger. Make sure you select enough counter channels in the NUM field.

Configure individual counter channels in the Scaler (Counter) Configuration screen of the configuration editor (S key)

Scaler (Counter) Configuration

Number        Name  Mnemonic  <>Device  Unit  Chan   <>Use As  Scale Factor
     0     Seconds       sec   SFTWARE     0     0   timebase          1000
     [...]
     3      EigROI    eigroi   MAC_CNT     0     0    counter             1
     4      EigMAX    eigmax   MAC_CNT     0     1    counter             1
     5      EigSUM    eigsum   MAC_CNT     0     2    counter             1

The mnemonics eigmax and eigsum are automatically recognized by the macros to hold counts for the maximum image value (eigmax) and the total image sum (eigsum). Others mnemonics can be chosen freely to hold the sum over a selected area of the image. Use the macro eiger_roi to define the area affected to the counter.

As many ROI counters as needed can be defined in this way.

COLLECTION ACQUISITION MODE

The collection feature is a special acquisition mode for collecting statistical data, such as regions of interest, while optimizing acquisition performance.

In a standard spec scan, if statistical counters are used (roi, sum, ...) and if data is collected synchronously with the acquisition process, spec must wait for the Eiger image to be processed before continuing to the next acquisition point.

If collection acquisition mode is enabled, the statistical values are calculated by the eiger_server asynchronously. The sequence of exposures continues while the statistical data is calculated and buffered in parallel. The available buffered data can be obtained at any time during the acquisition or at the end of the collection period.

When collection mode is active, the "sum" of all image pixels and the "max" pixel value in the image are automatically collected for each image. Regions of interest can also be defined.

image_par(unit, "collection_start")
Starts a collection. Statistical buffers are reset. Statistical data recording is started.
image_par(unit, "collection_end")
Ends a collection. Statistical data recording is stopped.
image_par(unit, "is_collecting")
Returns whether recording of statistical data is active (1) or inactive (0).
image_par(unit, "collection_npoints")
Returns the number of points of statistical data collected.
image_par(unit, "collection_add_roi", "roiname, rbeg, cbeg, rend, cend")

Define a new collection roi with name roiname for which integration value will be estimated for each collected image. The values rbeg (row begin), cbeg (column begin), rend (row end) and cend (column end) must be provided:

8.SPEC> image_par(0, "collection_add_roi", "e_roi,50,50,400,254")

This command is not allowed while a collection is active.

image_par(unit, "collection_roi roiname")

Returns the definition of the collection roi with name roiname:

9.SPEC> print image_par(0, "collection_roi e_roi")
50,50,400,254
image_par(unit, "collection_roi_list")

Returns the list of all statistical collection counters defined:

10.SPEC> print image_par(0,"collection_roi_list")
max,sum,e_roi,e_roi2
image_par(unit, "collection_reset")
Resets the collection roi definition. This command is not allowed while a collection is active.
image_par(unit, "collection_roi_get roiname")

Returns data collected for the collection roi with the name roiname. The data is returned in "json" format:

11.SPEC> image_par(0,"collection_add_roi", "e_roi2,50,50,400,254")

12.SPEC> image_par(0,"collection_start")

13.SPEC> for (i = 0; i < 10; i++) eigerct 0.1

14.SPEC> print image_par(0,"collection_npoints")
10

15.SPEC> print image_par(0,"collection_roi_get sum")
[0, 0, 0, 6, 0, 0, 0, 0, 2, 0]

16.SPEC> print image_par(0,"collection_roi_get e_roi2")
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
eigercollect [on|off]

Enables or disables the use of the collect feature. See detailed description above.

When collection acquisition mode is enabled, statistical data is acquired asynchronously when in scans for improved performance. For the standard counting macros, acquisition is synchronous.

During asynchronous acquisitions, spec will not wait for the image to become available before proceeding to the next acquisition point. ROI counter values calculated from the image will show a value of -1. However, the values for all such counters will be collected by the server and retrieved by spec when they become available.

In addition, reading image data into shared memory is also disabled during scans when collection mode is enabled.

However, images will still be saved is the "stream/TIFF" or "filewriter/HDF5" options are active.

When using collection mode, spec will open a second plot window (if x11filt is selected for plotting). The counter in this second window can be selected with the macro eigerplot (see below).

When using the collection/asynchronous mode, spec will gather the data for all eiger counters in the two-dimensional spec data array EIGER_scand. The first column in EIGER_scand. contains the position of the motor being scanned or the time value for a time scan.

The array EIGER_collect is also filled during scans in collection mode and is used by splot. EIGER_collect contains only two columns: motor position and values for the roi counter selected by eigerplot.

When using splot, use the SPEC menu to select for display EIGER_scand and/or EIGER_collect.

VERSION HISTORY

Version 2.1 - Released August 2020
Adds support for energy threshold management and monitor system for threshold image saving.
Version 2.0 - Released June 2020
Adds support for Eiger2 and SIMPLON Version 1.8.0.
Version 1.0 - Released November 2019
Support for Eiger and SIMPLON Version 1.6.0.

SEE ALSO

server_hdw

dectris.com

SIMPLON API Reference

Eiger User Manual