D-22844 Norderstedt / Germany
Tel. +49 (40) 529 884 0
- 5.1 Overview
- 5.2 Configuration File
- 5.3 Calibration Files
- 5.4 Parameter File
- 5.5 Command File
- 5.6 Shell Script
- 5.7 Images
- 5.8 Scale File
Program mar345 uses the following input files. Some of them are mandatory, others optional.
Table 1: mar345 input files.
|File type||File name||Mandatory||Description|
|Configuration||$MARTABLEDIR/config.###||yes||Configuration parameters for programs mar345 and scan345|
|yes||Detector calibration files for 150 and 100 micron scan modes. For mar345s versions, mar345s.### is required instead of mar3450.###.|
|no||Files for optional center offset corrections (see keyword USE CENTER).|
|Scale correction||$MARTABLEDIR/scale.###||no||Instruction files for optional local scales (see keyword SCALE).|
|Parameter||$MARLOGDIR/mar345.dat||no||Saved parameters from "Data collection parameters"|
|Shell script||$MARLOGDIR/mar345-set.csh||no||Shell script for changing wavelength. This file must be executable. The actual command to change the wavelength must be given. The script is called when pressing the "Set"-wavelength button. Argument no. 1 is the wavelength as given in the input field. Only used, when the keyword "USE WAVELENGTH" is given in the configuration file.|
|Shell script||$MARLOGDIR/mar345-com1.csh||no||Shell script for a shell command to be executed before starting a data set. The number of arguments is variable. The first argument is the name of the program to be called. Only used, when the keyword "USE SHELL" is given in the configuration file.|
|Shell script||$MARLOGDIR/mar345-com2.csh||no||Shell script for a shell command to be executed before starting an exposure. The number of arguments is variable. The first argument is the name of the program to be called. Only used, when the keyword "USE SHELL" is given in the configuration file.|
|Command||$MARLOGDIR/mar.com||no||Keyworded ASCII file for setting up simple hardware commands (shutter, erase, etc.) as well as an entire data collection. The file will be deleted after succesful evaluation.|
|Images||...||no||Image files in several formats|
|Configuration||$HOME/.marmusrc||no||Hardware parameters for IuS source (optional).|
### denotes a 3-digit serial number and usually is defined as $MAR_SCANNER_NO .
5.2 Configuration File
While all parameters used within program mar345 are set to reasonable defaults, there are some parameters that are specific for a particular model of the mar345 image plate detector. Therefore, the program must read in a configuration file for proper function. The configuration file is called config.$MAR_SCANNER_NO and resides in directory $MARTABLEDIR. If the configuration file doesn't exist, the program can't be started. The file is a keyworded ASCII-file which may be edited. Keep in mind that many of the parameters can be absolutely critical for hardware functions, so for editing you really have to know what you are doing!
The configuration file is a keyworded ASCII-file in free format. Lines starting with # or ! are treated as comment lines. Almost all keywords and subkeywords can be truncated to 4 characters.
- USE | IGNORE [options]
There are a number of options that can be turned on (USE) or off (IGNORE):
Use the ADC-offsets calculated by the electronics rather than those supplied by MODE <xxxx> AADD <aadd> BADD <badd> (version > 1.0 only).
Use hardware of the standard mar goniostat, i.e. X-ray shutter and motors for PHI, DISTANCE & OMEGA. Please note, that without a goniostat attached the functions for data collection within program mar345 become useless. In particular, an "exposure" requires a feedback from an X-ray shutter. The mar345 controller will always terminate an exposure instruction with an error if no shutter feedback is available.
Adds the CIF/CBF format to the list of available output formats.
Some mar345 image plate detectors suffer from a relatively strong artificial increase of intensities in the inner 5 mm of the IP. This is due to some electronical artifacts in the used controllers. Usually, this is considered as a non-critical problem since this area is mostly covered by the beamstop. However, it is possible to correct for those artifacts by applying a center offset correction. These are additional calibration files that optionally reside in directory $MARTABLEDIR and are called center2300.$MAR_SCANNER_NO and center3450.$MAR_SCANNER_NO. The corrections will be applied with each scanned image, but only if keyword USE CENTER is provided.
- DISTANCE, PHI, OMEGA, CHI, THETA
Use the corresponding motors.
Do provide an option for using X-ray dose controlled exposures.
Watch erase lamp status and stop data collection if erase lamps fail
Same as SUMMARY, but file is in HTML format. File name is rootname.#.html
Adds raw 16-bit data to the list of available output formats. This option replaces the obsolete mar180/mar300 image output. Raw 16-bit data are just plain arrays of N*N pixel values stored as 16-bit integers without header.
Increment image number of consecutive images in "Index Data Sets" by 1. The default is to increment by a number depending on PHI position.
Reports changes of laser status in log file and on the terminal screen. This is for testing lasers only.
Use fast mar345s scan modes 5 to 8 (1150, 1000, 800 or 600).
Put the next exposure command in the controller queue so the exposure starts immediately after the scan has finished. This normally happens sooner than if the scanner driving program on the host computer knows about the end of the scan and therefore saves some seconds of time depending on how busy the computer is. This may cause problems when using multiple oscillations so it is safer to use "IGNORE QUEUE". The default, however, is to use exposure queueing.
Adds an input field to the "Data collection parameters"-window and to the "Scan"-window to provide a reference image. This reference image must be a valid file name. If it does not reside in the data collection directory, an entire path name must be given. If a valid reference image is given, the given image will be used to process the images collected during a data collection. The program actually calls a shell script marreference.sh which must be available in the executable search path. This shell script is an ASCII-file that can be edited and modified if desired. By default, it calls program marreference which subtracts reference images from diffraction images. For more details, look up the documentation of marreference. The shell script is called with arguments "-i current_image" and "-r reference_image". This option has been introduced in version 6.6 of program mar345.
Adds 2 input fields to the "Data collection parameters"-window to submit shell commands, one to be executed before starting the data collection, the second to be executed before starting an exposure. No further program input is allowed during execution of the shell-command. The standard output of the shell will be displayed in the standard output window of mar345. Any shell-commands can be given. "mar345" expects files "$MARLOGDIR/mar345-com1.csh" and "$MARLOGDIR/mar345-com2.csh" to be present (see "man mar345" for an example).
Play sound files when issuing warning, errors, etc. The soundfiles must reside in directory $MARMANDIR and must be called mar_errorX.wav (X=1,2,3) and mar_warning.wav.
Adds the raw spiral format to the list of available output formats.
Adds the PCK-compressed spiral format to the list of available output formats.
Log native mar345-controller messages into file $MARLOGDIR/spy/mar.spy.#. This is very important for backtracing hardware problems of the detector.
For each image plate readout ome statistical values of the resulting image (average, sigma of total and of a box of 100x100 pixels in the 10:30 position of the detector) are calculated and the results are logged into the separate output file $MARLOGDIR/lp/mar.lp.#
Create a summary file in ASCII format for each collected data set. This file contains all relevant parameters used for collecting this data set: motor positions, exposure times, etc.. Useful for archiving. The file will be created in the current data directory and will be named rootname.#.SUMMARY, where # is a number starting at 1. This number will be incremented automatically if a file of the same name already exists in the data directory.
Watch X-ray intensities as read by the ionization chambers and stop data collection if X-ray intensities drop significantly
Use the OMEGA motor to drive a translation for the PHI axis. This is not a standard component of the mar-goniostat.
Default: USE DISTANCE PHI ERASE XRAY SOUND BASE DOSE RUN SPY HTML SUMMARY QUEUE
Default: IGNORE OMEGA CHI THETA IMAGE SPIRAL SPK INCR STATS Z-AXIS SHELL WAVE ADC LASER REFERENCE
- DIRECTORY <name> [DATE] [TIME]
Default directory to write data images if textfield for directory in the GUI is empty or if it says "auto". If option DATE is given, the data directory will be a subdirectory of name with name YYMMDD (eg 190622) that is being created if it does not exist. With option TIME the subdirectory will be called HHMM (e.g. 1409), with options DATE and TIME, the name is YYMMDD_HHMM.
Default: current working directory
- BROWSER <program_name>
Name of the program to display html documentation. Introduced in version 5.5
Default: BROWSER firefox
- THUMBNAIL <command>
Command to use to convert mar data images into graphical thumbnail images.
Default: mar2thumb (shell script)
- NUMBER <max> [LEN <len>]
This keyword can be used to provide the maximum allowed frame number with argument <max>. The program will not allow to produce images numbers exceeding this value. The length of the filename component with the image number is derived automatically from the maximum value, but can also be given explicitely with argument <len>.
Default: NUMBER 999 LENGTH 3
- CENTER USE |IGNORE [MIN <min>]
Choice for using a center correction table during transformation. This implies the existence of files center2300.$MAR_SCANNER_NO and center3450.$MAR_SCANNER_NO in $MARTABLEDIR. Technically, from each pixel in a transformed image a calibrated fixed count is subtracted. By providing a minimum pixel count, pixels will be forced not to drop below a given count (default to 5).
Default: CENTER IGNORE MIN 5
- COMMAND [<interval>] [PORT <port>] [WRITE <interval>] [REST <port> TOKEN <len;>]
<interval> defines the period of time in milliseconds after which an ASCII-formatted command file $MARLOGDIR/mar.com will be periodically checked and parsed. This file may contain commands for the mar345 detector and is the interface for external programs to interact with the mar hardware. A value of "0" means that no dtb.com file will be checked. If the keyword PORT is supplied commands are read using exactly the same syntax from a TCP/IP-socket on port <port>. In this configuration you may choose to only read from that socket or to write something back.
If keyword WRITE <interval> is supplied with a positive number, then a status block is sent every <interval> ms to the socket. The format of the status block is described in chapter "Status File" in section Output). If a 0 is given for <interval>, then no strings will be written
Please note, that it is the client program's responsibility to read back information from the socket. If the program mar345 sends data to the socket, but the client doesn't read it, the program is going to freeze within short time.
If keyword REST <port> is supplied with a positive number, then the program starts to listen for commands send via HTTP requests in a REST-like API. HTTP requests require authentication and on successful authentication, a so called web token is returned with a default length of 16 characters. When providing TOKEN <len> this value may be modified. Sending commands via the REST interface is described in section "REST API"
Default: COMMAND 0 PORT 0 WRITE 0 REST 0 TOKEN 16
- DATA_INTERVAL <t1> <t2> <t3>
These values are very ciritical program parameters concerning timing of data transfer across the network during scan. <t1> is the timeout in millisec- onds to wait for new data to come in before looking again on the network socket after a block of data has been successfully transformed, <t2> is the time to wait in the case <t1> is a timeout after a block of data has been received and transformed before looking for more incoming data. <t2> is a timeout that occurs if a previous call with a timeout of <t1> has not been successful. <t3> is another timeout that happens only at the end of a scan if there are still some data missing. Most relevant is <t1>. However, these parameters are considered strictly internal and modification will have seri- ous consequences on overall program preformance.
Default: DATA_INTERVAL 3 3 10
- COLORS <number>
Number of grey shades for image display.
Default: COLORS 64
- FLAG <number>
The scan command of the mar345-detector may be used with some special flags used for debugging. The number can be any hexadecimal combination of the following codes:
- 0: normal scan
- 1: scan with laser turned OFF
- 2: scan with high voltage turned OFF
- 4: scan with erase lamps turned OFF
- 9: scan with rotation encoder index line turned ON
- 16: scan without data transfer
- 32: scan with ADC offset set to input values
- 64: scan with profile skipped
- 128: scan with debug protocol turned ON
- 256: scan with ADC adjustment turned OFF
Default: FLAG 0
- GAIN [100u <f1>] [150u <f2>]
Gain for conversion of X-rays into ADC-units for the image plate detector. These gain factors differ between the 100 micron and 150 micron scanmodes due to double sampling in the latter one. The values will be written into the image header and play a role only later during data processing when it comes to a statistically correct estimate of the variances of the reflection intensities. The values provided by marxperts are calibrated and scanner specific.
Default: GAIN 100u 1.0 150u 0.65
- GAPS <345mm> <300mm> <240mm> <180mm> [TOLERANCE <N>]
The scanning head of the mar345-detector is mounted on a translation stage. During a scan the scanning head passes a couple of especially marked positions (gap) that serve as a reference for the correct scanning head positions. The positions are hardwired and scanner specific. For a scan at a certain diameter the positions should always stay the same. The posi tions are given in relative motor steps. The expected tolerance normally is +/- 5 steps. Larger variations of the found "gap" positions may indicate a problem with the scaning head spindle. The observed gaps will be written into image headers, so those values can be verified. If the "GAP" keyword is given and the observed gap for a scan at a certain diameter is not within the tolerance, an error message will be produced and data collection stops. Under normal conditions, the GAP keyword should be left out or the tolerance set to large values, e.g. 99999.
Default: GAPS 89600 78600 63900 49100 TOLERANCE 99999
- GENERATOR <synchrotron | rotating anode | sealed tube>
Type of X-ray source. This string will be written into the corresponding section of the resulting images.
Default: GENERATOR ROTATING ANODE
- IGNORE ERROR <n1> [<n2> [<n3>] [...]]
Most hardware errors will make a data collection stop when encountered. Some hardware errors may, however, not be fatal, and it may be desirable to continue data collection, anyway. Also, some hard- ware errors may not be real. For instance, when the scanners reports that an erase lamp is off during erase, it is possible that only the light sensor is broken but the lamp itself works fine. In such cases, the error number as produced by the hardware can safely be ignored. The error numbers can be looked up in the mar.spy file. There, each message (error or not) has got a unique message number. Up to 20 hardware errors may be ignored but all must go in only one line. If there are multiple "IGNORE ERROR" lines, only the last one will be used.
Default: no errors ignored
- INITIALIZE MIN | MAX
The distance crystal-detector may be initialized at near end (MIN) or at the far end of the translation stage.
Default: INITIALIZE MAX
- INTENSITY [MIN <min>] [WARN <warn>] [DOSEMIN <dose>]
<min> gives the minimum acceptable X-ray reading of chamber 2 during one exposure. If reading is lower than this, data collection stops since it will be assumed that the X-rays went away. To turn this off, enter a negative value. Otherwise, provide a value that is at least twice as large as the intensity reading of the 2. chamber without beam. This reading - of course - depends on the selected gain.
<warn> gives the allowed variation of X-ray intensity inbetween the start and the end of one exposure in percent. If the variation is larger than this, a warning message is issued and the data collection stops. This is to avoid unnecessary scans if the X-ray generator fails. To turn this off, enter a very large value for <warn>.
<dose> is the minimum intensity required to actually start an exposure when working in DOSE mode. If the intensity is less than <dose>, the exposure will not even be started but waits until the X-ray intensity as measured by the ionization chamber exceeds <dose>.
Default: INTENSITY MIN 2.0 WARNING 50.0 DOSEMIN 0.1
- MEMORY <number> MB | KB
The program reads a large calibration file during each scan. To improve reading efficiency, data are read in in larger blocks. Only used in program versions < 2.
Default: MEMORY 1 MB
- MODE <scanmode> [ROFF <roff>] [ADC <off>] [AADD <a>] [BADD <b>] [PIXELSIZE <mm>]
Here you specifiy scanner specific values for ADC properties and radial offset corrections for each scanmode (one of 2300, 2000, 1600, 1200, 3450, 3000, 2400, 1800). In particular the ROFF value is really scanner specific and is calibrated during the manufacturing process. The AADD and BADD values are rather dependent on the controller of the detector and have to do with finding an optimal baseline for the ADCs used for digitizing the data. For the mar345s versions of the mar345 detector, it is also required to provide the pixelsize in mm for each scanmode. The fast mar345s scan modes are 1150, 1000, 800 and 600 and are modes 5 to 8. Either the normal 150 micron or 100 micron scanmodes are in positions 1 to 4. values!
Default: MODE <all scanmodes> ROFF 0 ADC 0 AADD 0 BADD 0 PIXELSIZE 0.15
- MONOCHROMATOR <synchtrotron | mirrors | graphite>
Type of monochromator. This string will be written into the corresponding section of the resulting images.
Default: MONOCHROMATOR MIRRORS
- MOTOR [options]
MOTOR stands for a particular motor and is any of:
The following subkeywords define the specifications of the corresponding motor:
- SPEED <steps/sec>: Max. speed in steps/sec
- STEPS <steps/mm>: Translation of motor steps into mm or deg.
- DEFAULT <mm or deg>: Default position in mm or deg.
- MIN <mm or deg>: Minimum value in mm or deg. at near end of translation stage. Used to initialize motor.
- MAX <mm or deg>: Maximum value in mm or deg. at near end of translation stage. Used to initialize motor.
For motors PHI, DISTANCE & OMEGA, the following 3 additional keywords are available:
- USE: turn movement on
- IGNORE: turn movement off
- NEGATIVE: the polarity of the motor is inverted, i.e. the current position and the target position of the axis will invert it's sign.
For motor DISTANCE, the following 2 additional keywords are available:
- USEMIN: reject input values smaller than <min_dist> in GUI
- USEMAX: reject input values larger than <max_dist> in GUI
Default: PHI SPEED 2000 STEPS 500 DEFAULT 0.0 Default: DISTANCE SPEED 1000 STEPS 100 MIN 80.0 MAX 425.00 DEFAULT 100.0 Default: OMEGA SPEED 2000 STEPS 500 MIN -90.0 MAX 90.00 DEFAULT 0.0 Default: CHI SPEED 2000 STEPS 500 MIN -90.0 MAX 90.00 DEFAULT 0.0 Default: THETA SPEED 2000 STEPS 500 MIN -90.0 MAX 90.00 DEFAULT 0.0
- METALJET [PORT <number>] [HOST <IP-address>] [USER <user>] [PASS <password>] [RIGHT|SHUTTER1] [LEFT|SHUTTER2] [IGNORE]
Defines the IP-address and TCP port to which to talk to the MetalJet controller box manufactured by marXperts. Specify SHUTTER1 or SHUTTER2 in order to operate either side of the MetalJet ports. For safety reasons it is mandatory use credentials for talking to the Metaljet controller box. The credentials can be taken from a data base or must be given with keywords USER (default: "mar") and PASSWORD (default:"metaljet"). If the mar345 program is configured to communicate with the MetalJet controller, it is possible to either work with or without standard base goniometer functions. If a standard base is attached to the mar345 detector, exposures will be timed using the locally built-in shutter. Without a base it is possible to use the MetalJet shutter directly for timed exposures in a data collection. In that case, also use lines "IGNORE BASE" and "SHUTTER JET1" or "SHUTTER JET2" for operating the shutter on the right hand or left hand side of the MetalJet generator.
Default: METALJET PORT 45678 HOST metaljet USER mar PASSWORD metaljet RIGHT IGNORE
- MARMUS | IUS [LICENSE <password>] [SHUTTER] [CONDITION <days>] [WARMUP <hours>]
If the mar345 program is configured to communicate with the IuS controller, it is possible to either work with or without standard base goniometer shutter functions. If a standard base is attached to the mar345 detector, exposures will be timed using the locally built-in shutter. It is possible to use the IuS shutter directly for timed exposures in a data collection. In that case, also use parameter "SHUTTER" on the "IUS" keyword or use line "SHUTTER IUS". The parameters for
The LICENSE key is a computer specific ASCII-string that you may obtain from marXperts GmbH. For this purpose you need to run program 'marlicense' (typically contained in the automar program suite) on the mar345 PC and mail its output to marXperts. Without a valid license key, the program will automatically set "IUS IGNORE". For the Incoated IuS source, the program mar345 keeps track when the generator has been completely turned off. It gives suggestion when to run a warm-up procedure (> 8 hrs) or a conditioning procedure (> 56 days).
Default: IUS LICENSE none IGNORE WARMUP 8 CONDITION 56
- NETWORK|MAR345 [PORT <number>] [HOST <IP-address>] [TIMEOUT <sec>]
Defines the IP-address to which to talk to the mar345 detector and the socket ports. The timeout is a time given in seconds after which the program automatically closes and reopens the TCP/IP-sockets to the hardware.
Default: MAR345 PORT 4441 HOST 192.0.2.1 TIMEOUT 60
- SCALE USE|IGNORE <factor>|<file>
When using keyword SCALE <factor>, all pixels in the collected images are multiplied with the given scale factor.
When using keyword SCALE <file>, specific pixels in the collected images are multiplied with the scale factors as defined in that file. If a file name is given here, it will override the programs default ($MARTABLEDIR/scale.###). If SCALE is given, you must also give choose either USE or IGNORE. See section 5.8 "Scale File" for details on how this file must be formatted.
Default: SCALE IGNORE
- SETS <number>
Number of data sets to be programmed. Either 4, 8, 12, ..., 64.
Default: SETS 4
- SHUTTER [DELAY <delay>] [MAR|SHELL|IUS|JET1|JET2]
With <delay> we provide the delay in mseconds the shutter takes to actually be closed and makes exposure times more accurate. The controller measures the time automatically (typically 10-20 msec) every time the shutter is closed. This delay adds to the actual exposure time introducing a small error. To compensate for this error, a shutter delay time entered here will cause the shutter to be closed by <time> milliseconds earlier. This procedure is not essential and may play a role only with very short exposure times (<5 sec or so).
The option SHELL means, that when opening the shutter during data collection, an additional shell command mar345-com3.csh is called with arguments "shutter open" and "shutter close" at the start and end of each exposure. In the shell-script, that must be located in $MARLOGDIR, you may add something to trigger at the beginning and at the end of the exposure. Since there is no direct hardware control, there might be a couple of milliseconds of delay to carry out the command.
With the option IUS, a hardware command is send to IuS generator (Incoatec) to open and close the shutter at the start and end of an exposure. In order for this to work, the IuS generator must be physically connected with its USB cable to the mar345 control computer.
With the option JET1 or JET2, a hardware command is send to the MetalJet controller box to do a timed exposure an the local shutter is ignored altogether. Also, the DELAY argument gets a different function. It becomes a delay in milliseconds for compensating the time it takes to send commands accross the network. This can easily be 100 msec or more. However, when doing a data collection, it is guaranteed, that the scan does not start before the MetalJet shutter is physically closed.
Default: SHUTTER MAR DELAY 0
- STATUS <interval>
<interval> defines the period of time in milliseconds after which a status file mar.status will be periodically written to directory $MARLOGDIR. This ASCII files contains some information about what the scanner and dtb is currently doing. The purpose for this is to give any other program a chance to exchange information with the mar hardware. A value of "0" means that no status file will be written. The format of the status block is described in chapter "Status File" in section Output).
Default: STATUS 0
- UNITS TIME <time_units> DOSE <dose_unit>
<time_units> gives the number of milliseconds per time unit. <dose_units> gives the measured frequency per dose unit.
Default: UNITS TIME 1000 DOSE 1000
- WAVELENGTH <lambda> | VARIABLE
Wavelength of X-rays. This number will be written into the corresponding section of the resulting images. When choosing VARIABLE, the interface provides a field for entering the wavelength that is currently in used. This value goes into image headers. Hence, it is strongly recommended to always supply the correct values!
Default: WAVELENGTH 1.54178
- WINDOWS [MAIN <x y>] [VIEW <x y [width height]>]
[x,y]-coordinates for main window and display window at program startup. The main window has a fixed size. For the display window also the width and the height can be configured. This allows the program to be fit to any screen resolution (>=1280x1024 pixels) and window manager.
Default: Depends on screen resolution and operating system
The following file listing is a typical configuration file for a mar345-detector mounted on the dtb:
! _____________________________________________________________________________ ! ! Configuration file for mar345 S/N 000 ! _____________________________________________________________________________ ! ! NETWORK PORT 4441 HOST 192.0.2.1 ! DIST MIN 75.4 MAX 424.1 STEPS 100 USEMIN INTENSITY MIN -999 WARN 20.0 ! USE SPY USE STATS USE INCR ! USE RUN USE HTML USE SUMMARY ! SETS 4 COLORS 64 ! ! WINDOWS params for Linux:GNOME ! ============================== WINDOWS MAIN 1122 22 VIEW 15 22 1095 942 ! GENERATOR Rotating anode MONOCHROMATOR Mirrors WAVE 1.541789 ! GAIN 100U 1.00 150U 0.63 ! ! Never ever change keywords from here on ! MODE 2300 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.15 MODE 2000 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.15 MODE 1600 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.15 MODE 1200 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.15 ! MODE 3450 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.10 MODE 3000 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.10 MODE 2400 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.10 MODE 1800 ROFF 120 ADC 50 AADD -42 BADD -42 PIXELSIZE 0.10 ! FLAG 0 ! !IP-Diameter: 345mm 300mm 240mm 180mm !GAPS 89659 78656 63903 49146 (08:49 on 30-Oct-2000) !
5.3 Calibration Files
Program mar345 requires calibration files. Those calibration files contain flood field correction factors as well as the geometrical information required to transform spiral coordinates into a Cartesian grid system. The file names are:
- $MARLOGDIR/mar345s.$MAR_SCANNER_NO (mar345s only)
5.4 Parameter File
Program mar345 continuously saves parameters whenever they change within the program. When starting the program, the saved parameters are read back so the user always finds the latest changes after quitting a mar345 session. The parameter file read at startup is called mar345.dat and resides in directory $MARLOGDIR. If the parameter file doesn't exist, program defaults will be used. The program, however, will always create a new parameter file mar345.dat. The parameter file is a keyworded ASCII-file which may be edited.
Parameter files can be created and loaded from within the program. This is useful when working on a project where you always apply the same set of parameters. The parameter files carry the extension ".set" and may be saved using the "Save" button in the Data collection parameters-window. The parameters can be read back by using the "Load" button in the same window ( also see chapter 4.6 in section Collect).
The keywords used in the parameter file mar345.dat are as follows:
Table 2: Keywords in dtb.dat
|SET||N SINGLE|INDEX|MAD||SINGLE||SINGLE is the data set number.|
|DIRECTORY||STR||/data||STR is a string with a path name|
|ROOT||STR||xtal||STR is a string with image root name|
|MODE||N||1200||N is one of 8 scanmodes, either 2300, 2000, 1600, 1200, 3450, 3000, 2400, 1800 for normal scanners. For mar345s flavours choose one of 2300, 2000, 1600, 1200, 1150, 1000, 800, 600 for those where the slow 100 micron scan modes have been replaced by the fast mar345s scan modes. For those, where the slow 150 micron scan modes have been replaced, choose one out of 3450, 3000, 2400, 1800, 1150, 1000, 800, 600.|
|FORMAT||1|2|3|4||1||1="mar345", 2="cbf", 3="image", 4="spiral" format|
|COLLECT||1|2||2||Exposure mode, either 1=DOSE or 2=TIME|
|NFRM||N||50||N is the number of images per block|
|FFRM||N||1||N is the first image number|
|OSCI||N||1||N is the number of oscillations|
|DPHI||F||0.5||F is the Delta-PHI per image|
|DISTANCE||F||220.0||F is the distance detector-to-sample|
|PHIS||F||45.0||F is the starting PHI angle|
|WAVE||F||1.54178||F is the current wavelength|
|COM1/2||STR||sleep 1||Custom argument for shell script mar345-com1|2.csh|
|REFEREMCE||STR||ref_001.mar2300||With keyword "USE REFERENCE" in the configuration file, the output image is postprocessed with shell script marreference.sh. See USE REFERENCE for details.|
Up to here, the keywords are valid for the "SET" number given on the top. With a new SET keyword, the following keywords will be valid for that new set, so a mar345.dat may contain data for all possible sets and the corresponding entries will be used to update the "Data collection parameters"-window. A couple of keywords have to be given only once since they are not related to that page:
|SOURCE||STR||Rotating Anode||STR is the id of the X-ray source as given in the "Header Info"-window|
|POWER||F G||50.0 100.0||F and G are kV and mA settings of X-ray source as given in the "Header Info"-window|
|FILTER||STR||Mirrors||STR is the id of the monochromator as given in the "Header Info"-window|
|BEAM||F G||0.3 0.3||Beam divergence in deg.|
|CENT||F G||0.0 0.0||Deviations of center coordinates as given in the "Header Info"-window|
The following example contains parameters for only 1 data set.
#===================================================== # Date: Mon Feb 18 19:03:08 2002 # Automatically saved by mar345: DO NOT EDIT!!! #===================================================== # ---------------------------------- SET 1 DIRECTORY /home/mar345/data/ ROOT xtal MODE 1200 FORMAT 1 COLLECT 2 TIME 10 NFRM 1 FFRM 2 OSCI 1 DPHI 1.000 DISTANCE 350.000 PHIS 45.000 COM1 COM2 # ---------------------------------- # --- Optional Header Info --- SOURCE Rotating Anode POWER 50.00 100.00 FILTER Mirrors BEAM 0.3 0.3 POLAR 0.000 CENT 0.0 0.0 REMARK
5.5 Command File
Program mar345 may be completely driven by external commands, i.e. all relevant settings and push-button actions can be bypassed. The command interface comes into variants:
- a plain ASCII-file $MARLGODIR/mar.com with a syntax identical to the Parameter File with some extensions.
- a TCP/IP-socket
Note, that the command interface can be used together with the GUI but bears a considerable risk of unwanted or unforeseen dtb or mar345 activity. It must be stated that usage of the command interface is beyond the responsibility of marxperts and all damage produced by running commands using that command interface are not within our liability!
As stated above, all the syntax of the parameter file is used to modify settings of the data collection parameters, i.e. all parameters belonging to a given "SET" will be used to override the corresponding parameters on the "Data collection parameters"-window. The main difference is that the command file in addition to the (optional) keywords of the data collection parameters requires additional lines that actually provide a command to be executed. This line always starts with keyword COMMAND followed by the following arguments:
Table 3: Arguments for keywords COMMAND in mar.com
|ERASE||ERASE||Erase the image plate|
|SCAN||SCAN||The filename will be chosen taken from the current parameters. To override storage place, use an additional line with keyword DIRECTORY. To overide the resulting image name, use additional lines with keyword ROOT and FFRM (see below).|
|CHANGE <mode>||CHANGE||Change the scanmode to the scan mode given by keyword MODE (2300, 2000, 1600, 1200, 3450, 3000, 2400, 1800 for standard mar345 detectors).|
|IPS n1,n2,...||IPS 4,0||Native controller command for the mar345.display plate.|
|SHUTTER [OPEN|CLOSE]||SHUTTER CLOSE||Open or closes the shutter (or toggles current state).|
|PHI|DISTANCE MOVE <value>||PHI MOVE 90.0||Drive PHI or DISTANCE to <value>.|
|PHI|DISTANCE DEFINE <value>||DISTANCE DEFINE 424.4||Defenes PHI or DISTANCE as <value>. Beware: this command is VERY CRITICAL and should normally not be used.|
|INIT MIN | MAX||INIT MAX||Initialize DISTANCE motor at far end or near end (if MIN is given).|
|COLLECT SINGLE | INDEX | MAD||COLLECT SINGLE||Starts a data collection run, either as single data set, index crystal or MAD data set.|
|QUIT||QUIT||Shuts down the program|
When doing a scan or an entire data collection, the following additional keywords may be given:
Table 4: Other keywords in mar.com
|ROOT <root>||ROOT xtal||Specifies the root name of the output image when doing scans. The program automatically adds string _###.marNNNN to the root name when producing an output image, where ### is a 3-digit image number depending on the current image number (as given with keyword FFRM, see below) and NNNN the scanmode (1200, 1600, etc.)|
|DIRE <path>||DIRE /home/mar345/data||Output directory for image file|
|MODE <scanmode>||MODE 1200||Scanmode: either 1200, 1600, 2000, 2300, 2400, 3000 or 3450 for standard mar345 scanners. For mar345s modes 1150, 1000, 800 and 600 replace either the 100 micron scan modes 3450, 3000, 2400 and 1800 or the slow 150 micron scan modes 2300, 2000, 1600 or 1200.|
|FORMAT <format>||FORMAT mar345||Output format: either "mar345", "cbf", "image" or "spiral"|
|FFRM <number>||FFRM 91||First image no. of the data set or current image number of a single scan.|
|NFRM <number>||NFRM 60||Total number of images to be collected in a data set.|
|DPHI <delta-phi>||DPHI 0.5||PHI oscillation angle per image.|
|IPHI <phi increment>||IPHI 0.0||PHI movement inbetween 2 consecutive images of a data set, typically 0 deg.|
|OSCI <number>||OSCI 1||Number of oscillations in one exposure, typically 1.|
|DISTANCE | PHI | OMEGA | CHI | THETA | WAVELENGTH <value>||DISTANCE 120.0||The value given here only goes into the image header.|
|COLLECT TIME | DOSE <value>||COLL TIME 60||Specifies the type of exposures: TIME controlled or X-ray DOSE controlled.|
|TIME <secs>||TIME 60||Exposure time in seconds|
|FILTER <monochromator>||FILTER Mirrors||String to specify the type of monochromator used.|
|POLARIZATION <factor>||POLARIZATION Synchrotron or 0.9||String to specify the polarization factor of the beam.|
|POWER <kV> <mA>||POWER 50 40||Specifies the power settings of the X-ray source (kiloVolt, mil- liAmps).|
|COM1 <command_string>||COM1 sleep 5||External command to be carried out before starting a data set (see mar345-com1.csh)|
|COM2 <command_string>||COM2 sleep 5||External command to be carried out before starting exposure (see mar345-com2.csh)|
The next example contains instructions to carry out a single scan in scanmode 2300:
COMMAND SCAN FFRM 1 MODE 2300 DIRE /home/mar345/data ROOT xtal
The next example contains instructions to carry out a data collection in scanmode 1200 over 90 images starting with image number 1. The distance is 100 mm and the PHI oscillation is 1.0 deg/image. The starting PHI is 0.0 deg.. The output files will be called lyso_001.mar1200 to lyso_090.mar1200 and they will reside in directory /home/mar345/data.
COMMAND COLLECT DIRE /home/mar345/data MODE 1200 ROOT lyso FFRM 1 NFRM 90 DISTANCE 100.00 PHI 0.0 DPHI 1.0
The next command will move the DISTANCE to 150 mm;
COMMAND MOVE DISTANCE 150
5.6 Shell Script
Program mar345 allows to run external commands at certain times during data collection:
- before starting a data set
- before starting an exposure
- after finishing an exposure
- after finishing a detector readout
The following listing contains a very simple template for file mar345-com1.csh.
#!/bin/csh -f set argc = $#argv set NUM = 2 set cmd = $1 set LOG = ( $MARLOGDIR/mar345-com1.csh.log ) while ( $NUM <= $argc ) set cmd = ( $cmd $argv[$NUM] ) @ NUM++ end # echo "===============================================================" >> $LOG echo "Time: `date`" >> $LOG echo "Command: $cmd" >> $LOG echo "===============================================================" >> $LOG # # Actual command # echo $cmd sleep 2 # exit
mar345 autodetects image file formats. The program actually looks at contents of files rather than at file names only. mar345 accepts the following image formats:
Table 5: Image formats accepted by mar345
|mar345||.marXXXX||Images produced by mar345 detector|
|cbf||.cbfXXXX||Images produced by mar software in CBF format|
|image||.image||Original format of 180mm/300mm scanners|
|pck||.pck||Images of 180mm/300mm scanners, "pck"-compressed.|
|raw||.raw||16-bit raw images of x*y pixels without header where x=y|
5.8 Scale File
Program mar345 may automatically apply additional scale factors to single pixels or pixel areas of scanned images on output. This may be useful for special correction conditions. By default, program mar345 will check existence of file $MARTABLEDIR/scale.$MAR_SCANNER_NO unless another file name has been given on keyword SCALE of the configuration file. If that file exists, the instructions in this file will automatically be applied. The file may be empty or contents may be invalid. If no valid instructions are given, the output file will just not be modified. Valid instructions must be given in the following way.
- Declaration of a section: either [MM],  or 
- Declaration of type and coordinates using keywords RECTANGLE, CIRCLE or PIXEL
Table 6: Sections in $MARTABLEDIR/scale.###
|[MM]||All coordinates in section are in mm|
|||All coordinates in section are in pixels and apply to 150 micron scan modes only|
|||All coordinates in section are in mm apply to 100 micron scan modes only|
Table 7: Keywords within sections
|RECTANGLE||x1 x2 y1 y2 s||x1 & x2: starting and ending coordinates in horizontal direction|
y1 & y2: starting and ending coordinates in vertica direction
s: scale factor to apply to all pixels in this rectangle
|CIRCLE||x y R s||x: horizontal center coordinate of circle|
y: vertical center coordinates of circle
R: radius of circle
s: scale factor to apply to all pixels in this circle
|PIXEL||x y s||x: horizontal coordinate of pixel|
y: vertical coordinate of pixel
s: scale factor to apply to single pixel
The coordinates are given as shown in marView, i.e. with origin 0,0 in the upper left corner. The benefit of providing coordinates in mm is that the scale factors will be applied to all scan modes regardless of their pixelsize. Please note, that ALL coordinates refer to the full physical size of the image plate with a diameter of 345 mm. If given coordinates are outside the range of the current scanmode, the corrections will not be applied. However, a coordinate of xy=[172.5,172.5] will also be applied to a scan in mode 1200 (180 mm diameter), since 172.5,172.5 is the physical center of the plate which will be covered by the 180 mm scan.
[mm] CIRCLE 172.5 172.5 5.0 0.96 RECTANGLE 80.0 120.0 200.0 250.0 2.4 PIXEL 220.0 340.0 10.0