mar345(1) manual page

Name

mar345 - data acquisition program for the 345mm mar research Imaging

Plate Detector System

Synopsis

mar345 [ -h ] [ [ -keep ] [ -noself ] [ -noxf ] [ -setd ] [ -more LEVEL ] [ -[no]furnace [TIME] ] [ -host HOST ] [ -port PORT ]

Description

mar345 is a Motif-based graphical user interface for operating the mar research Imaging Plate Detector System. The program functions are:

Send Commands to the scanner.
Display the scanner status.
Transform spiral images into Cartesian images.
Display and analyze images.

The program features a scanner control window (Main Window), a image display window and related subwindows. The program versions 0.x for scanners with serial numbers < 044 support different electronics than program versions 1.x ( for serial numbers >= 044 ). They must not be mixed up!

With version 3.0 a way for externally feeding in commands has been added. Simple commands (e.g. erase, open shutter, move phi, etc.) as well as entire data collections can be started by creating a keyworded command file (see below: EXTERNAL COMMANDS).

Options

-keep: Write spiral images to disk during scan. By default, only transformed images are saved.
-noself: At program startup, do not perform a self test (i.e. lasers, laser shutter, erase lamps). The default is to do a self-test each time mar345 is started.
-noxf: Spiral images will not be transformed and displayed during data collection. The default is to transform images.
-setd: Allows users to redefine the distance within the program. For safety reasons, this feature is disabled.
-more LEVEL: Verbose output; the amount depends on the value of LEVEL, which may have a value between 0 and 3, higher values giving more information.
-[no]furnace TIME: This works with a special compilation of program mar345 version >= 2.5 only. <TIME> overrides the value given on keyword FURNACE UPDATE <sec> in the configuration file. A value of 0 would turn off usage and initialization of the furnace. So will the argument -nofurnace (leaving off the time value). This option should be use when working with the mar345 with a furnace disconnected.
-host HOST: Connect to host HOST. By default, the scanner hostname is "mar345" (192.0.2.1). The host name giving on the command line overrides the default and the entry in the configuration file.
-port PORT: Connect to port PORT. By default, the connection will be established through the arbitrary port no. 4123 (versions 0.x) or 4441 to 4444 (versions > 1.0) . The port number given on the command line overrides the default and the entry in the configuration file.

Scanner Control

The main window displays the following scanner status information:

Current time.
Current scanner operation.
Current scan mode (diameter and pixelsize).
Current X-ray shutter status.
Current image.
Current distance.
Current phi position.
Current intensity.
Current disk space.

Underneath the section with the scanner status information, the following push buttons can be found:

Collect: Choice of programming up to four data sets (see EDITING DATA COLLECTION PARAMETERS).
Scan: Provides a window for entering the output file name for a single scan.
Erase: Turns on the erase lamps and erases the imaging plate.
Initialize: Drives the detector to its distance reference position.
Open/Close Shutter: Opens and closes the local X-ray shutter.

Editing Data Collection Parameters

To edit data collection parameters, press the Collect button in the main window and make your choice of programming a "Single Set", "Multiple Sets" (1-4 data sets), "MAD Data" for collecting MAD data (multiple anomalous dispersion) or "Index Crystal" for collecting images with larger PHI movements inbetween. The following input is required:

In "Multiple Set" mode up to 8 data sets may be programmed by editing these parameters. To use any one of the programmed sets, the "Use" button must be explicitely pressed for this set.
In ""MAD Data" mode, 2 data sets will be take (A and B). A starts at "Starting PHI", B at "Starting PHI + 180 deg.". The first PHI-block of images will be in set A, the second one in set B, the third one also in set B, but at "Starting PHI + (images/block)* Delta-PHI + 180 deg.", the fourth one again in set A at "Starting PHI + (images/block)*Delta-PHI ", etc. A PHI-block denotes the smallest set of images that are contiguous in PHI. To obtain the total number of images to be collected, just multiply the number of PHI-blocks by the number of images per PHI-block. To alternate between both sets, use 1 image per block. Note, that the smaller the number of images per PHI-block the more PHI movements are required. For further illustration, use the Help-button in the window.
In "Index Crystal" mode, the field "First image no." is replaced by the field "PHI increment". The first image no. will always be 1. Before doing the next exposure, the PHI axis drives to a new value that is "PHI increment" degrees away from the previous image. The image no. for the new image is calculated as: previous image no. + PHI increment/Delta PHI.

Starting Data Collection

Data collection starts by pressing the "Go" button in the "Change Parameters" window. A new window "Run Parameters" pops up and displays the summary of the selected parameters. In this window, "Go" has to be pressed again. By pressing "Go/Erase first" the plate will be cleaned before starting the data collection. Note, that the plate will always be erase when moving to larger scanned diameters.

If additional shell-commands have been configured (see mar345_config_file) these shell-commands will be executed before actually starting the data collection and/or each exposure.

During data collection, the "Change Parameters" window cannot be obtained. If desired, the progress of data collection can be traced by looking at the "Run Parameters" window (select "Progress" in the menu bar of the main window or press "Ctrl+p" in the main window). All essential information, however, is displayed in the main window.

Stopping Data Collection

To stop data collection press the yellow "Stop" button in the main window and select "Abort NOW" or "Stop AFTER IMAGE" in the the "Run Parameters" window.

Moving Distance and Phi

The input fields for "Phi" and "Distance" in the "Change Parameters" window are followed by two buttons: "Move" and "Set". By pressing "Move", the PHI axis or the detector drives to the desired position. By pressing "Set", the currently known values can be redefined.

Operating the X-ray Shutter

In order to open or close the shutter, normally one would just press the "Open/Close Shutter" button in the main window. It is possible, however, to leave the shutter open for a specified period time using an additional window that can be obtained by choosing the "Shutter Timer" option in the "Windows" submenu of the menu bar. This window displays a digital stop watch that counts the time since the "Open Shutter" button was pressed. The shutter will automatically close after the time specified in the entry field above has elapsed. This will happen only if this window stays on the screen. When closed, no further time limits are applied.

Diagnosing Hardware

In order to diagnose hardware, in program version > 1.0 there is an additional window that can be opened using the "Hardware" button in the "Windows" submenu of the menu bar. In that window, hardware status is graphically displayed, i.e. state of erase lamps, plate locking, etc. All hardware errors are logged into standard output and into the log file. When using an optional "spy" output file, each scanner operation is logged into that file. This can be helpful for looking close at hardware problems.

Setting the Wavelength

On some synchrotron beam lines, a shell command can be issued to modify the current wavelength. In the config file, the "USE WAVE" keyword must be given. This will display a "Set"-button for the wavelength in the "Change Parameters" window. When pressed, a shell command ($MARLOGDIR/mar345-set.csh, see below) will be executed. No further input is allowed while task in progress. There is no feedback that actually checks if the actual wavelength is the desired one.

Additional Shell Commands

Shell commands may be executed at the beginning of a programmed data set and/or before starting an exposure. Input fields are provided if keyword "USE SHELL" is given in the configuration file. No further input is allowed while the shell command is running. Shell commands make use of existing shell script files that may be edited for further customization (see below).

External Commands

If a positive value for parameter COMMAND in the configuration file (see man page mar345_config_file) has been given, the program accepts commands from a keyworded ASCII-file $MARCOMMANDFILE which defaults to $MARLOGDIR/mar.com. Simple commands (e.g. erase, open shutter, move phi, etc.) as well as entire data collections can be started this way. After evaluating MARCOMMANDFILE, the file is deleted. If a certain task or procedure is active, only commands ABORT or STOP will be accepted. All other commands will be executed after the current procedure has finished. When setting up a data collection, the parameters given in MARCOMMANDFILE will overwrite the settings for either SINGLE SET, INDEX CRYSTAL or MAD DATA. Parameters that are not specified will be taken from the GUI, otherwise. This way, any combination of graphical editing and external commands is achieved.
An active task or procedure will write additional output into file $MARLOGDIR/mar.message. This file will contain information about the progress of a procedure. A new procedure is going to overwrite the file. This file may be used by other external programs for synchronization with further actions.
The syntax for file MARCOMMANDFILE is as follows (see also EXAMPLES for MARCOMMANDFILE):

COMMAND <string>

Specifies the hardware command or procedure to be executed. This keyword must be given as first line in MARCOMMANDFILE! <string> is one of:
·

SHUTTER OPEN - Opens the shutter

SHUTTER CLOSE - Closes the shutter

QUIT - Shuts down the program

CHANGE - Change current scanmode

ERASE - Erases the image plate

SCAN - Scans the image plate and produces an image

INIT [MIN] - Initializes the distance to far [or near] end

COLLECT [SINGLE | INDEX | MAD ] - Starts a data collection run, either as single data set, index crystal or MAD data set.

PHI MOVE <deg> - moves PHI to <deg>

PHI DEFINE <deg> - defines PHI as <deg>

DISTANCE MOVE <mm> - moves DISTANCE to <mm>

DISTANCE DEFINE <mm> - defines DISTANCE as <mm>

ABORT - aborts current movements and stops data collection

STOP - stops data collection after finishing current image

The following additional keywords in MARCOMMANDFILE are meaningful only for COMMAND COLLECT or COMMAND SCAN. If they are not provided, the corresponding entries in the GUI from either SINGLE SET, INDEX CRYSTAL or MAD SET are used for data collection.

The only effect of the following keywords will be that the provided values will be used as image header information.

Keyword | Arguments | Example | Description

OMEG | <deg> | 90.0 | Omega position

THET | <deg> | 0.0 | 2-Theta position

CHI | <deg> | 0.0 | Chi position

WAVE | <Ang> | 0.98 | Wavelength

The following keywords will overwrite the entries in the "X-ray Setup"-window of the GUI.

Image Display

The image display window can be obtained by selecting the "Display" button in the menu bar of the main window or by typing "Ctrl+d". During data collection, newly collected images are displayed automatically. While the scanner is not scanning, other images may be loaded from disk using the "Files" option in the "Windows" submenu of the menu bar.

Magnification Factors

To change magnification factors, select "Auto/100%", "100%", "75%" or "50%" in the menu bar, where 100% means: 1 pixel on the screen is 1 pixel in the image. It is possible to further magnify areas within the image by selecting a zoom area in the displayed image (see ZOOM MODE). In ZOOM MODE, the available zoom factors are: 1, 2, 4, 8, ... 512.

Image Display Options

With the "Options" button in the menu bar, the following options can be toggled:

Keep/Hide resolution rings.
Keep/Hide statistics (average and max. intensity).
Keep/Do not keep view.
Keep/Do not keep color scales.
Reset colors.
Next image.
Previous image.
Integrate.
Zoom options.
"Integrate" is available in ZOOM MODE only. The contents of the displayed image area is integrated.
"Keep view" means: when loading a new image, the same area and magnification will be drawn. "Keep view" also implies "Keep colors". If a crosssection has been drawn, it will be displayed as well.
"Keep color scales" means: when loading a new image, the image will be drawn in the same way as the previous image (see IMAGE COLORS).
"Reset colors" means: reinitialize image colors.
"Next image" means: load the next image (image number incremented by one).
"Previous image" means: load the previous image (image number decremented by one).
"Zoom options" means: in IMAGE MODE and zoom factors less than 100%, by default every "N'th pixel" is displayed only and the ones inbetween are ignored. While this method may hide some features in the image, it is much faster than computing the "Average pixel" or the "Maximum pixel". "Average pixel" tends to give a smoother look. In "Maximum pixel" mode, reflections will appear stronger, but you will also see more noise (e.g. cosmics).

Mouse Actions in Image Area

In the image area, the 3 mouse buttons have the following functions:

Left mouse button:: Draws a line from point A to point B and displays the pixel values along that line in a separate window (see CROSS SECTION).
Center mouse button:: Displays x,y-coordinates, intensity and resolution of the selected pixel (upper right area) and the minimum, maximum, average and sigma of a box of 100x100 pixels (red box) around the selected pixel (upper left area).
Right mouse button:: Draws a box from point A to point B and displays the image area within that box in the image display window with the corresponding magnification factor ("ZOOM MODE"). To get back to normal "IMAGE MODE", the "Back" button in the menu bar must be pressed (or "Alt+b" typed). In ZOOM MODE, the right mouse button has a different function: when pressed, the magnified area is recentered at the pixel under the mouse pointer.

Image Colors

Normally, 32 colors are distributed in equidistant intensity bins between a minimum (Min) and maximum (Max) value. All pixel values > Max are drawn in one color and all values < Min in another color. Min usually is 0, but Max is calculated such that 99.998 % of all pixels in the image have intensities <= Max. The Max and Min can be entered on the left hand side of the image display window (upper left and lower left corner, respectively) or in the "Colors" window which can be obtained by selecting the "Colors" option in the "Windows" submenu or by typing "Ctrl+o". In the "Colors" window, the histogram of the pixel values in the image is displayed, i.e. the inetnsity of a pixel versus its frequency. In the histogram plot, two dashed bars mark the Min and Max values. To change Min or Max, enter values in the corresponding fields (and press RETURN!) or move the left or right bar using the left or right mouse button, respectively. Warning: each operation requires recalculation of the whole image (CPU!!!).

To change color schemes, select "Gray scales" or "Gray scales" or "Rainbow". By dragging the center mouse button in the histogram plot or in the color area of the image display window, colors can be redistributed.

Cross Section

Cross sections can be obtained by pressing the left mouse button in the image area of the display window. The cross section plot can be used for measuring distances and thus getting an estimate of cell constants. In the plot area two dashed lines can be moved around by pressing the left (left bar) and right (right bar) mouse button, respectively. The distance between bars is given in pixels and mm. The upper horizontal scale in the plot area is the length of line in pixel units, the lower one the length in mm.

To calculate cell constants, the no. of peaks between the left and the right distance measuring bar must be entered. Place the bars on top of two peaks. The no. of peaks must include the first and last one.

Environment

The following logical names must be assigned:

MARTABLEDIR:

Location of scanner specific calibration and configuration files.

MAR_SCANNER_NO

Serial number of scanner.

MARLOGDIR

Directory where log files will go.

MARHELPDIR

Directory containing interactive help file (optional).

Input Files

The program requires the following input files:

$MARTABLEDIR/mar2300.$MAR_SCANNER_NO:: Scanner specific calibration table used for transformation of the images collected with 0.15 mm pixelsize.
$MARTABLEDIR/mar3450.$MAR_SCANNER_NO:: Scanner specific calibration table used for transformation of the images collected with 0.10 mm pixelsize.
$MARTABLEDIR/config.$MAR_SCANNER_NO:: Scanner specific configuration file (Ascii).
$MARHELPDIR/mar345.hlp:: Ascii file for interactive help.
$MARLOGDIR/mar345.dat (optional):: Contains latest data collection parameters.
$MARLOGDIR/mar345.PAR (optional):: Stores the latest DISTANCE and PHI values on disk. The scanner does not keep these values in memory, so the software has to tell the scanner which values to use (or reinitialize). This file is used only on versions 0.x!
$MARLOGDIR/mar345-set.csh (optional):: 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.
$MARLOGDIR/mar345-com1.csh (optional):: 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.
$MARLOGDIR/mar345-com2.csh (optional):: 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.
MARCOMMANDFILE ($MARLOGDIR/mar.com, optional since version 3.0):: 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.

Output Files

The program produces the following output files:

$MARLOGDIR/last.log:: Contains the version number of the latest log file.
$MARLOGDIR/mar.log_NO (version 0.x) or $MARLOGDIR/log/mar.log.NO:: Latest log file. NO ranges from 1 to 99 and is increased with each call of program mar345. If NO > 99, NO = 1.
$MARLOGDIR/MAR345.NO.LP (version 0.x) or $MARLOGDIR/lp/mar.lp.NO:: Optional output, if keyword USE STATS is given in the config file (see mar345_config_file). The NO ranges from 1 to 99 and is increased with each call of program mar345. If NO > 99, NO = 1.
$MARLOGDIR/spy/mar.spy.NO (version > 1.0 only):: Optional output, if keyword USE SPY is given in the config file (see mar345_config_file).
$MARSTATUSFILE: Optional output of a status file updated in regular interval, containing the most relevant status information. To enable output, use keyword STATUS <interval> in the configuration file. The interval is in milliseconds. If the environment variable MARSTATUSFILE is not defined, the default file name will be $MARLOGDIR/mar345.status.
$MARLOGDIR/mar.message: Optional output of a progress file when using external command files (see MARCOMMANDFILE). This file contains the most relevant status information about the progress of an active task. To enable output, use keyword COMMAND <interval> in the configuration file. The interval is in milliseconds.
data directory:: Transformed image files and data collection summaries (.SUMMARY and .html).

Note: The program will automatically set links $MARLOGDIR/mar.log and optionally $MARLOGDIR/mar.lp and $MARLOGDIR/mar.spy to the latest files in use.

EXAMPLE for the mar345-set.csh SHELL SCRIPT

#
changewavelength $1

exit

EXAMPLE for the mar345-com1.csh SHELL SCRIPT

#!/bin/csh -f
set argc        = $#argv 
set NUM         = 2
set cmd         = $1
while ( $NUM <= $argc )
        set cmd = ( $cmd $argv[$NUM] )
        @ NUM++
end
#
# Actual command
#
$cmd
#
exit
#

EXAMPLE for MARCOMMANDFILE

The following command file would start a data collection:

COMMAND COLLECT SINGLE
MODE 2000
ROOT lyso
FFRM 1
NFRM 90
PHI  0.0
DPHI 1.0
FORMAT MAR345

The following command file would move the distance to 250 mm:

COMMAND DISTANCE MOVE 250.0

Marresearch G.m.b.H.	Phone: +49 - (40) - 529 884-0
Hans-Boeckler-Ring 17	FAX: +49 - (40) - 529 884-20
D-22851 Norderstedt - GERMANY	info@marresearch.com
	www.marrresearch.com

Table of Contents

Name
Synopsis
Description
Options
Scanner Control
Editing Data Collection Parameters
Starting Data Collection
Stopping Data Collection
Moving Distance and Phi
Operating the X-ray Shutter
Diagnosing Hardware
Setting the Wavelength
Additional Shell Commands
External Commands
Image Display
Magnification Factors
Image Display Options
Mouse Actions in Image Area
Image Colors
Cross Section
Environment
Input Files
Output Files
EXAMPLE for the mar345-set.csh SHELL SCRIPT
EXAMPLE for the mar345-com1.csh SHELL SCRIPT
EXAMPLE for MARCOMMANDFILE
See Also
Author
Copyright
Address

Input field	\|	Description	\|	Example
Directory	\|	Output directory	\|	/data/images
Image root	\|	Name root of image files	\|	lyso
Scan mode	\|	IP diameter and pixelsize	\|	345 mm @ 0.15 mm
Output format	\|	new "mar345" or old "image"	\|	mar345
Collect mode	\|	TIME or X-ray DOSE	\|	TIME
	\|	controlled PHI movement	\|	(recommended)
First image no.	\|	No. of first image (1-999)	\|	1
No. of images	\|	No. of images in set (1-999)	\|	120
PHI increment	\|	PHI movement between 2	\|	45 deg.
(Index crystal)	\|	consecutive images	\|
Exp. time	\|	Exposure time per image	\|	300 sec
Oscillations	\|	PHI oscillations per image	\|	1
Delta PHI	\|	PHI movement during	\|	1.0 deg.
per image	\|	one exposure	\|
PHI	\|	PHI angle where data	\|	0.0 deg.
	\|	collection starts	\|
Distance	\|	Distance crystal-detector	\|	150 mm

Keyword	\|	Arguments	\|	Example	\|	Analogy in GUI
DIRE	\|	<string>	\|	/data	\|	Directory
ROOT	\|	<string>	\|	xtal	\|	Image root
MODE	\|	<number>	\|	1200	\|	Scan mode
FORM	\|	<string>	\|	MAR345	\|	Output format
TIME	\|	<time>	\|	60	\|	Exp. time (sec)
DOSE	\|	<dose>	\|	100	\|	X-ray dose (units)
FFRM	\|	<number>	\|	1	\|	First image no.
NFRM	\|	<number>	\|	90	\|	No. of images
BLOC	\|	<number>	\|	2	\|	No. of PHI blocks
NPER	\|	<number>	\|	10	\|	Images/PHI-block
OSCI	\|	<number>	\|	1	\|	Oscillations
DPHI	\|	<number>	\|	1.0	\|	Delta-PHI per image
IPHI	\|	<number>	\|	0.0	\|	PHI increment
PHI	\|	<number>	\|	0.0	\|	Starting PHI
DIST	\|	<number>	\|	250.0	\|	Distance
COM1	\|	<strings>	\|	?	\|	Shell command 1
COM2	\|	<strings>	\|	?	\|	Shell command 2

Keyword	\|	Arguments	\|	Example	\|	Analogy in GUI
SOUR	\|	<string>	\|	SYNCHROTRON	\|	X-ray source
POWE	\|	<kV> <mA>	\|	50 100	\|	X-ray kV, mA
SLIT	\|	<x> <y>	\|	0.3 0.35	\|	Collimator X,Y
FILT	\|	<string>	\|	MIRROR	\|	Monochromator
POLA	\|	<value>	\|	0.0	\|	Beam polarization
BEAM	\|	<x> <y>	\|	0.1 0.2	\|	Deviation X,Y