NAME#

eldix.cfg - configuration file for program \"eldix\" for the ELDICO electron diffration system

DESCRIPTION#

Program eldix drives the ELDICO electron diffraction system. The program can be configured with one or more configuration files that will be read at program startup. The configuration file follows the convention of Windows \"ini\" files with section names given in [brackets] and keywords and their values separated by the \"equal\" sign (=). All lines starting with # are ignored.

The program reads configuration files from the following locations in the given order (in parenthesis: Windows)

current_working_directory/eldix.cfg (eldix.ini)
\$HOME/.eldix.cfg (%HOME%\eldix.ini)
\$HOME/.local/share/ELDICO/eldix.cfg (%APPDATA%\ELDICO\eldix.ini)
/usr/local/ELDICO/eldix.cfg (%PROGRAMDATA%\ELDICO\eldix.ini)

Entries given in the next available file will override all previous entries. This allows for mixing entries that can be changed by the user with entries set by a system administrator.

Depending on the connected hardware, the program will also read similarly named configuration files for specific hardware with the same variations of names, i.e. by replacing string \"eldix\" by the corresponding string for the hardware. The following hardware uses the following configuration files:

E-beam system: ebeam.cfg|ini
Octagon system: octagon.cfg|ini

The syntax in the configuration file remains the same, so it doesn\'t matter whether entries specific for the E-beam system are listed in eldix.cfg or in ebeam.cfg. Note, though, that in case of a duplicate entry in eldix.cfg and ebeam.cfg, only the one in eldix.cfg is taken. Please note also, that in ebeam.cfg and octagon.cfg only the hardware specific entries will be parsed, not the ones for general program features.

SECTION: [eldix] or [global]#

In section [eldix], the program accepts the following parameters:

process=True|False: (De-)Activate data processing interface\ Default: process=True

octagon=True|False: (De-)Activate octagon goniometer interface\ Default: octagon=True

http=N: Turn on REST API on port N. See man page of program \"eldix\" for more details about the REST API.\ Default: http=0

browser=NAME: In the \"Help\" menu of the GUI, a browser will be called to show the man pages of program eldix and eldix.cfg. Depending on the system, the browser name may very but typical choices are \"firefox\", \"chromium\", \"windows-default\" or \"macosx\". The default system browser is used if not set explicitely or if not available.\ Default: browser=None

SECTION: [image]#

In section [image], the program accepts the following parameters:

box=N: Size of integration box around selected pixel when pressing middle mouse button\ Default: box=25

colors=N: N is the amount of colors to be used by the program.\ Default: colors=256

colorscheme=SCHEME: Colorscheme for image: either \'grey\', \'blue\' or \'rainbow\'\ Default: colorscheme=grey

play_delay=TIME in sec: When loading images in play mode, add a delay between subsequent loads.\ Default: play_delay=0

convert=PROGRAM_NAME: If an executable program name is given here, the program at the end of each series of data collection will call that program with all images of the current series as command arguments. The executable program can as well be a shell script that can be edited to fit your needs. A typical usage would be to convert collected images into another format.\ Default: convert=

center_x|y=CX|CY: Pixel x|y-coordinate for center of beam on detector.\ Default: center_x=NX/2 center_y=NY/2

wavelength=LAMBDA: For a fixed wavelength system, set the used wavelength in Angstroem, e.g. 0.02805 for a 160kV electron beam. This value will go into image headers.\ Default: wavelength=1.541789

distance=DISTANCE: For a fixed distance system, set the used distance in mm. This value will go into image headers.\ Default: distance=100.0

chi=CHI: For a fixed CHI system, set the used CHI angle in deg.. This value will go into image headers.\ Default: chi=0.0

file=NAME: NAME of file to load at startup.\ Default: not given

linewidth=N: Width of line in Line window.\ Default: linewidth=1

