DESCRIPTION

The spec macros are for the Dectris Pilatus models 100K, 200K, 300K and 1M that use a camserver interface based on the TVX software. Newer Pilatus models use a different software interface.

The macros use spec's macro hardware feature to implement the control. See the spec mac_hdw help file for details.

IMAGE ACCESS

The Pilatus image files are created on the Pilatus control computer, which may not be the same computer on which spec runs. In order to access the image files from spec (to calculate regions of interest, for example), the image directory on the Pilatus computer should be mounted on the local computer running spec. The usual way is with the NFS facility. The Linux package nfs-common may need to be installed to enable use of NFS.

To configure NFS, on the Pilatus computer, add an entry to the file /etc/exports along these lines:

/data/images *(rw,sync,no_subtree_check,all_squash,anonuid=0,anongid=0)

where /data/images is the directory on the Pilatus computer where the images are written. The above allows any computer on the network to mount the image directory and allows any user to create or modify files. Those permissions can certainly be tightened. See the Linux man page for exportfs for details on the syntax. Importantly, the Pilatus spec macros assume the user running spec on the local computer has permission to create directories on the remote computer.

On the local computer, the NFS mount is accomplished with a command such as:

mount -t nfs pilatus_host:/data/images /data/images

The last path is a folder on the local computer. The pilatus_host is an IP address or resolvable host name of the pilatus computer. The IP address can be associated with a host name in the /etc/hosts file. The mounting can be made automatic with a line in /etc/fstab such as:

pilatus_host:/data/images       /data/images   nfs

Note, symbolic links may well be used on both the local and remote computer to specify alternate paths to the same image directory. The path names could well differ between the two computers.

READING TIFF

In order to read the .tif image files, spec must be compiled with the optional tiff developer library. The package containing the library is not usually installed by default on the various Linux platforms. On an Ubuntu and Debian type Linux systems the package is called libtiff-dev. On CentOS and Rocky type systems the package is called libtiff-devel. To install on Ubunutu, for example, use:

apt-get install libtiff-dev

To include the library with spec, flags must be set, either by editing the install_data file or entering values when using spec's interactive Install script. The install_data lines are:

site_flags=-DUSING_LIBTIFF=1
site_lib=-ltiff

After adding the flags for the tiff library, reinstall spec, using the -C flag to make sure spec is relinked. See the spec install help file for details.

CONFIGURATION

Use the spec config macro to run the edconf hardware configuration editor to add a line on the Acquisition screen of the sort:

MCA (1D) and Image (2D) Acquisition Device Configuration

 Image        DEVICE   ADDR  <>MODE                       <>TYPE
0  YES       pilatus ipname                   Macro Image Device

where ipname is the resolvable host name or IP address of the computer running camserver for the Pilatus. Use the p command to configure custom parameters for the Pilatus:

Custom Parameters for Image 0 "Macro Image Device"      2/2 configured

NAME                      VALUE
model                     200k
PILATUS_base_dir          /data/images

Possible values for model are 100k, 200k, 300k and 1M. The values are case insensitive. If the "model" parameter is not configured or not recognized the macros default to using the image size of the 200K model. The value for "PILATUS_base_dir" can also be configured in the macros.

To use the Pilatus, the pilatus.mac file needs to be read into spec. A command such as:

qdo /usr/local/lib/spec.d/macros/pilatus.mac

will work. If /usr/local/lib/spec.d/macros is in the DO_DIR list of directories (a colon separated list of directories configured in the mstartup macro), a simple:

qdo pilatus.mac

will do. Be sure to type reconfig after reading the macros to initialize the connection to camserver on the remote computer.

The Pilatus macros are written to work with the standard acq macros included with the spec distribution. See the acq help file for more details.

When spec has connected to the Pilatus detector, the standard counting and scanning macros can be configured to read the Pilatus during data acquisition. Use the acq_setup macro to set up whether to read the Pilatus during scans and to configure regions of interest. Use the pilatus_setup macro to configure Pilatus parameters.

Consider these acq_setup configuration options:

Image (PSE_MAC_IMG pilatus unit 0)

Program image device with count time? YES

Read image data during scans? YES

Save image data during scans? YES

How should the image data be saved? Separate file(s)

Template source for image data file names? User defined

Template for MCA/image data file? %d*-%4S*/img-%4N*

How to distribute data? ---

Create a splot window to display the image data? YES

Read image device during updated counting? NO

Prefix for custom device acquisition macros? pilatus

The Pilatus should be configured to be programmed with the count time. The read-during-scans configuration needs to be selected if interested in real-time plots. If ROIs are configured the Pilatus will be read in any case. Note, "reading" for the Pilatus means reading the .tif files written out by camserver.

The option to save image data should be selected in order to configure a template for the image files. The template is with respect to the PILATUS_base_dir directory. The example given creates a subfolder for each scan (%S*) with a name prefixed by the configured data file template (%d*) from mstartup. A possible data file template could be exp_%F where the %F expands to the current date, for instance exp_2026-04-20. With the above, each scan will create a new folder using the file template and the scan number, such as exp_2026-04-20-0012/. The images in that folder will include the point number of the scan via %4N. See the newfile help file for more on templates.

