Ubuntu Manpage: ssocr - optical recognition of seven segment displays

NAME

       ssocr - optical recognition of seven segment displays

SYNOPSIS

       ssocr [OPTION]... [COMMAND]... IMAGE

DESCRIPTION

       ssocr  reads  an  image file containing the picture of a seven segment display, recognizes
       the displayed digits and prints them to standard  output.   All  image  formats  known  by
       imlib2  are  supported.   Use - as file name to read the image from standard input.  ssocr
       provides several image manipulation algorithms to enhance noisy images.

OPTIONS

-h, --help
Write a help message to standard output. The default settings are shown as well.

-V, --version
Write version information to standard output.

-v, --verbose
Print information about program execution to standard error.

-t, --threshold THRESHOLD
Specify a percentage value as luminance threshold to differentiate between black and
white. This threshold is adjusted to the luminance values occurring in the image, unless
option --absolute-threshold is used. The default threshold is 50.

-a, --absolute-threshold
Do not adjust the threshold to the luminance values occurring in the image. Consider this
option when using the dynamic_threshold command.

-T, --iter-threshold
Use an iterative method (one-dimensional k-means clustering) to determine the threshold.
The starting value can be specified with the --threshold option.

-n, --number-pixels NUMBER
Set the number of foreground pixels that have to be found in a scanline to recognize a
segment. Can be used to ignore some noise in the picture. See the web page of ssocr(1)
for a description of the algorithm.

-i, --ignore-pixels NUMBER
Set the number of foreground pixels that are ignored when deciding if a column consists
only of background or foreground pixels. Can be used to ignore some noise in the picture.
See the web page of ssocr(1) for a description of the algorithm.

-d, --number-digits NUMBER
Specifies the number of digits shown in the image. Default value is 6. Use -1 to
automatically detect the number of digits.

-r, --one-ratio RATIO
Set the height/width ratio threshold to recognize a digit as a one. RATIO takes integers
only. See the web page of ssocr(1) for a description of the algorithm.

-m, --minus-ratio RATIO
Set the width/height ratio to recognize a minus sign. This uses the same idea as
recognizing the digit one.

-H, --dec-h-ratio RATIO
Set the max_digit_height/height ratio used for recognition of a decimal separator. This
value is used in combination with the max_digit_width/width ratio.

-W, --dec-w-ratio RATIO
Set the max_digit_width/width ratio used for recognition of a decimal separator. This
value is used in combination with the max_digit_height/height ratio.

-o, --output-image FILE
Write the processed image to FILE. Use - to write to standard output. Unless this option
is used no image is written to disk. If a standard filename extension is used it is
interpreted as the image format to use. Can be useful together with the --process-only
option.

-O, --output-format FORMAT
Specify the image format to use with --output-image. This format must be recognized by
imlib2. Standard filename extensions are used to describe the format. Overwrites the
image file format automatically determined via the filename. If no format is specified
via this option or the filename, png is used.

-p, --process-only
Use ssocr(1) as an image manipulation program. No image recognition is performed. Should
be used together with the -B --output-image option.

-D, --debug-image[=FILE]
Write a debug image showing the results of thresholding, segmentation and character
recognition to disk. The image is written to the file testbild.png unless a filename FILE
is given. This debug image often helps in understanding why ssocr(1) does not recognize
the number from a given image.

-P, --debug-output
Print information helpful for debugging to standard error.

-f, --foreground COLOR
Specify the foreground color (either black or white). This automatically sets the
background color as well. Default is black.

-b, --background COLOR
Specify the background color (either black or white). This automatically sets the
foreground color as well. Default is white.

-I, --print-info
Prints image dimensions and range of used luminance values to standard error.

-g, --adjust-gray
Interpret the values T1 and T2 given to the command gray_stretch as percentages instead of
absolute luminance values.

-l, --luminance KEYWORD
Choose the type of luminace computation. Using help as KEYWORD prints the list of
implemented luminance keywords with a short description of the used formula. The default
of Rec709 should work well in most cases.

-s, --print-spaces
Print space characters between digits (characters) that are farther apart than a factor
times the minimum distance between digits (characters).

-A, --space-factor FACTOR
Use the given FACTOR instead of the default value to determine white space between digits
(characters).

-G, --space-average
Use the average distance between digits (characters) instead of the minimum distance to
determine white space between digits.

-S, --ascii-art-segments
Prints the recognized segments, i.e. the display as seen by ssocr, as ASCII art to
standard error.

-X, --print-as-hex
Prints the recognized segments as a string of hexadecimal numbers separated by a colon
instead of digits and characters. Each number comprises two hexadecimal digits (one
byte). 0x01 represents the upper horizontal segment, 0x02 represents the upper left
vertical segment, 0x04 represents the upper right vertical segment, 0x08 represents the
middle horizontal segment, 0x10 represents the lower left vertical segment, 0x20
represents the lower right vertical segment, 0x40 represents the lower horizontal segment,
0x80 represents a decimal point (or comma or thousands separator). Each hexadecimal
number printed is the logical or of the set segments.

-C, --omit-decimal-point
Omit decimal points from output. Decimal points are still recognized and counted against
the number of digits. This can be used together with automatically detecting the number
of digits to ignore isolated groups of pixels in an image.

