Dectris PILATUS3 R User manual

DECTRIS Ltd.
5400 Baden
Switzerland
www.dectris.com
User Manual
PILATUS3
This user manual is valid for the following PILATUS detectors:
PILATUS3 6M | PILATUS3 2M | PILATUS3 1M
PILATUS3 300K | PILATUS3 300K-W | PILATUS3 200K
Version:
V2.1

User Manual. PILATUS3. Version: V2.1 2/62
Table of Contents
1. Document History 4
1.1. Current document 4
1.2. Changes 4
2. How to use this Manual 5
2.1. Address and Support 5
2.2. Explanation of Symbols 6
2.3. Convention for Commands 6
2.4. Disclaimer 7
3. Warnings 8
4. System Description 9
4.1. Overview 9
4.2. Hardware 10
4.3. Software 14
4.3.1. Overview of Camserver 14
4.3.2. Description of the File Structure and Configuration Files on the
PILATUS3 Detector Server 14
4.3.3. Overview of TVX 15
4.3.4. Configuration Files for TVX 15
5. Quick Start Guide 16
6. Control the Detector 18
6.1. From the Detector Server 18
6.2. From a Specific Environment 19
6.2.1. Steps to Bring Up a PILATUS3 Detector in a New Environment 19
6.2.2. Testclients 20
7. How to use the PILATUS3 Detector through Camserver 21
7.1. Main Commands 21
7.1.1. Variables 22
7.2. Image formats 23
7.3. External Triggering 25
7.3.1. External Trigger Mode 25
7.3.2. External Multi Trigger Mode 27
7.3.3. External Enable Mode 28
7.3.4. Multiple Exposure Mode 30
8. Trimming the Detector 31

3
8.1. Principle 31
8.2. Trimming Method 31
8.3. Set the Threshold with more Control 32
9. Bad Pixel Mask and Module Gaps 34
9.1. Using the Bad Pixel Mask 34
9.1.1. Adding new Bad Pixels to the Mask 34
9.1.2. Make a new Bad Pixel Mask from an Uniform Illumination 35
9.2. Flag the Module Gaps 36
10.Adjust Crystallography Parameters 37
11.Flat Field Image 38
11.1.Using the Flat Field Correction Image in Camserver 38
12.How to Use the PILATUS3 Detector through TVX 39
12.1.Description of the Image Display 42
12.2.Analysis commands 46
12.3.Mask files 48
12.4.User defined commands 49
12.5.Glossary files 50
12.6.Example 50
13.Factory Calibration and Correction 51
14.Camserver Commands 52
15.Camserver Test Client 61

User Manual. PILATUS3. Version: V2.1 4/62
1. Document History
1.1. Current document
Version
Date
status
prepared
checked
released
2.1
20.06.2014
released
SB, LK
PH
SB
1.2. Changes
Version
Date
Changes
1.0
01.05.2013
First version
1.1.1
12.06.2013
Adapted CD
2.0
14.02.2014
Complete revision, final CD
2.1
20.06.2014
Moved system specific information to Technical
Specifications. Minor changes.

5
2. How to use this Manual
Before you start to operate the PILATUS3 detector system please read the User Manual and
the Technical Documentation included in the documentation package carefully.
This document has been designed for the PILATUS3 detector systems.
2.1. Address and Support
DECTRIS Ltd.
Neuenhoferstrasse 107
5400 Baden
Switzerland
Phone: [phone]
Fax: + 41 56 500 21 01
Website:
www.dectris.com →support →Technical Notes →PILATUS
www.dectris.com →support →FAQ
www.dectris.com →support →Problem Report
Email:
[email protected]
Should you have questions concerning the system or its use, please contact us via phone,
mail or fax.
Do not ship the system back before you receive the necessary
transport and shipping information!

User Manual. PILATUS3. Version: V2.1 6/62
2.2. Explanation of Symbols
Symbol
Description
Important or helpful notice
Caution.
Please follow the instructions carefully to prevent
equipment damage or personal injury.
2.3. Convention for Commands
Example
Description
cd ..
Shell commands are written in blue and italic
ExpTime
Camserver commands are in written italic
Disp
TVX commands are written in bold italic
exposem
TVX macros are written in underlined, bold, italic

