Table of Contents 1 Document History ..................3 1.1 Changes ....................3 2 How to use this Manual ................. 4 2.1 Address and support ................4 2.2 Explanation of Symbols ................4 2.3 Convention for Commands ..............5 2.4 Disclaimer ....................5 3 Warnings .......................
Page 3
12 How to Use the Pilatus Detector through TVX .......... 37 12.1 Description of the Image Display ............40 12.2 Analysis commands ................44 12.3 Mask files ................... 45 12.4 User defined commands ..............47 12.5 Glossary files ..................48 12.6 Example .....................
1 Document History Actual document Version Date status prepared checked released 01.05.2013 released PS, BS 1.1 Changes Version Date Changes 31.08.2007 Various improvements 06.02.2009 Various improvements 1.2.1 28.09.2010 Various improvements 23.08.2011 Major revision 01.05.2013 Various improvements...
Before you start to operate the PILATUS detector system please read this manual thoroughly. The user manual and the technical specification together form the user documentation. 2.1 Address and support DECTRIS Ltd. Neuenhoferstrasse 107 5400 Baden Switzerland Phone: +41 56 500 21 02 Fax: + 41 56 500 21 01 Email: support@dectris.com...
DECTRIS bears no responsibility or liability for damage of any kind, also for indirect or consequential damage resulting from the use of this system. DECTRIS is the sole owner of all user rights related to the contents of the manual (in particular information, images or materials), unless otherwise indicated.
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 will void the warranty. The Linux operating system, on the DETECTOR SERVER has a customized Kernel to improve data throughput.
Figure 1. Overview of the PILATUS detector system setup (Monitor or laptop are not included). 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...
Page 9
Figure 2. Principle of direct detection. A DECTRIS 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 3).
Page 10
Figure 3. The detector module, the basic element of all DECTRIS area detector systems 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.
Page 11
The fundamental unit of the DECTRIS 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...
4.3 Software The operating software for the PILATUS detector system consists of two components: TVX Data analysis software and control program Camserver Operating software for the detector hardware These two software packages are normally installed on one detector server and communicate with each other through an internal socket connection.
4.3.1 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.
4.3.3 Description of the File Structure and Configuration Files on the Pilatus Detector Server In the default setup, all data necessary for the use of the PILATUS 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...
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 ●...
Page 16
Details on this command can be found in section 8. For a finer control you can use the SetThreshold command (see section 8.3). For more specific questions and detailed advice, please contact DECTRIS Ltd. for support. Note that the SetEnergy command takes a relatively long time. On a large multi module system it can take up to 2 minutes.
6 Control the Detector 6.1 From the Detector Server The Pilatus 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. runtvx command is a shell script which starts the actual programs: Camserver and TVX.
"dbglvl 6" reproducing the error can be helpful for diagnosis. Simply capture 'camdbg.out' and send it to DECTRIS. The Camserver program of the PILATUS detector provides a simple to use interface for either EPICS or SPEC. Several clients for these protocols have...
41234 the port where Camserver is listening to. A basic test client written in C can be found under section15. Another test client, called "camclientt" in "p2_det/programs/tvx/camera" can also be used to issue commands to Camserver. For more information please contact Dectris at support@dectris.com.
7 How to use the Pilatus Detector through Camserver Camserver is a completely freestanding program that controls the 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.
7.1.1 Variables The following variables can be viewed just by typing them; all times are in seconds. Variable Description NImages [N] Query or set the number of images in a sequence. ExpTime [time] Query or set the exposure time. ExpPeriod [time] Query or set the exposure period for serial exposures.
Page 22
.img raw data format no extension or raw data format misspelled Of these four image formats .tif, .edf, and .img are uncompressed and .cbf is the only (lossless) compressed format . The .cbf and .edf headers are pure text and therefor human-readable. The .tif headers are encoded, so only the comment section is human-readable.
7.3 External Triggering External triggering can be separated into three different modes: External Trigger: triggers a predefined series of commands after the detector receives a positive edge. External Multitrigger: triggers each exposure with an external pulse, but times the exposures using the internal timer. ...
interrupted by transmitting a 'K' to Camserver over the socket connection. The exposure time and exposure period still have to be set to the approximate trigger structure. If the exposure time is longer than the DMA timeout (see above) the polling method is enforced.
Page 25
Figure 8. Oscilloscope trace of an external trigger. Orange: enable signal of the detector; Green: trigger. In Figure 8 the upper trace is the exposure (enable) signal, the lower trace is from the pulse generator being used as a trigger. For this external trigger, “NImages”...
7.3.3 External Multi Trigger Mode External multi trigger mode is started with the command “ExtMTrigger imagename.tif” where imagename.tif is the name of the images you wish to be taken. The image name will be imagename_00000.tif unless otherwise specified. If NImages >1 the image number will be incremented for each image in the series.
7.3.4 External Enable Mode External enable mode is started with the command “ExtEnable imagename.tif” where imagename.tif is the name of the images you wish to be taken. The first image name will be imagename_00000.tif unless otherwise specified. If NImages >1 the image number will be incremented for each image in the series.
Page 28
Figure 11. Oscilloscope trace of the typical delay between enable signal and exposure. Orange: enable signal of the detector; Green: trigger.
7.3.5 Multiple Exposure Mode This mode is useful to capture data from a rapidly repeating event which generates only a few X-rays per pixel for each event, such as pump- probe experiments. For example, it is possible to synchronize to the bunch structure of a storage ring providing that an appropriate gate is available from the ring control system.
8 Trimming the Detector 8.1 Principle PILATUS detectors possess an adjustable energy threshold which has to be set due to the working principle of the detector. This threshold is controlled by the comparator voltage of the detector chip. Furthermore, the threshold of every pixel can be individually trimmed with six trim bits (6-bit DACs) which allow 2 = 64 different values.
8.3 Set the Threshold with more Control In order to have more control over the threshold the SetThreshold command can be used. Background: The detector systems require that an energy threshold is set. This threshold is usually set to 50% of the incoming X-ray energy for reasons which are explained below.
Page 32
Command Description SetThreshold gain SetThreshold - set gain (energy range) and threshold threshold energy Usage: SetThreshold [[gain] threshold] 1) if parameters are omitted, the current settings are shown 2) gain is 'highG', 'midG' or 'lowG' 3) if gain is omitted, the previous setting is retained 4) threshold is in eV 5) this command builds a script in "/tmp/setthreshold.cmd"...
9 Bad Pixel Mask and Module Gaps During factory calibration the bad pixels (non-responding or noisy) are determined and stored in a tif image. This image contains 0 for good pixels and 1 for bad pixels. Once the bad pixel mask is loaded, bad pixels are flagged with -2 in the final image.
9.1.2 Make a new Bad Pixel Mask from an Uniform Illumination If you expose the detector with a flat field you can use this image to create a new mask with TVX by defining upper and lower limits. Pixels in the detector that are either dead, too noisy or behave in a non-desirable manner can be masked out.
10 Adjust Crystallography Parameters The MxSettings command allows the user to store more information (as comments or in the CBF template) inside the image header of TIF and CBF images. The principal usage of the MxSettings command is the following: mxsettings [parm_name value] [parm_name value] ...
11 Flat Field Image 11.1 Using the Flat Field Correction Image in Camserver The flat field images recorded during factory calibration are NOT automatically applied to the images that you take. The factory recorded flat field is only appropriate to use at the energy and threshold settings at which it is recorded (no special correction, recommended usage only at 100K and 300K detectors).
11.2 Creating a new Flat Field Image Intensity correction images can be created by the user. To get an appropriate flat field from an homogeneous illumination one can calculate it manually or use a TVX command. First set up a very uniform X-ray illumination and verify that it is as flat as possible.
12 How to Use the Pilatus Detector through TVX TVX is a powerful tool for data acquisition and analysis. This section describes only the most commonly used commands in TVX. All commands are case-insensitive; however, filenames are case-sensitive. An ‘object’ in TVX may be an image or a graph. Many commands, such as move, will work on objects of either kind.
Page 39
Command or Macro Description Read Back Detector. Self-test of the digital part of the detector. Sends a digital pattern to each pixel, reads it out and displays the image. Use this command always after a startup. Every pixel shows 1000 counts. calibdet Self-test of the detector.
Page 40
Command or Macro Description graf fn1[fn2[ fn3]] Graph up to 3 graphs in a window Change the image data type. S…source image, Convert [S][D][type] D…destination image. Type… Char, Short, Int, Float define DEFINE name="instruction1; instruction2;.." Defines user symbol name and value. E.g.
12.1 Description of the Image Display The TVX command disp allows display of images. It contains several options to adjust the contrast and the min-max values. Moreover, it is possible to display the image in different color schemes. This image display will automatically show up after you execute the expose macro in TVX.
Page 42
Display tool Description (sliders) Define the color and the contrast of the image. For every value of a pixel a color from a lookup table will be displayed. With the two left sliders the cut off for the low and high values can be set.
Page 43
Display tool Description black near zero, red fading to pink and white at the high end) thermal color lookup table going from blue through yellow and red, but no greens decades The values between Min and Max are displayed linearly, but with the scale wrapping around Scal number of times.
Page 44
Example: Butterfly selection tool This selection tool is useful for straight line integrations (densitometer traces) and for integrating small angle scattering patterns from either a line or a point X-ray source. Figure 14. Example of a the butterfly selection tool The size and position can be adjusted directly with the mouse or by typing the values directly into the boxes.
12.2 Analysis commands TVX offers a large variety of image analyzing and processing commands. The most important commands are described in this document. All created numeric data are stored in the directory given by “grafpath”; image data are stored in the directory given by “imagepath”. Command Description move fn1=fn2...
Print statistics from the current box selection tool on the image. Alternatively, specifiy image name and box coordinates on the command line. Usage: box [IM] [x1 y1 x2 y2] If IM is not given, the default IM is used. [x1 y1 x2 y2] are the coordinates of box to be examined. If not given, use the box selection tool on image.
Page 47
Command Description mkmask Make a mask from an image between two limits, inclusively. Usage: mkmask [IM [IMout]] low high The result is a mask of 1's and 0's which can be used to select pixels of an image by multiplication. If no image is supplied, the default is used.
12.4 User defined commands TVX supports complex C-like commands in the command line. Example: To display a series of images as a movie: format 2; for (i=0;i<100;i++){disp1 image_000[i]; wait 0.5} Displays image_00000 to image_00099 and waits 0.5 seconds between each picture.
12.5 Glossary files When TVX is started, a glossary is automatically started up called /home/det/p2_det/config/default.gl. In this glossary, the main commands for using the detector are defined. Three other glossaries are called from default.gl (all in config): Glossary Description det_spec.gl Detector specific definitions.
13 Factory Calibration and Correction The following calibrations are done at the DECTRIS premises: 1) Threshold Calibration The PILATUS detector systems come fully calibrated. See the system information sheet in your user handbook for more information about the calibrated energies and settings.
Page 51
6) Bad Pixels The software permits reading a bad pixel mask and flagging defective pixels as -2 in the data. The gaps between the modules can optionally be flagged with -1 (zero is the default). Both of these flags are used by XDS.
14 Camserver Commands The following list presents the Camserver commands with a short description. For detailed usage of the detector system please see sections 7 through 11. Command Arguments Description Socket Socket connection (unit) connection return text [default values] return code Exposure file_base_name + Make an exposure...
Page 53
ExtMtrigger file_base_name + Arm the detector for an exposure series where each exposure is at the start: 15 at start: Starting externally file extension started by an external trigger. multi-triggered exposure(s): <date & Set timing parameters by the commands ExpTime and time>...
Page 54
ExtEnable file_base_name + Make an exposure or an exposure series using an external gate at the start: 15 at start: Starting externally file extension signal. enabled exposure(s): <date & time> Set timing parameters by the commands ExpTime and ExpPeriod before execution. Each exposure is started when the at the end: 7 at the end: full path name signal changes to high and is finished when the signal changes...
Page 55
ImgPath Path [/home/det/ Change the image path the path p2_det/images] If the directory does not exist, it will be created if it is possible to do so with write permission. A path relative to the current path is accepted; '..' is accepted. If 'imgpath test' is given, and the current directory named is 'test', a new directory is NOT created.
Page 56
NExpFrame Number (#) [1] Set the number of exposures to accumulate per frame/read out. Exposures per frame set to: nn This is a method summing up images within the detector chip. A value >1 is a waste of X-rays except when using external enable or external multi-trigger to synchronously capture an event.
Page 57
SetThreshold Threshold Set gain and threshold Setting the threshold: parameters pathname of file (text) [none] This allows setting the threshold energy in eV with following method: Without argument (once setthreshold [[gain] threshold] set): Settings: xxx gain; * If parameters are omitted, the current settings are shown. threshold: xxxx eV;...
Page 58
Stop data taking after current exposure ERR kill full path name of last image LdBadPixMap Filename (text) Load a mask image giving bad pixels to be flagged none or pathname [none] Filename must be a full pathname. If filename is not given, the current setting is shown. If filename is '0' or "off", the pixel flagging function is turned off.
Page 59
Time (s) [0] Control in-line count rate correction. Rate correction is on; tau = xxxe-9 s, cutoff = xxxx A value of 0.0 turns off the in-line rate correction. counts The count rate correction value is threshold dependent and thus set by the SetThreshold commando to an appropriate value.
Page 60
DiscardMultiIm yes/no [no] Discard multiple images status During (too) fast images collections it can happen that the system loses images. It is possible to sum the counted photons in the following image or zero this. no/n/0 … Multiple images will be preserved yes/y/1 …...
Page 61
1…file_base_name Exposure commands take a filename or file basename as their argument. For single images, the filename is used as typed; if a recognized image file format extension is present (.tif, .edf, .cbf), the file will be created in that format. Otherwise, a raw image is produced. For multiple exposure series (NImages >...
Created by: Sebastian Commichau, May 2009 Modified by: Stefan Brandstetter, Feb 2011 Purpose: Client for Camserver Compile with: gcc -o cam_client cam_client.c DECTRIS Ltd. Neuenhoferstrasse 107 CH-5400 Baden www.dectris.com \********************************************************************/ #include <stdio.h> #include <netdb.h> #include <signal.h> #include <unistd.h> #include <string.h>...
Page 64
// Main loop processing user input and socket input while (1) { printf("cam_client> "); fflush(STDIN_FILENO); // Wait for data either from terminal (stdin) or from socket FD_ZERO(&rfd); FD_SET(s, &rfd); FD_SET(STDIN_FILENO, &rfd); if (select(((int) s)+1, &rfd, NULL, NULL, NULL)==-1) break; // Data from stdin if (FD_ISSET(STDIN_FILENO, &rfd)) { fgets(buffer, BUFSIZE, stdin);...