ssocr(1)

📦
version 2.25.1 · 5 versions
, in nixos 26.05, ubuntu resolute, ubuntu stonking

💖 NAME 💖

ssocr — optical recognition of seven segment displays. yep bestie, you're reading the ssocr(1) manual page and it's about to be your whole personality 💅

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

Okay so here's the vibe: ssocr reads an image file that has a picture of a seven segment display in it, figures out which digits are showing, and prints them to standard output. That's it. That's the whole job. 🌟

Every image format that imlib2 knows about is supported. And if you want to pipe stuff in, just use - as the file name and it'll read the image straight from standard input. No cap. 🫶

ssocr also ships with a bunch of image manipulation algorithms, so if your image is noisy and messy (it's giving ✨ chaos ✨) you can clean it up first.

  • Options change how ssocr behaves.
  • Commands let you manipulate the input IMAGE before the recognition algorithm even starts doing its thing.

Two hyphens (--) can be used as a special argument to end option-scanning, like when you need to use a negative number as an argument to a command. Sneaky but iconic.

Now, argument-passing rules, because yes there are rules:

  • When you're using a single character (i.e., short) option, the arguments can either follow the option character directly, or be separated from it by whitespace. Both are fine, she's flexible 💁‍♀️
  • When you're using a multi character (i.e., long) option, the arguments must be separated from the option by either an equals sign (=) or whitespace. Periodt.

👑 OPTIONS 👑

-h, --help

Writes a help message to standard output. And yes, the default settings get shown too, so you can peek at all the defaults without guessing. 🎀

-V, --version

Writes version information to standard output. Slay.

-v, --verbose

Prints information about program execution to standard error. Chatty queen behavior, we love it. 💬

-t, --threshold THRESHOLD

Specify a percentage value as the luminance threshold that differentiates between black and white. This threshold is adjusted to the luminance values occurring in the image, unless you're using --absolute-threshold. 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 via --iter-threshold. Consider reaching for this one when you're using the dynamic_threshold or gray_stretch commands. 💅

-T, --iter-threshold

Use an iterative method (one-dimensional k-means clustering) to determine the threshold. You can set the starting value with the --threshold option. Heads up: --absolute-threshold inhibits iterative threshold determination.

-n, --number-pixels NUMBER

Set the number of foreground pixels that have to be found in a scanline to recognize a segment. Note: this does not apply to ratio based recognition. Handy for ignoring 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 the 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 gets used for both scanline based and ratio based recognition. It is not applied to decimal separator detection, because those aren't comprised of regular segments. Great for ignoring 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 get ignored when deciding if a column or row consists only of background or foreground pixels. Another noise-ignoring tool in your arsenal. 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. Noise begone. 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. Here's the menu of choices:

  • 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 gets recognized as a decimal separator. Teamwork fr fr 🤝

-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 gets 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 gets interpreted as the image format to use. Can be super 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. This overwrites the image file format automatically determined via the filename. And if no format is specified via this option or the filename, png is used. Default queen behavior honestly. 👑

-p, --process-only

Use ssocr(1) as an image manipulation program. No image recognition is performed at all. 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 is genuinely so helpful for understanding why ssocr(1) doesn't recognize the number from a given image. Detective mode 🔎

-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. Receipts! 🧾

-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 luminance 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). Spreading them out, respectfully. 🌸

-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. This is so fun to look at, ngl 🎨

-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). Here's the decoder ring, memorize it bestie:

  • 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. Bit math, but make it cute. 🔥

-C, --omit-decimal-point

Omit decimal points from output. Decimal points are still recognized and counted against the number of digits though — they're not getting erased from existence, just from the printout. 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). 💖

-F, --adapt-after-crop

When using the crop command, adjust (adapt) the threshold to image luminance values only after cropping, not also directly before. Note: using other commands before crop can still lead to adapting the threshold to the original image. 🌈

🌟 COMMANDS 🌟

Okay bestie, listen — this is the fun part. 💅 Most of these commands do not change the image dimensions. They just vibe-check your pixels in place, no resizing, no drama.

⚠️ One exception, and it's a big one: the crop command absolutely does change the image dimensions. That's literally its whole thing. Keep that in mind, fr fr.

🫧 dilation [N]

Filter the image with the dilation algorithm. The rule is simple: any pixel that has at least one neighbour pixel set in the source image gets set in the filtered image too. It's giving "if your friend is here, you're here" energy. 🫶

If you pass a number N > 1, the dilation algorithm runs N times. Slay, stacking effects.

🫧 erosion [N]

Filter the image with the erosion algorithm. Opposite vibe: a pixel gets set in the filtered image only if every single neighbour pixel is set in the source image. No weak links allowed. 😤

If you pass a number N > 1, the erosion algorithm runs N times.

🫧 closing [N]