7
2.4. Disclaimer
DECTRIS Ltd. has carefully compiled the contents on this manual according to the current
state of knowledge. Damage and warranty claims arising from missing or incorrect data are
excluded.
DECTRIS Ltd. bears no responsibility or liability for damage of any kind, also for indirect or
consequential damage resulting from the use of this system.
DECTRIS Ltd. is the sole owner of all user rights related to the contents of the manual (in
particular information, images or materials), unless otherwise indicated. Without the written
permission of DECTRIS Ltd. it is prohibited to integrate the protected contents published in
these applications into other programs or other Web sites or to use them by any other means.
DECTRIS Ltd. reserves the right, at its own discretion and without liability or prior notice, to
modify and/or discontinue this application in whole or in part at any time, and is not obliged to
update the contents of the manual.

User Manual. PILATUS3. Version: V2.1 8/62
3. Warnings
Please read these warnings before operating the detector system.
Before turning the power supply on, check the supply voltage against the label on the
power supply. Using an improper main voltage will destroy the power supply and
damage the detector.
Power down the detector system before connecting or disconnecting any cable.
Make sure the cables are connected and properly secured.
Avoid pressure or tension on the cables.
The detector system should have enough space for proper ventilation. Operating the
detector outside the specified ambient conditions could damage the system.
The detector is not specified to withstand direct beam at a synchrotron. Such
exposure will damage the exposed pixels.
Place the protective cover on the detector when it is not in use.
Opening the detector or the power supply housing without explicit instructions from
DECTRIS Ltd. will void the warranty.
DO NOT INSTALL ADDITIONAL SOFTWARE OR CHANGE THE OPERATING
SYSTEM on the detector server except for necessary network configurations.
DO NOT TOUCH THE ENTRANCE WINDOW OF THE DETECTOR.

9
4. System Description
4.1. Overview
A PILATUS3 detector system consists of the following components:
Detector
Detector server
Cooling unit
PILATUS Processing Unit (depending on the system)
High-bandwidth connection
PILATUS
Detector Cooling
Unit
(optional)
Detector
Server
PILATUS
Processing
Unit (PPU)
(optional)
TCP/IP
Client
(local or remote)
TCP/IP
Client
(local or remote)
10 Gbit Ethernet point-to-point connection
Closed circuit
Max. 3 bar, 23°C

User Manual. PILATUS3. Version: V2.1 10/62
4.2. Hardware
DECTRIS X-ray detector systems operate in "single photon counting" mode and are based on
the newly developed CMOS hybrid pixel technology. The main difference with respect to
existing detectors is that the X-rays are directly transformed into electric charge (Figure 1)
and processed in the CMOS readout chips. This new design has no dark current or readout
noise, a high dynamic range of 20 bits (0:1'048'573), a read out time of less than a 1 ms, a
frame rate of up to 500 images/s and an excellent point spread function of 1 pixel. The
quantum efficiency depends on the silicon sensor thickness; however the detectors can be
used for energies of up to 36 keV or more. The count rate is greater than 1x107/s/pixel,
enough to perform many experiments using the high flux of modern synchrotron light sources.
However, the detector cannot withstand a direct synchrotron beam.
Figure 1. Principle of direct detection.
A DECTRIS Ltd. hybrid pixel detector is composed of a silicon sensor, which is a two-
dimensional array of pn-diodes processed in high-resistivity silicon, connected to an array of
readout channels designed with advanced CMOS technology (Figure 2). Each readout
channel is connected to its corresponding detecting element through a microscopic indium
ball, with a typical diameter of 18 m. This connection process is called ‘bump-bonding’.
Figure 2. The detector module, the basic element of all DECTRIS Ltd. area detector systems

