ssocr(1) OCR for seven segment displays ssocr(1) 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 dis- play, 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 manipula- tion 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. 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 occur- ring 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. Using this option also inhibits iterative thresholding using option --iter-threshold. Consider this option when using the dynamic_threshold or gray_stretch commands. -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 op- tion. Option --absolute-threshold inhibits iterative threshold determina- tion. -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 indi- vidual 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 ap- plied to decimal separator detection, because those are not comprised of regular segments. This option can be used to ignore some noise in the pic- ture. 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 sep- arated 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 dec- imal separator. -W, --dec-w-ratio RATIO Set the max_digit_width/width ratio used for recognition of a decimal sepa- rator. 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. Un- less this option is used no image is written to disk. If a standard file- name 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 test- bild.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 im- age. -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 er- ror. -g, --adjust-gray Interpret the values T1 and T2 given to the command gray_stretch as per- centages 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 dig- its (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 seg- ment, 0x02 represents the upper left vertical segment, 0x04 represents the upper right vertical segment, 0x08 represents the middle horizontal seg- ment, 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 auto- matically detecting the number of digits to ignore isolated groups of pix- els 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 (recog- nizing all characters known to ssocr in the image). -F, --adapt-after-crop When using the crop command, adjust (adapt) the threshold to image lumi- nance values only after cropping, not also directly before. Using other commands before crop can still lead to adapting the threshold to the origi- nal image. COMMANDS 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 neigh- bour 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 ex- ecuted. 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 ex- ecuted. 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 in- terval of the image unless option --absolute-threshold is used. grayscale Transform image to gray values using luminance. The formula to compute lu- minance 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 inter- preted as percentages. Consider using the --absolute-threshold option to- gether with a manually adjusted --threshold for predictable results. 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 --thresh- old 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 in- stead. 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 bot- tom. 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 pix- els 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 (C) 2004-2025 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. SEE ALSO netpbm(1), ImageMagick(1), https://www.unix-ag.uni-kl.de/~auerswal/ssocr/ 2.25.1 2025-10-31 ssocr(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | LUMINANCE KEYWORDS | CHARACTER SET KEYWORDS | EXIT STATUS | ENVIRONMENT | BUGS | AUTHOR | COPYRIGHT | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ssocr&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>