Filter the image with the closing algorithm, i.e. erosion and then dilation. ✨

If you pass a number N > 1, then N times dilation and then N times erosion is executed.

👀 bestie read that twice: the original manual says exactly that, so I'm keeping it exactly that. No editing, no cap.

🫧 opening [N]

Filter the image with the opening algorithm, i.e. dilation and then erosion. 🌸

If you pass a number N > 1, then N times dilation and then N times erosion is executed.

🫧 remove_isolated

Delete any foreground pixels that don't have any neighbouring foreground pixels. Lone wolf pixels? Gone. Blocked. Unfollowed. 💀

🫧 make_mono

Convert the image to monochrome using thresholding. The threshold can be set with the --threshold option, and it gets adjusted to the used luminance interval of the image — unless you're using the --absolute-threshold option. 🎚️

🫧 grayscale

Transform the image to gray values using luminance. The formula used to compute that luminance can be chosen with the --luminance option. 🌈➡️🩶

🫧 invert

Set every foreground pixel to the background color, and every background pixel to the foreground color. Flip era. 🔄

🫧 gray_stretch T1 T2

Transform the image so that the luminance interval [ T1,T2 ] is projected onto [ 0,255 ], with anything below T1 set to 0 and anything above T2 set to 255. 📈

Together with the --adjust-gray option, the values T1 and T2 are interpreted as percentages.

💡 heads up: consider using the --absolute-threshold option together with a manually adjusted --threshold if you want 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 figure out the (local) thresholding value. 🔍

💡 same energy as above: 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.

🚨 bestie, listen to the manual: you should use --luminance=minimum and make_mono or dynamic_threshold instead.

🫧 r_threshold

Convert the image to monochrome using simple thresholding, using only the red color channel. This is the same as --luminance=red make_mono.

🚨 again: you should use --luminance red and make_mono or dynamic_threshold instead.

🫧 g_threshold

Convert the image to monochrome using simple thresholding, using only the green color channel. This is the same as --luminance=green make_mono.

🚨 once more: you should use --luminance green and make_mono or dynamic_threshold instead.

🫧 b_threshold

Convert the image to monochrome using simple thresholding, using only the blue color channel. This is the same as --luminance=blue make_mono.

🚨 last one I promise: you should use --luminance blue and make_mono or dynamic_threshold instead.

🫧 white_border [WIDTH]

The border of the image gets set to the background color. 🖼️ That border is one pixel wide unless you specify a WIDTH > 1.

🫧 shear OFFSET

Shear the image OFFSET pixels to the right. That OFFSET is applied at the bottom.

Image dimensions do not change. Pixels in background color are used for pixels that were outside the image and got shifted inside. Pixels shifted out of the image are just dropped, bye. 💨

Why would you do this? Because many seven segment displays use slightly skewed digits, and this command compensates for that. And honestly? Sometimes ssocr(1) cannot separate a decimal point from the preceding digit without shearing the image. So yeah, it's a real one. 🎀

🫧 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, and pixels from outside the image that get rotated into the new image are set to the background color.

🫧 mirror { horiz | vert }

Mirror the image horizontally or vertically. That's it, that's the command. 🪞✨

🫧 crop X Y W H

Use only the subpicture whose upper left corner is ( X,Y ), with width W and height H. ✂️

🚨 THIS COMMAND CHANGES THE IMAGE DIMENSIONS. The one and only. You've been warned. 💅

🫧 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 — and no, it doesn't count the pixel being checked itself. 🧐

🌈 LUMINANCE KEYWORDS 🌈

The glow-up vocabulary for --luminance:

  • rec601
  • rec709
  • linear
  • minimum
  • maximum
  • red
  • green
  • blue

🎀 CHARACTER SET KEYWORDS 🎀

Your options for the character set, bestie:

  • full
  • digits
  • decimal
  • hex
  • tt_robot

💀 EXIT STATUS 💀

What the exit code is telling you, decoded:

  • 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 it was successful. ✨
  • 42 — if help or version info was requested. 👑 (yes, it's 42, iconic)
  • 99 — if some other error occurred. 💀

🦋 ENVIRONMENT 🦋

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

🐛 BUGS 🐛

Real talk: Imlib2 (and therefore ssocr(1)) does not work well with Netpbm(1) images. Not our fault, we're just the messenger. 😭

👑 AUTHOR 👑

ssocr was written by Erik Auerswald <auerswal@unix-ag.uni-kl.de>. Thank you for your service, king. 🫶

Copyright © 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. (Yes, in caps. It means it. 🙈)

🔍 SEE ALSO 🔍

okay that's the whole page bestie, you ate it 🎀 This one's ssocr(1) version 2.25.1, dated 2025-10-31. Go forth and read some seven-segment digits, you absolute main character. 💅✨🦋

📦 where this page comes from