11
The great advantage of this approach is that standard technologies are used for both the
silicon sensor and the CMOS readout chips, which guarantees highest quality. Both
processes are optimized separately, as the best silicon substrates for X-ray detection and for
high-speed/high-quality electronics are very different. Moreover, the small size of the pixel
and the interconnection results in a very low capacitance, which has the beneficial effect of
reducing the noise and power consumption of the pixel readout electronics.
X-ray data collection can be improved with detectors operating in single photon counting
mode. A hybrid pixel which features single photon counting comprises a charge-sensitive
preamplifier (CSA), which amplifies the signal generated in the sensor by the incoming X-ray,
and a comparator (Comp), which produces a digital signal if the incoming charge exceeds a
pre-defined threshold. The comparator feeds a 20 bit counter, which then leads to completely
digital storage and noiseless readout of the number of detected X-rays in each pixel (Figure
3).
Figure 3. Design of each pixel. See text for details.
The fundamental unit of the DECTRIS Ltd. detectors, the module, consists of a single fully
depleted monolithic silicon sensor with an 8 x 2 array of CMOS readout chips bump-bonded
to it. Each sensor is a continuous array of 487 x 197 = 94965 pixels without dead areas and
covers an active area of 83.8 x 33.5 mm2. The readout chips are wire-bonded to the
underlying print which is glued to the mounting bracket. Together with its readout control
electronics the sensor with readout chips forms the complete module (Figure 2).
The novel PILATUS3 X-ray features an instant retrigger capability, improved high-rate
counting performance, reduced readout time. Instant retrigger capability results in non-
paralyzable counting and allows for enhanced count rate correction. In addition, the
PILATUS3 detectors boast improved high-rate counting performance thanks to various
enhancements such as counter overflow handling, improved pixel uniformity and reduced
crosstalk. The shorter readout time allows for increased frame rates.

User Manual. PILATUS3. Version: V2.1 12/62
Instant retrigger technology with adjustable dead time is a photon counting imaging method
that results in non-paralyzable counting and achieves an improved high-rate counting
performance. In a conventional single-photon counting X-ray detector, the charge pulses
generated by impinging photons are counted by digital circuits. Simultaneously generated
pulses can pile up and as a result, photon counts can be lost. At high photon fluxes, pulse
pile-up significantly affects the observed count rate and can lead to complete paralyzation of
the counting circuit. In PILATUS single-photon counting hybrid pixel X-ray detectors, count
rate correction is applied in order to compensate for the counting loss at high count rates.
However, counter paralyzation limits the maximum usable count rate. In PILATUS3 detectors,
the instant retrigger technology re-evaluates the pulse signal after a predetermined dead time
interval after each count and is able to retrigger the counting circuit should a pulse pile-up
occur. The respective dead time interval is adjustable and is equivalent to the width of one
single photon pulse. This results in non-paralyzable counting and allows for enhanced count
rate correction so as to achieve improved data quality at high count rates.
Figure 4: Signal waveforms illustrating instant retrigger technology.
Figure 4 illustrates the principle of instant retrigger technology. The first diagram shows the
signal pulses generated by impinging photons and the effective discriminator threshold level
for single photon counting. The pulse signal includes a series of one single pulse, a pile-up of
two pulses and a pile-up of multiple pulses. The second diagram shows the corresponding
digital discriminator output signal that triggers the counting circuit. The third diagram shows
the corresponding counts being registered by a conventional single photon counting X-ray
detector, clearly illustrating that counts are lost in the case of pulse pile-up and that this can
lead to paralyzation. The fourth diagram shows the respective dead-time generator output
signal provided by a single photon counting X-ray detector with instant retrigger technology.
Here, a predefined dead time interval is started whenever a count has been registered. The
fifth diagram shows the corresponding counts being registered, including potential retriggering
of the counting circuit after the dead-time interval after each count. This clearly illustrates that

13
pulses are counted more accurately in the case of pile-up and that counting is non-
paralyzable.

