.TH ssocr 1 "2023-05-18" "2.23.1" "OCR for seven segment displays"
.SH NAME
ssocr \- optical recognition of seven segment displays
.SH SYNOPSIS
.B ssocr [OPTION]... [COMMAND]... IMAGE
.SH DESCRIPTION
.B 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
.B \-
as file name to read the image from standard input.
.B ssocr
provides several image manipulation algorithms to enhance noisy images.
.PP
.B Options
can be used to change
.B ssocr
behavior.
.B Commands
can be used to manipulate the input
.I IMAGE
before starting the recognition algorithm.
Two hyphens
.RB ( \-\- )
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.
.SH OPTIONS
.SS \-h, \-\-help
Write a help message to standard output.
The default settings are shown as well.
.SS \-V, \-\-version
Write version information to standard output.
.SS \-v, \-\-verbose
Print information about program execution to standard error.
.SS \-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
.B \-\-absolute\-threshold
is used. The default threshold is
.IR 50 .
.SS \-a, \-\-absolute\-threshold
Do not adjust the threshold to the luminance values occurring in the image.
Consider this option when using the
.B dynamic_threshold
command.
.SS \-T, \-\-iter\-threshold
Use an iterative method (one-dimensional k-means clustering) to determine the
threshold. The starting value can be specified with the
.B \-\-threshold
option.
.SS \-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
.BR ssocr (1)
for a description of the algorithm.
.SS \-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
.B 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
.BR ssocr (1)
for a description of the algorithm.
.SS \-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
.BR ssocr (1)
for a description of the algorithm.
.SS \-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
.B WIDTH
or a height less than
.B HEIGHT
are ignored.
Can be used to ignore some noise in the picture.
See the web page of
.BR ssocr (1)
for a description of the algorithm.
.SS \-d, \-\-number\-digits RANGE
Specifies the number of digits shown in the image. Default value is
.IR 6 .
Use
.I \-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
.RI ( - )
to specify an inclusive range of acceptable values for the number of digits.
.SS \-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
.B RATIO
is recognized as a one.
.B RATIO
takes integers only.
See the web page of
.BR ssocr (1)
for a description of the algorithm.
.SS \-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
.B RATIO
is recognized as a minus sign.
.B RATIO
takes integers only.
This uses the same idea as recognizing the digit one.
.SS \-H, \-\-dec\-h\-ratio RATIO
Set the max_digit_height/height ratio used for recognition of a decimal
separator.
.B 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
.RB 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.
.SS \-W, \-\-dec\-w\-ratio RATIO
Set the max_digit_width/width ratio used for recognition of a decimal separator.
.B 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
.RB 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.
.SS \-o, \-\-output\-image FILE
Write the processed image to
.BR FILE .
Use
.B \-
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
.B \-\-process\-only
option.
.SS \-O, \-\-output\-format FORMAT
Specify the image format to use with
.BR \-\-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,
.IR png
is used.
.SS \-p, \-\-process\-only
Use
.BR ssocr (1)
as an image manipulation program.
No image recognition is performed.
Should be used together with the
\-B \-\-output\-image
option.
.SS \-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
.I testbild.png
unless a filename
.B FILE
is given.
This debug image often helps in understanding why
.BR ssocr (1)
does not recognize the number from a given image.
.SS \-P, \-\-debug\-output
Print information helpful for debugging to standard error.
.SS \-f, \-\-foreground COLOR
Specify the foreground color (either
.I black
or
.IR white ).
This automatically sets the background color as well.
Default is
.IR black .
.SS \-b, \-\-background COLOR
Specify the background color (either
.I black
or
.IR white ).
This automatically sets the foreground color as well.
Default is
.IR white .
.SS \-I, \-\-print\-info
Prints image dimensions and range of used luminance values to standard error.
.SS \-g, \-\-adjust\-gray
Interpret the values
.B T1
and
.B T2
given to the command
.B gray_stretch
as percentages instead of absolute luminance values.
.SS \-l, \-\-luminance KEYWORD
Choose the type of luminace computation.
Using
.I help
as
.B KEYWORD
prints the list of implemented luminance keywords with a short description of
the used formula.
The default of
.I Rec709
should work well in most cases.
.SS \-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).
.SS \-A, \-\-space\-factor FACTOR
Use the given
.B FACTOR
instead of the default value to determine white space between digits
(characters).
.SS \-G, \-\-space\-average
Use the average distance between digits (characters) instead of the minimum
distance to determine white space between digits.
.SS \-S, \-\-ascii\-art\-segments
Prints the recognized segments, i.e. the display as seen by
.BR ssocr ,
as ASCII art to standard error.
.SS \-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).
.I 0x01
represents the upper horizontal segment,
.I 0x02
represents the upper left vertical segment,
.I 0x04
represents the upper right vertical segment,
.I 0x08
represents the middle horizontal segment,
.I 0x10
represents the lower left vertical segment,
.I 0x20
represents the lower right vertical segment,
.I 0x40
represents the lower horizontal segment,
.I 0x80
represents a decimal point (or comma or thousands separator).
Each hexadecimal number printed is the logical
.I or
of the set segments.
.SS \-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.
.SS \-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
.I 6
(with digits and decimal) or
.I b
(with hexadecimal and full).
Using
.I help
as
.B KEYWORD
prints the list of implemented character set keywords with a short description
of the included characters.
The default is
.I full
(recognizing all characters known to ssocr in the image).
.SH COMMANDS
Most commands do not change the image dimensions.
The
.B crop
command is a notable exception to this rule.
.SS 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
.B N
>
.I 1
is specified, the dilation algorithm is executed
.B N
times.
.SS 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
.B N
>
.I 1
is specified, the erosion algorithm is executed
.B N
times.
.SS closing [N]
Filter image using closing algorithm, i.e. erosion and then dilation.
If a number
.B N
>
.I 1
is specified,
.B N
times dilation and then
.B N
times erosion is executed.
.SS opening [N]
Filter image using opening algorithm, i.e. dilation and then erosion.
If a number
.B N
>
.I 1
is specified,
.B N
times dilation and then
.B N
times erosion is executed.
.SS remove_isolated
Remove any foreground pixels without neighbouring foreground pixels.
.SS make_mono
Convert the image to monochrome using thresholding.
The threshold can be specified with option
.B \-\-threshold
and is adjusted to the used luminance interval of the image unless option
.B \-\-absolute\-threshold
is used.
.SS grayscale
Transform image to gray values using luminance.
The formula to compute luminance can be specified using option
.BR \-\-luminance .
.SS invert
Set every foreground pixel to background color and vice versa.
.SS gray_stretch T1 T2
Transform image so that the luminance interval [
.BR T1 , T2
] is projected to [
.IR 0 , 255
] with any value below
.B T1
set to
.I 0
and any value above
.B T2
set to
.IR 255 .
Together with the option
.BR \-\-adjust\-gray ,
the values
.B T1
and
.B T2
are interpreted as percentages.
.SS dynamic_threshold W H
Convert the image to monochrome using dynamic thresholding a.k.a local
adaptive thresholding.
A window of width
.B W
and height
.B H
around the current pixel is used to determine the (local) thresholding value.
Consider using the
.B \-\-absolute\-threshold
option together with a manually adjusted
.B \-\-threshold
for predictable results.
.SS rgb_threshold
Convert the image to monochrome using simple thresholding for every color
channel.
This is the same as
.B \-\-luminance=minimum make_mono.
You should use
.B \-\-luminance=minimum
and
.B make_mono
or
.B dynamic_threshold
instead.
.SS r_threshold
Convert the image to monochrome using simple thresholding.
Only the red color channel is used.
This is the same as
.B \-\-luminance=red make_mono.
You should use
.B \-\-luminance red
and
.B make_mono
or
.B dynamic_threshold
instead.
.SS g_threshold
Convert the image to monochrome using simple thresholding.
Only the green color channel is used.
This is the same as
.B \-\-luminance=green make_mono.
You should use
.B \-\-luminance green
and
.B make_mono
or
.B dynamic_threshold
instead.
.SS b_threshold
Convert the image to monochrome using simple thresholding.
Only the blue color channel is used.
This is the same as
.B \-\-luminance=blue make_mono.
You should use
.B \-\-luminance blue
and
.B make_mono
or
.B dynamic_threshold
instead.
.SS white_border [WIDTH]
The border of the image is set to the foreground color.
This border is one pixel wide unless a
.B WIDTH
>
.I 1
is specified.
.SS shear OFFSET
Shear the image
.B OFFSET
pixels to the right.
The
.B 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
.BR ssocr (1)
cannot separate a decimal point from the preceding digit
without shearing the image.
.SS rotate THETA
Rotate the image
.B 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.
.SS mirror { horiz | vert }
Mirror the image horizontally or vertically.
.SS crop X Y W H
Use only the subpicture with upper left corner (
.BR X , Y
), width
.B W
and height
.BR H .
This command changes the image dimensions.
.SS set_pixels_filter MASK
Set every pixel in the filtered image that has at least
.B MASK
neighbour pixels set in the source image.
.SS keep_pixels_filter MASK
Keep only those foreground pixels in the filtered image that have at least
.B MASK
neighbour pixels set in the source image (not counting the checked pixel itself).
.SH "LUMINANCE KEYWORDS"
.IP \(bu
rec601
.IP \(bu
rec709
.IP \(bu
linear
.IP \(bu
minimum
.IP \(bu
maximum
.IP \(bu
red
.IP \(bu
green
.IP \(bu
blue
.SH "CHARACTER SET KEYWORDS"
.IP \(bu
full
.IP \(bu
digits
.IP \(bu
decimal
.IP \(bu
hex
.IP \(bu
tt_robot
.SH EXIT STATUS
.IP \(bu
0, if the correct number of digits have been recognized
.IP \(bu
1, if an incorrect number of digits have been found
.IP \(bu
2, if not all digits have been recognized
.IP \(bu
3, if only image processing was requested and successful
.IP \(bu
42, if help or version info was requested
.IP \(bu
99, if some other error occurred
.SH ENVIRONMENT
.B TMP
can be used to specify a different directory for temporary files than
.BR /tmp .
.SH BUGS
Imlib2 (and therefore
.BR ssocr (1))
does not work well with
.BR Netpbm (1)
images.
.SH AUTHOR
.B ssocr
was written by Erik Auerswald <auerswal@unix\-ag.uni\-kl.de>.
.SH COPYRIGHT
Copyright \(co 2004-2023 Erik Auerswald.
License GPLv3+: GNU GPL version 3 or later
.UR https://gnu.org/licenses/gpl.html
.UE .
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH "SEE ALSO"
.BR netpbm (1),
.BR ImageMagick (1),
.P
.UR https://www.unix\-ag.uni\-kl.de/~auerswal/ssocr/
.UE