The selection to create a splot window will automatically display each image as it is taken.

Very importantly, the prefix for custom macros must be set to pilatus for the spec Pilatus acquisition to work.

The acq_setup macro also configures the region of interest (ROI) counters. There is no need to add ROI counters to the config file. The configuration appears as:

How many ROI counters? 2

Mnemonic (ROI 0)? ir0_0

Name (ROI 0)? IROI 0.0

Operation (ROI 0)? [sum] ave max min

First Row (ROI 0)? 0

Last Row (ROI 0)? -1

First Column (ROI 0)? 0

Last Column (ROI 0)? -1

Each counter has a mnemonic and name, just as the config file counters. The automatically generated values can be customized. The ROI operations are sum, average, maximum and minimum. With the row and column specifications, a negative number counts from the end. A -1 is the last row or column.

The pilatus_setup macro (or simply pilatus) has options related to the detector configuration and to how to save the data.

Save each image to a new file: YES

File for images when saving is off: tmp_img.tif

Directory for images: data/images

Template for image files (not during scans): %d*-seq/pil_img

Sequence number for next image (not during scans): 7

Photon energy: 8048 ev

Value for gap pixels: [0] -1

If "save each image" is enabled, each count period, whether from ct or during a scan, creates a new file. If the option is turned off, each image will be saved to the same file, named in the next option. Even if all images are saved into the same file, spec can still display the image using the Python splot package, and spec can still calculate ROIs.

The image directory is probably an NFS mount and is where the Pilatus writes its files. The template is for image files made with the ct macro or similar, not during scans. (The template for image files made during scans is configured in acq_setup.) A sequence number will be added to each file. The macros automatically reset the sequence number to zero when the directory containing the images is changed. One can also set the sequence number here. Note, the Pilatus camserver will overwrite existing files with the same name.

spec's standard disable/enable macros can be used to control whether spec access the Pilatus. The arguments to the macros are based on the unit number of the Pilatus. For unit number 0, the commands would be disable image0 and enable image0. See the disable help file for details.

INTERNAL MACROS

pilatus_setup (or pilatus_menu or simply pilatus) prompts user for the few configurable parameters.

pilatus_config(), pilatus_cmd() and pilatus_par() implement the macro hardware image device. The config file should have a nonstandard optional parameter for the Pilatus "model". If it is missing, the macro defaults to the image size for the 200K model.

The pilatus_cmd() macro implements "run", "halt", "get_status" and "read".

The "get_status" checks if the image acquisition is finished by looking for an asynchronous reply from camserver using the sock_par() "queue" option to see if a message has been sent. (The server sends a "7 OK" message when the acquisition finishes.)

The "read" is done using spec's fmt_read() function, which calls functions in the linked-in libtiff.a. A problematic file can result in a program crash. The macros check that at least the .tif file is the right size before attempting to read.

The macros pilatus_scan_head() and pilatus_precount() are called from the standard acquisition macros. A pilatus_save_acq() is also defined. It does nothing but must exist to avoid the macros writing the image data to an ASCII file.

pilatus_scan_head() adds header information to the standard spec data file.

pilatus_precount() creates file names to send to the camserver process using the configured templates. The macro also creates directories as needed, for example, when the templates include scans numbers or date/time parameters as part of the directory names.

The pilatus_info macro queries camserver and displays most of the available information about the current Pilatus configuration in a more or less as-received format.

GLOBALS

PILATUS_addr - IP address or resolvable host name

PILATUS_unit - Unit number from config file

PILATUS_base_dir - Where the Pilatus image directory is mounted

PILATUS_rem_filename - File path wrt PILATUS_base_dir

PILATUS_filename - File path wrt local computer

PILATUS_seq - Sequence number for "ct" images

PILATUS_seq_prefix - Sequence template (minus sequence number)

PILATUS_seq_dir - Directory for "ct" images

PILATUS_seq_dir_prev - Previous directory (for resetting seq num)

PILATUS_saving - Set if saving new files for each acquire

PILATUS_tmp_filename - File when not using new files

PILATUS_size - Expected size of .tif files

PILATUS_photon_energy - Incoming photon energy

PILATUS_gap_fill - Value for gap pixels

pilatus_debug - If enabled, doesn't access sockets

MACROS

pilatus

pilatus_menu

pilatus_setup

pilatus_defaults

pilatus_connect()

pilatus_send(cmd, progress)

pilatus_config(num)

pilatus_cmd(mne, cmd, p1, p2)

pilatus_par(num, key, how, par)

pilatus_scan_head(id, unit, filename)

pilatus_precount(unit, filename)

pilatus_save_acq(id, filename, arr)

PILATUS_usable

pilatus_run(t)

pilatus_wait()

pilatus_get_energy()

pilatus_info