User Manual. PILATUS3. Version: V2.1 14/62
4.3. Software
The PILATUS3 detector system is controlled via Camserver.
4.3.1. Overview of Camserver
Camserver is a freestanding program that controls the PILATUS3 detector and provides a
simple user interface for "atomic" (single function) commands. It is intended to provide a
minimal, but fully functional, low level interface to camera hardware.
On invocation, Camserver takes a single command-line argument, the path to its resource
file, by default called 'camrc'. Camserver will also use the same path to open its debugging
file, 'camdbg.out'.
A major feature of Camserver is to accept socket connections from a high level controller,
which can provide high level services to this or other cameras. (see section 7 and 14 for more
details). The interface is a simple text-based message passing system. Images - the ultimate
product of a working area X-ray detector - do not pass through the socket interface, but are
written to a configurable location (e.g., a NFS mount) where any program can access them.
4.3.2. Description of the File Structure and Configuration Files on the PILATUS3
Detector Server
In the default setup, all necessary data for the use of the PILATUS3 detector system is in the
directory /home/det/p2_det.
Directory
Sub Directory
Description
config
Configuration Data
cam_data
Definitions of the camera /
calibrations
calibration
All calibration details
including Mask files
camstat
Status of the detector
images
Default image directory
programs
Program code for Camserver
Important configuration files are listed in the followings table. The directory is given relative to
the default path /home/det/p2_det/.
File
Directory
Description
camrc
./
configuration file for
Camserver
camdbg.out
./
Debug file for Camserver
p2det.set
config/cam_data
Startup file for Camserver

15
4.3.3. Overview of TVX
TVX is a free, open source, data acquisition and control software suite tailored to X-ray
science. TVX is an attempt to provide a flexible user interface that is easily adapted to control
a broad range of 2-D X-ray detectors as well as a powerful collection of analysis tools.
The suite operates by distributing the tasks of data analysis and hardware control between
two separate programs. TVX contains a user interface and analysis tool suite. TVX
communicates over a TCP/IP connection to Camserver.
4.3.4. Configuration Files for TVX
In the default setup, all data for the use of the PILATUS3 detector system are in the directory
/home/det/p2_det. The following directories are relative to it.
Directory
Sub Directory
Description
programs
Program code for TVX and
Camserver
graphs
Default directory for TVX
graphs
correct
Masks for statistical analysis
in TVX
docs
Documentation of TVX and
Camserver
Important configuration files are listed in the followings table. The directory is given relative to
the default path /home/det/p2_det/.
File
Directory
Description
tvxrc
./
configuration file for TVX
default.gl
config
Startup glossary of TVX
det_spec.gl
config
Detector specific parameters
for TVX
user.gl
config
User shortcuts for TVX
startup.gl
config
Final startup glossary
executing detector self-tests

User Manual. PILATUS3. Version: V2.1 16/62
5. Quick Start Guide
Before you turn on the system, make sure you have read this manual, the technical
specification, and set up the detector accordingly.
Turn on the detector server.
Log in procedure:
User and password: see additional sheet in your user documentation
Open a shell.
Change to the p2_det directory. All following paths are given relative to this!
cd /home/det/p2_det 
Run TVX by typing
./runtvx 
After the initialization (~20 s) you should get the following screen:
Figure 5. Startup screen after executing ./runtvx

17
The command ../runtvx is a shell script which starts the programs Camserver (window
on the left side of Figure 5) and TVX (window on the right side of Figure 5) as well as
manages all log files.
During startup the detector sets several parameters in the startup scripts (details in
6.1).
Once two images (green and blue) appear on the screen the detector is ready to
operate. In Figure 5 only one (blue) is visible since it is above the other (green) one.
Both terminals (TVX and Camserver) have their prompt, indicated by an asterisk
symbol (*).
The detector is now ready for operation with Copper (8keV) radiation. If you would like
to change to other energies please see section 8.
To take an image you can type:
expose 10 
in the TVX window, where 10 is the exposure time in seconds.
Further information:
Details on how to control the detector from a specific environment (e.g. at a synchrotron)
can be found in section 6.2.
Details on how to trigger the detector with an external signal can be found in section 7.3.
For information concerning the dead pixels and gaps please see section 9.