-c, --charset KEYWORD
Select the set of characters that ssocr shall recognize. This affects, e.g., if a display
showing a six with missing top segment is recognized as 6 (with digits and decimal) or b
(with hexadecimal and full). Using help as KEYWORD prints the list of implemented
character set keywords with a short description of the included characters. The default
is full (recognizing all characters known to ssocr in the image).

COMMANDS

dilation [N]
Filter image using dilation algorithm. Any pixel with at least one neighbour pixel set in
the source image will be set in the filtered image. If a number N > 1 is specified, the
dilation algorithm is executed N times.

erosion [N]
Filter image using erosion algorithm. Any pixel with every neighbour pixel set in the
source image will be set in the filtered image. If a number N > 1 is specified, the
erosion algorithm is executed N times.

closing [N]
Filter image using closing algorithm, i.e. erosion and then dilation. If a number N > 1
is specified, N times dilation and then N times erosion is executed.

opening [N]
Filter image using opening algorithm, i.e. dilation and then erosion. If a number N > 1
is specified, N times dilation and then N times erosion is executed.

remove_isolated
Remove any foreground pixels without neighbouring foreground pixels.

make_mono
Convert the image to monochrome using thresholding. The threshold can be specified with
option --threshold and is adjusted to the used luminance interval of the image unless
option --absolute-threshold is used.

grayscale
Transform image to gray values using luminance. The formula to compute luminance can be
specified using option --luminance.

invert
Set every foreground pixel to background color and vice versa.

gray_stretch T1 T2
Transform image so that the luminance interval [ T1,T2 ] is projected to [ 0,255 ] with
any value below T1 set to 0 and any value above T2 set to 255. Together with the option
--adjust-gray, the values T1 and T2 are interpreted as percentages.

dynamic_threshold W H
Convert the image to monochrome using dynamic thresholding a.k.a local adaptive
thresholding. A window of width W and height H around the current pixel is used to
determine the (local) thresholding value. Consider using the --absolute-threshold option
together with a manually adjusted --threshold for predictable results.

rgb_threshold
Convert the image to monochrome using simple thresholding for every color channel. This
is the same as --luminance=minimum make_mono. You should use --luminance=minimum and
make_mono or dynamic_threshold instead.

r_threshold
Convert the image to monochrome using simple thresholding. Only the red color channel is
used. This is the same as --luminance=red make_mono. You should use --luminance red and
make_mono or dynamic_threshold instead.

g_threshold
Convert the image to monochrome using simple thresholding. Only the green color channel
is used. This is the same as --luminance=green make_mono. You should use --luminance
green and make_mono or dynamic_threshold instead.

b_threshold
Convert the image to monochrome using simple thresholding. Only the blue color channel is
used. This is the same as --luminance=blue make_mono. You should use --luminance blue
and make_mono or dynamic_threshold instead.

white_border [WIDTH]
The border of the image is set to the foreground color. This border is one pixel wide
unless a WIDTH > 1 is specified.

shear OFFSET
Shear the image OFFSET pixels to the right. The OFFSET is used at the bottom. Image
dimensions do not change, pixels in background color are used for pixels that are outside
the image and shifted inside. Pixels shifted out of the image are dropped. Many seven
segment displays use slightly skewed digits, this command can be used to compensate this.
Sometimes ssocr(1) cannot separate a decimal point from the preceding digit without
shearing the image.

rotate THETA
Rotate the image THETA degrees clockwise around the center of the image. Image dimensions
do not change, pixels rotated out of the image area are dropped, pixels from outside the
image rotated into the new image are set to the background color.

mirror { horiz | vert }
Mirror the image horizontally or vertically.

crop X Y W H
Use only the subpicture with upper left corner ( X,Y ), width W and height H.

set_pixels_filter MASK
Set every pixel in the filtered image that has at least MASK neighbour pixels set in the
source image.

keep_pixels_filter MASK
Keep only those foreground pixels in the filtered image that have at least MASK neighbour
pixels set in the source image (not counting the checked pixel itself).

LUMINANCE KEYWORDS

       •      rec601

       •      rec709

       •      linear

       •      minimum

       •      maximum

       •      red

       •      green

       •      blue

CHARACTER SET KEYWORDS

       •      full

       •      digits

       •      decimal

       •      hex

       •      tt_robot

EXIT STATUS

       •      0, if the correct number of digits have been recognized

       •      1, if an incorrect number of digits have been found

       •      2, if not all digits have been recognized

       •      3, if only image processing was requested and successful

       •      42, if help or version info was requested

       •      99, if some other error occurred

ENVIRONMENT

       TMP can be used to specify a different directory for temporary files than /tmp.

BUGS

       Imlib2 (and therefore ssocr(1)) does not work well with Netpbm(1) images.

AUTHOR

       ssocr was written by Erik Auerswald <auerswal@unix-ag.uni-kl.de>.

COPYRIGHT

       Copyright  ©  2004-2022  Erik  Auerswald.   License  GPLv3+:  GNU  GPL  version 3 or later
       ⟨https://gnu.org/licenses/gpl.html⟩.
       This is free software: you are free to change and redistribute it.  There is NO  WARRANTY,
       to the extent permitted by law.