NAME#

stemfind - Finds patterns in STEM images produced by ELDICO system

SYNOPSIS#

stemfind [ -h (--help) ] [ --location ] [ -A (--ai) ] [ -b (--bg) ] [ -B (--scaleBar) ] [ -D (--debug) code ] [ --db FILE ] [ -f (--file) FILE ] [ --filter) FILTER ] [ -F (--force) ] [ --fov FOV ] [ --gx|sx|sz ] [ -H (--http) PORT ] [ -i (--invert) ] [ --min MINCOLOR ] [ --max MAXCOLOR ] [ -L (--loglevel) LEVEL ] [ -G (--grid) ] [ -M (--mesh) ] [ -N (--pin) ] [ -P (--particle) ] [ -R (--reduce) ] [ -r (--results) FILE ] [ -p (--plot) ] [ --png ] [ --pmin SIZE ] [ --pmax SIZE ] [ -x (--x) NX ] [ -y (--y) NY ] [ -Y (--y0) ] [ -s (--size) SIZE ] [ --scale SCALE ] [ -S (--srv) ] [ -t (--tcp) PORT ] [ --tiff ] [ -u (--update) ] [ -v (--verbose) ] [ -V (--VERSION) ] [ file ]

DESCRIPTION#

stemfind is a program to find specific patterns in a STEM image. Currently the program implements different algorithms for finding the following objects:

grid: finds meshes on a grid (field-of-view >= 150 microns)
mesh: finds particles in a mesh (field-of-view >= 50 microns)
particle: finds center of a particle (field-of-view \< 50 microns)
pin: finds the tip of a needle used for alignment purposes

When looking for the center of a particle inside a mesh, the program determines the centroid of a blob closest to the vertical center (y=0) or closest to the physical center of the image. For a pin (or needle) the program determines its tip. When using large fields-of-view, the program finds meshes in it. For medium sized fields-of-view, the program tries to locate several particles in a mesh. In either case, the program prints x,y-coordinates as result plus some further stats. The program can produce an output png or tiff file with a cross-marker at the resulting x,y-coordinates. The program accepts TIFF-files as input or plain ASCII data with X*Y pixels.

OPTIONS#

-A (--ai): Use AI methods to locate particles. AI should not be used for finding meshes but only particles in a mesh. AI requires availability of a trained model which must be supplied via a configuration file or via the command line. The program makes use of \"Segment Anything\" supplied by Meta Labs.
-b (--bg): Run the program in daemon mode as back process without accepting commands from stdin. This is most appropriate when using the program in AI mode where loading the AI model is a time consuming step that should run only once while processing an image with a loaded model is done in very short time. With option --bg, the TCP/IP and HTTP-server ports are opened automatically even if not configured. See options --tcp, --http and --srv below.
-B (--scaleBar): Burn a small scale bar in upper left corner of image on output
--db MODEL: Model to use when running AI.
-o (--out) NAME: Name of output file. This option is valid only with option --png and only for single image processing.
-f (--file) FILE|DIR: If a single file is given, only this file will be processed. If the argument is a directory, all files with extension \".tiff\" and \".report\" will be taken. By default, the field-of-view stored in the image header will be used to detect either meshes on a grid, particles in a mesh or the center of a particle.
--filter FILTER: The program applies a variety of filter algorithms that have impact on the results. The default for FILTER is \"bw\" which implies a series of filters before reducing the image to black and white. Filter \"bw+blur\" applies some blur filter before color reduction. Filter \"bw-histo\" does not use a histogram to reduce colors but a plain thresholding scheme.
-h (--help): Prints a summary of program command line options.
-F (--force): Force reprocessing even if the TIFF-header already contains an entry with the results.
--gx|sx|sz: Program stemfind can be used on a series of STEM images in order to derive missets of goniometer axes GONIO:X, SAMPLE:X and SAMPLE:Z. For the calculation, the direction of the motors matters. With either option --gx, --sx, --sz the direction of the motors can be inverted. To invert the directions of all motors, option --invert (-i) is available.
-H (--http) PORT: Listen to commands on http port PORT. See more details in section REST API.
-x (--x) NX: Horizontal dimension of images. Not required when using TIFF files.
-y (--y) NY: Vertical dimension of images. See -x NX.
-N (--pin): Force finding the tip of a pin.
-G (--grid): Enforce detection of meshes on a grid.
-M (--mesh): Enforce detection of particles in a mesh.
-P (--particle): Enforce detection of a single particle in a mesh at small field-of-view.
--png: Create output file in png format with a marker at the x,y-coordinates of the processing results.
--pmin SIZE: Minimum size of a particle in blob locator. Default: 0.1 um
--pmax SIZE: Maximum size of a particle in blob locator. Default: 4.0 um
-p (--plot): When processing a series of images, show the results of x,y in a 2D-plot. Requires Python matplotlib to work.
-R (--reduce): Applies only to AI: reduce the input image to black&white before applying AI methods to locate particle. Default: don\'t reduce.
-r (--result) FILE: When processing a series of images, the program will create an ASCII file and write data into that file, that can easily be used by plotting routines. The program write lines with the title and subtitle, followed by an array of x-axis data (PHI position), y-axis data (observed deviations of x from center of image), a fitted line through y-axis data, and a fitted line for x-axis data.
-s (--size) SIZE: Maximum size of particle. Default: 20.0 pixels
--scale SCALE: Factor to apply to all input values. Default: 1.0
-S (--srv): Run the program as server by opening also TCP/IP and HTTP ports. This is similar to option --bg, but --srv also allows for input on stdin. See section CONSOLE COMMANDS for details.
-t (--tcp) PORT: Run a TCP/IP-server on port PORT. The command syntax on the TCP/IP port is identical to the one on stdin.
--tiff: Create output file in tiff format with a marker at the x,y-coordinates of the processing results. This option works only when using \".report\" files as input files and not tiff files.
-u (--update): By default, TIFF-headers will be updated with processing results. To turn this off, use option -u.
-v (--verbose): Increases verbosity level for more program output.
-V (--VERSION): Only show program version and exit.
files: All remaining arguments are considered to be input-file names. Wildcards allowed.

