ssocr - optical recognition of seven segment displays
ssocr [OPTION]... [COMMAND]... IMAGE
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 can be used to change ssocr behavior.
Commands can be used to manipulate the input IMAGE before starting the recognition algorithm.
Two hyphens (--) can be used as a special argument to end option-scanning, e.g., in order to use a negative number as argument to a command.
When using a single character (i.e., short) option, arguments can either directly follow the option character, or can be separated from the option character by whitespace. When using a multi character (i.e., long) option, arguments must be separated from the option by either an equals sign (=), or whitespace.
-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. This does not apply to
ratio based recognition. Can be used to ignore some noise in
the picture. See the web page of ssocr(1) for a
description of the algorithm.
-N,
--min-segment SIZE
Set the minimum number of pixels required for width and
height of an individual segment of a seven segment display.
A set segment in the display must have both a width and
height of at least SIZE pixels. This minimum is used
for both scanline based and ratio based recognition. It is
not applied to decimal separator detection, because those
are not comprised of regular segments. This option 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 or row 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.
-M,
--min-char-dims WIDTHxHEIGHT
Specify the minimum dimensions of characters respectively
digits. When the segmentation step finds potential digits,
those with a width less than WIDTH or a height less
than HEIGHT are ignored. 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 RANGE
Specifies the number of digits shown in the image. Default
value is 6. Use -1 to automatically detect the
number of digits. Use a single positive number to specify an
exact number of digits. Use two positive numbers separated
with a hyphen (-) to specify an inclusive range of
acceptable values for the number of digits.
-r,
--one-ratio RATIO
Set the height/width ratio threshold to recognize a digit as
a one. A digit with a height/width ratio greater than
RATIO is recognized 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. A
digit with a width/height ratio greater than or equal to
RATIO is recognized as a minus sign. RATIO
takes integers only. 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. RATIO takes integers only.
This value is used in combination with the
max_digit_width/width ratio. If the height of a digit is
less than 1/RATIO of the maximum digit height in the
image and the max_digit_width/width threshold is also
reached, it is recognized as a decimal separator.
-W,
--dec-w-ratio RATIO
Set the max_digit_width/width ratio used for recognition of
a decimal separator. RATIO takes integers only. This
value is used in combination with the
max_digit_height/height ratio. If the width of a digit is
less than 1/RATIO of the maximum digit width in the
image and the max_digit_height/height threshold is also
reached, it is recognized as a decimal separator.
-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 (default) or
average 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).
Most commands do not change the image dimensions. The crop command is a notable exception to this rule.
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 background 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.
This command changes the image dimensions.
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).
• |
rec601 |
|||
• |
rec709 |
|||
• |
linear |
|||
• |
minimum |
|||
• |
maximum |
|||
• |
red |
|||
• |
green |
|||
• |
blue |
• |
full |
|||
• |
digits |
|||
• |
decimal |
|||
• |
hex |
|||
• |
tt_robot |
• |
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 |
TMP can be used to specify a different directory for temporary files than /tmp.
Imlib2 (and therefore ssocr(1)) does not work well with Netpbm(1) images.
ssocr was written by Erik Auerswald <auerswal@unix-ag.uni-kl.de>.
Copyright
© 2004-2024 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.
netpbm(1),
ImageMagick(1),
https://www.unix-ag.uni-kl.de/~auerswal/ssocr/