minscale=METHOD, maxscale=METHOD, minvalue=N, maxvalue=N, minrange=N: For converting image pixels into display colors, the programs distribute a certain amount of colors in equidistant intensity bins between a minimum and maximum pixel value. All pixel values above the maximum are drawn in one color and all values below the minimum in another color. The program computes suitable min. and max. values by analyzing a histogram of pixel intensities. There is a choice of fully automatically determine the initial values (\'auto\') or to provide a fixed value. In the latter case, this value can be an absolute pixel value (\'absolute\'), but it can also be a value relative to the maximum of the histogram (\'relative`). Note, that for enforcing a minimum threshold on the left hand side of the histrogram, a negative relative value will have to be entered. Instead of using absolute or relative values, it is usually better to use a multiple of the full-width-half maximum of the histogram (\'fwhm\'). Suitable values are 3 fwhm for the minimum threshold and 5 to 20 fwhm for the maximum. When providing a positive number for minrange, the max. value computed by the program will become not smaller than min. value + minrange. E.g. if the program determines a color range starting with 100 and ending with 200 but minrange is 256 (default), the ending color will be 100+256=356.\ Example: minscale=fwhm, minvalue=3, maxscale=fwhm, maxvalue=10, minrange=512\ Default: minscale=auto, maxscale=auto, minvalue=-1, maxvalue=-1, minrange=256

method=METHOD: Method for plotting lines: either \'crystal\', \'powder\' or \'texture\'\ Default: method=crystal

raw=WxH[[BPP]+OFF]: Format specification for uncompressed raw data images. For each raw data format you want to support you need to provide details about width (W) and height (H) and (optionally) the number of bytes per pixel (BPP, default: 2-bytes=16 bits) and an optional offset (OFF) in bytes from the start of the file to the beginning of the actual image data that might be used to skip an image header. The total size of the file MUST be OFF+WxH*BPP (in bytes). As an example, to read an image with 2048x2048 pixels with 32-bit integers in each pixel and an image header of 4096 bytes you would specify: raw=2048x2048x4+4096.\ Default: none

rings=0|1: Show or hide resolution rings at startup.\ Default: rings=1

scaling=METHOD: Scaling method for image: either \'linear\', \'square\', \'cubic\', \'fwhm\' or \'logarithmic\'\ Default: scaling=linear

spots=METHOD: For detectors with very small smearing (e.g. flat panels and pixel detectors), diffraction spots may be very small and comprise only a single pixel. It then becomes difficult to see those spots in an image. To make them more visible, a method can be provided to make the spots appear bigger than they actually are. Generally speaking, pixels drawn in black will be painted with either one additional black neighbour (spots=small) or 2 additional black neighbours (spots=tiny) on each side.\ Default: spots=normal

SECTION: [auth]#

Section [auth] defines user authentication details. The section may contain the following keyworded lines:

policy=none|relaxed|strcit: With policy set to \"none\" (default), no user authentication is required to run the program. All functions are accessible. With policy \"relaxed\", only authenticated users may change the status of the system like changing the power of the ebeam-system. Unauthenticated users may only see status information but cannot interact. With policy \"strict\", a user must give username and password in order to use the program at all.\ Default: policy=none

user=USERNAME: Specifies a single single username who may use the program.\ Default: empty

password=PASSWORD: Specifies the password for a single user. It is STRONGLY DISCOURAGED to use a clear text password but nevertheless possible. It is highly recommended to rather use a password hash, i.e. a password that has been digested by an encryption algorithm. This password hash is not the actual password and therefore safe to use. The program makes use of the hashing algorithms implemented in the Apache web server. Command line utilities like \'htpasswd\' will produce a valid password hash out of a secret password. Likewise, the internet provides online tools to generate password hashes. Please note, that only the following encryption algorithms can be used: \"apr1\", \"md5\", \"sha1\", \"sha256\", \"sha512\" and \"des\". A typical entry would look like:\ password=\$apr1\$nK4/FNVY\$9VIUw.j8ez3pecAkeMMUh0\ Default: empty

db=database: Specifies the name of a database with combinations of username and password hashes in the same way as a htpasswd-like databases for web browsers. All users given in the database will be used to check for password checks in program \"eldix\" . A typical entry for username \"eldix\" and password \"eldix\" encrypted with \"apr1\" looks like:\ eldix:\$apr1\$nK4/FNVY\$9VIUw.j8ez3pecAkeMMUh0

When using a database, it is possible to assign role to individual users, but only if the user policy is set to \"strict\". The user role must be appended to the hashed password using a colon \':\' followed by a role string or digit. The following roles are implemented (digits in parentheses):

General (0) - Unrestricted access to all functions
Major (1) - Access to hardware interface for typical user functions related to sample handling and data collection. No access to critical hardware functions. Full access to data processing interface.
Sergeant (2) - Access to hardware interface only for monitoring, no interaction, not even data collection. Full access to data processing interface.
Private (3) - No access to hardware. Full access to data processing interface only.

The default role is \"Major\". A typical line in the user interface for a \"General\" would look like:\ general:\$apr1\$nK4/FNVY\$9VIUw.j8ez3pecAkeMMUh0:General

The easiest way to manage users in the user database is to use program \"eldixusers\". This program comes with a graphical interface that allows for adding, changing and deleting users from the database. Please see the man page for eldixusers for more details.

SECTION: [detector]#

Section [detector] defines details for the use of a detector by the program. The section may contain the following keyworded lines:

host=NAME[:PORT]: Hostname and optional port number to connect to. Dectris ELA/QUADRO detectors should be 10.42.41.10 and port number should be 80\ Default: host=None

type=\"eiger\": Type of detector in use. Currently only \"eiger\"\ Default: type=\"eiger\"

zmq=PORT: Port number for streaming interface of Dectris detectors. Should be 9999.\ Default: zmq=9999

api=a.b.c: Dectris EIGER API in use. In 2021 supposedly 1.8.0. This might change with a firmware upgrade on the detector.\ Default: api=1.8.0

SECTION: [ebeam]#

Section [ebeam] defines details for the use of the E-beam system by the program. The section may contain the following keyworded lines:

ebeam_host=NAME[:PORT]: Hostname and optional port number the E-beam controller is listening to. Example: ebeam_host=ebeam:4944\ Default: ebeam_host=None

stemcmd=NAME: Actual name of the state of the E-beam system. For the time being, the name of operation state STEM in the E-beam system is called \"_stem\".\ Default: stemcmd=_stem

stemcmd=NAME: Actual name of the state of the E-beam system. For the time being, the name of operation state STEM in the E-beam system is called \"_stem\".\ Default: stemcmd=_stem

SECTION: [stem]#

For the E-beam system, the program will also accept a section that configures the way STEM-images are produced, in particular limits for the field of view and resolution of the STEM-pictures. A typical section would look like this:

[stem]
um2ma=0.00072681
prescan=10000
blank_timeout=1000.
fov=10.0
xmin=-0.15
xmax=0.15
ymin=-0.15
ymax=0.15
brightness=5.0
contrast=1.7
pixels=400
rows=0
columns=0
gain=3
format=tiff
ascii=False
stemdir=/home/eldix/stem
datadir=
palette=rainbow
series_n=1
series_fov=10
series_dphi=10.0
series_phi=-60.0
series_pixels=400
prealign_fov=10
prealign_phi=1.0
prealign_pixels=400

xmin|ymin|xmax|ymax=val: Min. and max. limits for the movements in x and y of the STEM scan that define the field of view. The unit is microns. Values given here may be modified in the GUI.\ Default: xmin=-0.15, ymin=-0.15, xmax=0.15, ymax=0.15

um2ma=X: For STEM image creation the electron beam needs a conversion factor to convert ranges of micrometers into milliAmps. This conversion factor is instrument specific and needs to be calibrated.\ Default: um2ma=0.00072681

prescan=N: Another cryptic value used for generation of STEM images. Don\'t touch.\ Default: prescan=10000

format=FORMAT: Output format of STEM images. Can be \".report\" files which are plain ASCII files with e.g. 400 x 400 values. The better alternative is to use \"tiff\" as format.\ Default: format=tiff

pixels|rows|colums=N: Number of pixels in x (columns) and y (rows) for a STEM scan. Values may be modified in the GUI. For the time being, STEM images should have x=y. It is sufficient to only specify pixels=N. The values for rows and columns will then be set to N\ Default: pixels=400, rows=pixels, columns=pixels

brightness|contrast=val: Brightness and contrast parameters for STEM scan. The unit is dimensionless. The range of values is from 0 to 5.0.\ Default: brightness=5.0, contrast=1.7

gain=val: Gain parameter for STEM scan. The unit is dimensionless. The value is an integer between 0 and 7. Low emission might need 4 or 5, default is 3.\ Default: gain=3

ascii=True|False: The E-beam system may transfer the STEM-picture as binary data or as ASCII data. The user shouldn\'t care, but large scans would usually benefit from a binary transfer.\ Default: ascii=False

stemdir=path: Path to store the STEM data. STEM data are stored as a sequence of columns*rows pixel values as digitized by either the bright field or dark field detector. The STEM data can be viewed a 2D images with appropriate software and can be loaded into the GUI in the foreseen window to display STEM data. If no directory is given, STEM data will be saved in the directory where the GUI has been started.\ Default: stemdir=None

datadir=path: After data collection all STEM images in stemdir (see above) will be moved to the current data collection directory (datadir=.) or a subdirectory of it (e.g. datadir=stem). If the keyword is missing altogether, no STEM images will be moved from stemdir\ Default: datadir missing, i.e. STEM\'s will not be moved
palette=string: Default color scheme to be used for showing STEM images. The color palette can be modified in the window showing STEM images. A number of color palettes are predefined, but more could be added. Currently the program supports the following choices: grey, autumn, bone, jet, winter, rainbow, ocean, summer, spring, cool, hsv, pink, hot, parula, magma, inferno, plasma, viridis, cividis, twilight, twilightshifted, turbo and deepgreen.\ Default: None

series_n=N: When collecting a series of STEM images, define the default value here. This is the amount of STEM images taken when doing a series. Once modified in the GUI, the modified values will be stored and reloaded at next startup of the program.\ Default: series_n=1

series_fov=N: Field of view in microns for a series of STEMs.\ Default: series_fov=10

series_pixels=N: Amount of pixels in x&y when collecting a series of STEMs.\ Default: series_pixels=400

series_phi=PHI: Starting PHI angle for a series of STEMs.\ Default: series_phi=-60.0

series_dphi=DPHI: PHI movement inbetween 2 STEMS in a series of STEMs.\ Default: series_dphi=10.0

prealign_fov=N: Field of view in microns for the prealignment procedure.\ Default: prealign_fov=10

prealign_phi=PHI: The first STEM in the prealignment procedure will always be shot at PHI=0.0. The value given here is the PHI position for the second shot. It should be close to 0.0 but can also be larger. If the mounted sample is pretty much out of focus, even a small movement of PHI will move the sample out of the field of view.\ Default: prealign_phi=1.0

SECTION: [octagon]#

Section [octagon] defines details for the use of the Octagon goniometer sysgtem by the program. The section may contain the following keyworded lines:

camera=N: Index of video device to use for displaying a video stream on the E-beam page in the notebook. If missing or set to None, no camera subpage will be present. If the system has 1 video device N should be 0. If the camera is of type TIS, use camera=tis:0 (see below). In the octagon section, you can also use the keywords width, height, scale, brightness, contrast, exposure, gain, colormode, and origin as described below in the section [camera].

\ Default: camera=None

SECTION: [hardware-ids]#

For the octagon, the program will also accept a number of sections that carry an ID string describing the related hardware, e.g. [OCT:GONIO:PHI] or [OCT:GONIO:X]. Each section will contain hardware specific configuration values that should not be changed. A typical section would look like this:

[OCT:GONIO:PHI]
channel=2
name=Gonio:Phi
units=deg.
precision=3
min_speed=0.2
max_speed=2.0
default_speed=2.0
upper_ctrl_limit=580.
lower_ctrl_limit=-220.
transfer=0.0

SECTION: [cameraX]#

The program supports video frame grabbers (USB, PCI, PCIe) that produce a video stream from a connected camera. It also support TIS-cameras as manufactured by \"The Imaging Source\". These cameras come with a special software interface (see below). The program also supports IP cameras or server program that transmit image data via TCP/IP. The program may connect to a given host name and port. If successful, it expects entire images to be sent as greyscale (1 byte per pixel) or RGB images (3 bytes per pixel). The result will be displayed on an additional window that can be opened under menu \"File -> Camera\" or by typing CTRL+m on the keyboard. If no camera ID or host and port is given, the option \"Camera\" is not available in the file menu. The X in the section name should be an integer value. You can thus define multiple camera sections, if multiple cameras are present in the system. If there is more than 1 camera, you will see them on different tabs of the Camera window. The section may contain the following keyworded lines:

name=NAME: A meaningfule name that will be shown on the tab header of the camera window. Otherwise, this keyword has no further function.

camera|device=N: Index of video device to use for displaying a video stream on the E-beam page in the notebook. If missing or set to None, no camera page will be present in the Camera window. If the system has 1 video device N should be 0. For TIS-cameras, you will have to use something like: camera=tis:XXX where XXX is the serial number of that device. If it is unknown, just provide camera=tis:0. A serial number is required only if there are multiple TIS-cameras connected to the system. If the value is set to \"ignore\", the camera will not be used upon program start.\ Default: device=ignore

host=NAME[:PORT]: Hostname and optional port number to connect to. The default port is 80. If no hostname is given, there will be no page for IP-cameras in the Camera window. Example: host=camera:4567\ Default: host=None

pixels=NXxNY[xBPP]: NX is the horizontal number of pixels, NY is the vertical number. BPP is the number of bytes per pixel and defaults to 1 (greys). For RGB data, use 3.\ Example: pixels=576x720x3\ Default: pixels=576x720x1

fps=N: N is the number of frames per second. This applies to TIS cameras only which provide a variety of operation modes with different resolutions and FPS rates. The default is 15 and should work for all cameras.\ Example: fps=15

\ origin=CX,CY CX,CY are pixel coordinates with respect to the lower left corner of the video frame. A small cross is painted as overlay on the video frames at the given coordinates CX and CY. The coordinates should mark the intersection of the beam with the goniometer rotation axis, i.e. the center of the sample. When doing point-and-click centering all motions will be calculated using [CX,CY] and the coordinates of the point that has been clicked inside the video frame. See section SAMPLE CENTERING in eldix(1).\ Default: origin=321,239\ Default: origin=video_width/2, video_height/2

brightness|contrast|exposure|gain=[default,min,max]: Settings for adjusting the visual appearance of the video stream. Typical values could be [50,0,100], i.e. setting the range of adjustment from 0 to 100 and the default to 50.\ Default: brightness=[50,0,100] etc.

colormode=grey|colors: This applies only to TIS camera. The cameras can be operated as color cameras or with greys only. Unless explicitely given as grey, colors are tried.\ Default: colormode=colors

EXAMPLE#

A typical configuration file eldix.cfg looks like:

[eldix]
browser=None
process=True
octagon=True
http=0

[camera0]
camera=0
name=-DFK_33GX264E
device=tis:06120046
origin=960,540
fps=15
width=1920
height=1080
scale=0.5
brightness=[64,0,100]
contrast=[55,0,100]
colormode=colors

[image]
wavelength=0.02805
distance=745.78
colors=256
box=25
colorscheme=grey
linewidth=1
scaling=linear
minscale=fwhm
minvalue=3
maxscale=fwhm
minrange=256
maxvalue=10
method=crystal
spots=normal
raw=2560x3072 2048x2048x4+4096 1028x514x4 514x514x4

[auth]
#policy=strict
policy=none
user=eldix
password=$apr1$nK4/FNVY$9VIUw.j8ez3pecAkeMMUh0
#db=/usr/local/ELDICO/users.db

[ebeam]
host=ebeam:4944
stemcmd=_stem
diffractioncmd=_diffraction
oncmd=_on

[detector]
host=quadro:80
zmq=9999
api=1.8.0

[octagon]
camera=0
device=tis:06120046
origin=1224,1024
fps=15
width=2448
height=2048
scale=0.5
colormode=colors

[stem]
prescan=10000
um2ma=0.00072681
yscale=1.13
pixels=400
fov=10.0
palette=rainbow
ascii=False
stemdir=/home/eldico/data/stem

AUTHOR#

Claudio Klein, Marxperts GmbH, Norderstedt, Germany

COPYRIGHT#

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 _