Name

Plate Detector System

Synopsis

Description

• 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

-c, --colors COLORS

No. of colors to use for image display.
Default: -c 64

--debug NUMBER

Sets an undocumented flag for debugging purposes.
Default: --debug 0

--default SCANMODE

Default scanmode to use for the mar345 detector. At program startup, the scanner will be set to the requested scanmode.
Default: leave in current scanmode

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

-h, --help

Prints usage summary

-hw

Do not connect to the mar345 detector, but do run the program. Only a limited amount of things can be done without hardware interface.

-k, --keep

Write spiral images to disk during scan. By default, only transformed images are saved.

-m, --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.

-mar345s, -f

Force usage of fast mar345s scanmodes overriding the values in the configuration files. Use with care. It will work only if the mar345 controller is capable of using fast scan modes.

-noinit

At program startup, do not perform run through initialization procedures.

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

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

-p, --port PORT

Connect to port PORT. By default, the connection will be established through ports 4441 to 4444. The port number given on the command line overrides the default and the entry in the configuration file.

-s, --server PORT

Listens to port PORT for incoming connections. If the port number is given on the command line, the optional keyword SERVER PORT in the configuration file will be ignored. When running the program in TCP/IP-server mode, the program accepts command input via that TCP/IP-socket.

-off OFFSET

Apply an offset to raw spiral data.

-sc factor

Apply a scale factor to raw spiral data.

-setd

Allows users to redefine the distance within the program. For safety reasons, this feature is disabled.

-sn NNN

Serial number of detector. By default, the serial number is taken from environment variable $MAR_SCANNER_NO.

-v, --verbose

Increases verbosity level. May be given several times.

Scanner Control

• 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

Input field	|	Description	|	Example
Directory	|	Output directory	|	/data/images
Image root	|	Name root of images	|	lyso
Scan mode	|	Diameter+pixelsize	|	345mm@0.15mm
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

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

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

Moving Distance and Phi

Operating the X-ray Shutter

Diagnosing Hardware

Setting the Wavelength

Additional Shell Commands

External Commands

COMMAND <string>

Specifies the hardware command or procedure to be executed. This keyword must be given as first line in MARCOMMANDFILE when driving the program via MARCOMMANDFILE. When driving the program via a TCP/IP-socket, the COMMAND line must be given as the last part of the instructions! <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. Note that when doing SCANS, the output file name will be composed of the directory (DIRE), the root name (ROOT), a three digit number starting with FFRM and the image extension depending on the format (e.g. .mar1200).

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

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.

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

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.

MAR{MAN|DOC|HELP}DIR

Directory containing help files (optional).

$MARSTATUSFILE

If the environment variable MARSTATUSFILE is not defined, the default file name will be $MARLOGDIR/mar345.status. For a description, see below.

$MARMESSAGEILE

If the environment variable MARMESSAGEFILE is not defined, the default file name will be $MARLOGDIR/mar.message. For a description, see below.

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.

$MARMESSAGFILE

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. The default file name is $MARLOGDIR/mar.message

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 for images lyso_001.mar2000 to lyso_090.mar2000 starting at PHI=0 with an oscillation width of 1 deg. per image:

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

See Also

marView, marTools, mar345xf, mar345_formats, mar345_config_file, marpack, marcvt.

Author

Claudio Klein, marXperts GmbH, Norderstedt, Germany

Copyright

© Copyright 2000-2017 marXperts GmbH, Norderstedt, Germany

Address

marXperts GmbH	Phone: +49 - (40) - 529 884-0
Werkstr. 3	FAX: +49 - (40) - 529 884-20
D-22844 Norderstedt - GERMANY	info@marXperts.com
	www.marXperts.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