Table of Contents

Name

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

Plate Detector System

Synopsis

mar345 [ OPTIONS ]

Description

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

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

Command line options always have precedence over value given in the configuration file. All documentation about how to actually use the features of the graphical user interface must be looked up in the html documentation.

-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

The main window displays the following scanner status information:

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

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:

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

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. Likewise, if a positive port number for parameter SERVER PORT in the configuration file (see man page mar345_config_file) has been given, the program accepts commands from the given port of a TCP/IP-socket in the same ASCII syntax as defined in $MARCOMMANDFILE.
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 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:

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


    Table of Contents