INPUT FILES#

TIFF-files or ASCII \".report\" files with STEM data from ELDICO system.

CONFIGURATION FILE#

The program reads configuration files from the following locations in
the given order (in parenthesis: Windows): \$HOME/.stemfind.cfg (%HOME%\\stemfind.ini)
[step]: \$HOME/.eldix.cfg (%HOME%\\eldix.ini)
[step]: /usr/local/ELDICO/stemfind.cfg (%PROGRAMDATA%\\ELDICO\\stemfind.ini)
[step]: /usr/local/ELDICO/eldix.cfg (%PROGRAMDATA%\\ELDICO\\eldix.ini)
[step]: \$ELDICOHOME/stemfind.cfg (%ELDICOHOME%\\stemfind.ini)
[step]: \$ELDICOHOME/eldix.cfg (%ELDICOHOME%\\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. In section [stemfind], the program accepts the following parameters:

sam_db=filename: Name of the file containing the trained model when using AI. See section AI for more details.\ Default: sam_db=
sam_model=filename.yaml: This is an instruction file for exclusive use with a SAM-2 database file. Typical settings would be \"sam_db=/opt/meta/sam2.1_hiera_tiny.pt\" together with \"sam_model=/opt/meta/sam2.1_hiera_t.yaml\"\ Default: sam_model=
scalebar=True|False: Burn a scale bar into image on image output. May be forced with command line option --scaleBar.\ Default: scalebar=False
tcpport=N: Open port N for TCP/IP connections. The syntax for commands on the TCP/IP-port is identical to stdin. If no tcpport is defined, when running the program in server or daemon mode (--srv, --bg), by default port 8881 will be opened.
httpport=N: Open port N for HTTP connections. The syntax for commands on the TCP/IP-port is described in section REST API. If no httpport is defined, when running the program in server or daemon mode (--srv, --bg), by default port 8882 will be opened.
grid=N: Use N as min. field-of-view threshold for deciding that the image is a grid and that the program should try to detect meshes. Default is >=150 microns.
mesh=N: Use N as min. field-of-view threshold for deciding that the image is a mesh and that the program should try to detect particles. Default is >=50 microns
filter=FILTER: Use FILTER for color reduction. Choices are \"bw\", \"bw+blur\" and \"bw-histo\". Default is \"bw\" for meshes and \"bw+blur\" for particles.
contrast_min=N: N is the difference between min. and max. value in the original image. Empty images typically show a low contrast with small N. Images with contrast smaller than N will be regarded as empty. Default is: 25.0
contrast_ios=N: N is the ratio of mean to standard deviation of the pixel values in the original image. Empty images typically show a small standard deviation and therefore a large I over Sigma. Images with particles show a large standard deviation and therefore a small I over Sigma. Images wil contrast_ios larger than N will be regarded as empty. The default is: 25.0.

CONSOLE COMMANDS#

When running the program in server mode, the program accepts keyboard input from the command line (stdin). The following commands are available:

help: show some usage instructions
ai | noai: Turn AI on and off. AI is only available if the PC running the program features a CUDA enabled graphics card as the AI makes use of the phenomenal computation capabilities of NVIDIA GPU\'s. The results of object detection using AI are superior to conventional computations. However, detection of meshes is reliable enough, so even if AI is turned on, this tool will not make use of the AI features. By default, AI is not turned on.
debug N: Set debug to level N. Not documented. N defaults to 0.
file FILENAME: Find objects in FILENAME. The field-of-view in the TIFF header will be used to decide which objects to detect (grid: > 150 microns, mesh: > 49 microns).
force | noforce: When processing an image, the program will update the header of the image with the processing results. When reprocessing the same file, the image header information will be shown instead of doing the calculation unless option \"force\" is active. The default is \"noforce\".
fov X: The field of view is an important parameter for the success of object detection. It is usually taken from the image header. However, it is possible to override this value by explicitely telling the program which field of view to use. The unit of X is microns.
plot | noplot: To get a visual feedback on the selection of objects in an image, you may turn on plotting. It should be noted that plots of an image also require verbosity to be turned on (see command \"verbose\"). By defaults, plots are turned off.
grid FILENAME: In FILENAME, force detection of meshes on a grid (large field-of-view)
mesh FILENAME: In FILENAME, force detection of particles in a mesh (medium field-of-view)
part FILENAME: In FILENAME, force detection of a single particle in a mesh at a small field-of-view
results FILENAME: Write results of processing a series into FILENAME.
series FILE1,FILE2,FILE3,...: Process a series of images and obtain shifts in goniometer motor settings.
scalebar | noscalebar: The program can hardcode a scalebar into the image. It will show a physical scale of the image in the upper left corner of the image. The default is noscalebar.
verbose N: Set verbosity to level N. There are at least levels 0 (default), 1 and 2.

REST API#

When running the program with httpport > 0, the program accepts REST like commands on the given port number (default: 8882). The base syntax for commands is http://HOSTNAME:HTTPPORT/cmd/CMDNAME where HOSTNAME is a name like localhost or a defined IP-address. HTTPPORT usually is 8882. CMDNAME is the key command as used on stdin, but most typically \"part\", \"mesh\", \"grid\" or \"file\". When using commands part|mesh|grid|file, you may also leave out \"cmd\" from the base syntax and use a command like http://HOSTNAME:HTTPPORT/file. When using commands part|mesh|grid|file you need to add a payload to the command. The payload has to be a json formatted instruction with \"name\" as keyword and the full path name of the file to be processed as argument. Thus a typical command would look like:\

curl -H "Content-type:application/json" -d '{"name": "/home/eldico/data/img.tiff"}' http://localhost:8882/file

curl -H "Content-type:application/json" -d '{"file": "/home/eldico/data/1.tiff,/home/eldico/data/2.tiff,/home/eldico/data/3.tiff,"}' http://localhost:8882/series

The result of processing the image is returned as json like:

{'blob': {'x': 180.2, 'y': 248.6, 'diameter': 66.0, 'min': 0.0, 'max': 139.1, 'pixels': 3097, 'phi': 4.0}, 'alt_1': {'x': 200.5, 'y': 239.1, 'pixels': 527, 'mean': 52.0, 'best': 0}, 'alt_2': {'x': 151.5, 'y': 237.5, 'pixels': 790, 'mean': 56.3, 'best': 0}, 'alt_3': {'x': 206.9, 'y': 261.6, 'pixels': 761, 'mean': 59.0, 'best': 0}, 'alt_4': {'x': 159.4, 'y': 258.4, 'pixels': 456, 'mean': 59.9, 'best': 1}}

{'msg': '  180.2  248.6  |    66.0  |  115.0  255.0  |    3097 |     4.00 | a.tiff  !'}

{'shift': {'gonio-x': -0.21, 'sample-x': 0.18, 'sample-z': -0.04}, 'target': {'gonio-x': -175.89, 'sample-x': 175.95, 'sample-z': 6.11}}

AI#

The program may be run using Meta\'s pretrained \"segment anything\" models (SAM). There is a variety of models that differ in size and complexity. Depending on the choosing model, the processing time and success rate varies. For practical usage in short time, the small FastSAM-s model already gives good results and it does not seem necessary to go for the larger sized vit_b/l/h models provided by Meta. The model data are not part of this distribution and will have to be installed separately. Specify which model to use using the sam_db keyword in the configuration file (see above). When using SAM-2, it is also required to provide a yaml file.

AUTHOR#

Claudio Klein

COPYRIGHT#

ADDRESS#

_
ELDICO Scientific AG Phone: +41 - 763020303 Switzerland Innovation Park info@eldico.ch Hegenheimermattweg 167 A www.eldico.ch CH-4123 Allschwil Switzerland _