User Manual. PILATUS3. Version: V2.1 18/62
6. Control the Detector
6.1. From the Detector Server
The PILATUS3 detector can be controlled from the delivered detector server. Just follow the
instructions in the Quick Start Guide (Section 5) to start up the detector.
The runtvx command is a shell script which starts the actual programs: Camserver and TVX.
It also handles the log-files which can be found in the p2_det directory.
During the Camserver startup a connection to the detector is established and verified.
The TVX startup is carried out via the file called default.gl. This is a so called glossary file
(*.gl), which is a convention used for files which are processed by TVX.
This default.gl file (stored in "$HOME/p2_det/config) makes several definitions (short-cuts)
which can be used further on in TVX.
For example the exposem command makes an endless loop and writes images in a
temporary file (see also section 12). This is a simple live-view tool of TVX.
At the end of the startup glossary three more glossaries are called. The first one (det_spec.gl)
loads detector specific parameters such as camera size and number of modules. The second
one (user.gl) is used to enter user short-cuts once you start to define your own ones. The last
one (startup.gl) sets voltages on the actual X-ray sensitive elements and carries out a test of
the digital part and the analog part of each pixel. The last two tests are done with the TVX
definitions rbd (read back detector) and calibdet, respectively. The results are shown in a
green (digital test with 1000 counts loaded into the counter of each pixel) and a blue (analog
test with 100 simulated pulses fed into each pixel) image. These two images show up
automatically at the end of the startup procedure and verify the full functionality of the
detector.

19
6.2. From a Specific Environment
In the previous section the stand alone operation is shown. However, often there is a need to
integrate the detector in an existing environment.
The PILATUS3 detector can be easily integrated in any system. To do this, one has to send
commands through a socket connection to Camserver. Any client can connect to Camserver
via a socket connection, and issue plain text commands. However, only the first connection
will get full control and can execute commands. All following connections will only have read
access. The command syntax (see section 14) over the socket is identical to the syntax to be
typed directly in the Camserver window. Thus, direct typing is helpful for testing.
The reply from Camserver (acknowledgement) consists of a command index number,
followed by a space and either "OK" or "ERR", followed by another space and possibly a
message. The acknowledgement arrives after the requested action is completed, typically in
1-2 ms; some commands, such as trimming commands (e.g. SetCu), take longer, especially
for a big detector. All acknowledgements end in 0x18 (ASCII 'CAN') without a newline; there
may be internal newlines in long messages.
Since there is no terminating linefeed, MS Windows sockets must be opened in binary mode;
this is not a consideration for UNIX-like systems.
Because of the socket connection protocol, the camera hardware and server can reside on a
different machine from the high level controller.
Camserver implements a token mechanism to prevent more than one outside process from
having control over the hardware. The Camserver window has full control at all times.
There is a debug facility to help with setting up the interface. If you type "dbglvl 5", the file
'camdbg.out' will contain many messages, including the exact contents of socket messages.
Be sure to set "dbglvl 1" (the default) before doing real work, else 'camdbg.out' can grow
without limit. If there are difficult problems with the detector, a run with "dbglvl 6" reproducing
the error can be helpful for diagnosis. Simply capture 'camdbg.out' and send it including a
description of the issue to DECTRIS Ltd support.
The Camserver program of the PILATUS3 detector provides a simple to use interface for
either EPICS or SPEC. Several clients for these protocols have been written at the Swiss
Light Source (SLS) at the Paul Scherrer Institute (PSI) and by Mark Rivers of the University of
Chicago:
http://cars.uchicago.edu/software/epics/areaDetector.html
6.2.1. Steps to Bring Up a PILATUS3 Detector in a New Environment
1. If needed, change the hostname to be compatible with the local network.
2. Set up the detector on the network, if needed. Note that the detector does not require
an external network.
3. Configure Camserver, and the client TVX, as needed. Probably the defaults will be
adequate, but many parameters can be adjusted in "camrc", and "tvxrc", both of which
reside in the $HOME/p2_det directory.
4. Start the detector by ./runtvx in the $HOME/p2_det directory.
5. If you are using your own client (see section 6.2.2) for Camserver (e.g., SPEC or
EPICS) disconnect TVX (type “disconnect” in TVX). This can be done automatically
in the startup script after the test images are shown. Connect your client and begin
issuing commands (see section 14).
6. Alternatively it also possible to start only Camserver with the command ./camonly in
the $HOME/p2_det directory.

User Manual. PILATUS3. Version: V2.1 20/62
6.2.2. Testclients
The detector can be controlled from any client which opens a socket connection to
Camserver.
Make sure TVX is disconnected (type “disconnect” in TVX) before
you connect your own client.
The most simple client perhaps is “telnet”. It is possible to test it on the detector server itself
by executing telnet localhost 41234. Here localhost is the “IP” of the detector and 41234 the
port where Camserver is listening to.
A basic test client written in C can be found under section15.
For more information please contact DECTRIS Ltd. at [email protected].