mar345_248x110
Edited on 19-May-2023

prev  up  down  next 

5. Input

5.1 Overview

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
Calibration $MARTABLEDIR/mar2300.###
$MARTABLEDIR/mar3450.###
($MARTABLEDIR/mar345s.###) 		yes Detector calibration files for 150 and 100 micron scan modes. For mar345s versions, mar345s.### is required instead of mar3450.###.
Center correction $MARTABLEDIR/center2300.###
$MARTABLEDIR/center3450.### 		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!

prev  up  down  next 

5.2.1 Keywords

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.

prev  up  down  next 

5.2.2 Example

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)
!

prev  up  down  next 

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:

These files are very large in size (73 MB and 103 MB, respectively). Every time the scanner reads out the plate this file has to be processed. While most of the file contents are binary data, some part of the header is ASCII. Program catmar allows to look into the header.

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).

5.4.1 Keywords

The keywords used in the parameter file mar345.dat are as follows:

Table 2: Keywords in dtb.dat

Keyword Arguments Example Description
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:

Keyword Type Value Description
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.
POLAR F 0.9 Beam polarisation
CENT F   G 0.0   0.0 Deviations of center coordinates as given in the "Header Info"-window

5.4.2 Example

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:

This ASCII-file interface becomes active, if the configuration file has a positive argument on keyword COMMAND. A typical value would be "COMMAND 1000", i.e. the program would look all 1000 msec for existence of a file mar.com. If it does exist, it is read and evaluated . If it does contain a command, the file will be deleted (!) and the command will be executed. While the given command is in progress, a new dtb.com may be created, but it will be evaluated only after the previous command has completed - except commands that contain a STOP or ABORT signal. External programs may monitor the progress of the activity either by evaluating the mar.log, mar.spy or mar345.status files, all residing in $MARLOGDIR.

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

Arguments Example Description
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

Arguments Example Description
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)

5.5.1 Examples

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:

In all cases, the program relies on the existence of an executable shell script called mar345-set.csh and mar345-comN.csh (which N=1,2,3) which must reside in directory $MARLOGDIR. If those file don't exist, the program will continue immediately with the next step of data collection. Otherwise, the data collection will only continue if the commands in the shell script are finished. The shell script may be edited to add any desired command.

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

5.7 Images

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

Format Name suffix Description
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.

Table 6: Sections in $MARTABLEDIR/scale.###

Section Description
[MM] All coordinates in section are in mm
[2300] All coordinates in section are in pixels and apply to 150 micron scan modes only
[3450] All coordinates in section are in mm apply to 100 micron scan modes only

Table 7: Keywords within sections

Keyword Arguments Description
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.

Example: 




[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

prev  up  next