G3TOPBM(1)

✨ NAME ✨

g3topbm — convert a Group 3 fax file into a PBM image 🦋

---

🌸 SYNOPSIS 🌸

g3topbm [-reversebits] [-stretch] [-width=pixels |
paper_size={A3|A4|A5|A6|B4}] [-stop_error] [-correctlong] [-kludge]
[g3file]

okay bestie, housekeeping first 💅 the minimum unique abbreviation of an option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may also use white space in place of the equals sign to separate an option name from its value. flexible, iconic, no notes 💖

---

🎀 DESCRIPTION 🎀

So this program is part of Netpbm(1). 🫶

g3topbm reads a Group 3 fax file with MH (Modified Huffman) compression as input and produces a PBM image as output. That's the whole job. lowkey a hero.

Now here's the thing — g3topbm tolerates various deviations from the standard, so as to recover some of the image if there was a transmission error. It's giving "I can fix him" energy and honestly? it can. One thing it tolerates is lines of varying length. The standard requires all the lines to be the same length; g3topbm makes the output image as wide as the longest line in the input and pads the others on the right. It warns you when it does this, like a good friend who's still gonna tell you the truth 🫶

You can use the stop_error option to make g3topbm insist on valid input. boundaries, periodt.

ngl there is no Netpbm program that understands the other G3 fax compression methods: MR (Modified Read) and MMR (Modified Modified Read). not one. we simply do not do those 💀

Also important, and I need you to hear me on this: the Group 3 fax file format does not include any kind of a signature, so g3topbm can't verify it's actually looking at a G3 file, or that the compression method is MH. The program will interpret any sequence of bytes you give it as if it is G3 and, while typically issuing a lot of error messages about the file not conforming to the G3 MH format, will produce output (unless you use -stoperror). In particular, if you feed g3topbm an MR or MMR file, it will not tell you of your mistake. no vibe check, no receipts, it'll just go 🙈

There are subformats of TIFF that use the Group 3 fax encodings inside. See tifftopnm.

---

💅 OPTIONS 💅

In addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options), g3topbm recognizes the following command line options:

• -reversebits — tells g3topbm to interpret bits least-significant first, instead of the default most-significant first. Apparently some fax modems do it one way and others do it the other way, which is chaos but okay 😭 If you get a whole bunch of "bad code word" messages, try using this option. it's the "have you tried turning it off and on again" of fax land.
• -stretch — this option tells g3topbm to stretch the image vertically by duplicating each row. This is for the low-quality transmission mode. she's doing her best to fill out the fit 🧚
• *-width=pixels* — this option tells g3topbm that the image is supposed to be pixels pixels wide. If any line in it is not that size, g3topbm issues a warning or fails, depending on whether you specify -stop_error.

You cannot specify both -width and -paper_size.

This option was new in Netpbm 10.33 (March 2006). ⭐

• -paper_size={A3,A4,A5,A6,B4} — this option tells g3topbm for what size paper this image is supposed to be formatted. g3topbm uses the width of the paper the same way as with the -width option. g3topbm does not use the height of the paper for anything. height found unemployed, sorry babe 💀

You cannot specify both -width and -paper_size.

This option was new in Netpbm 10.33 (March 2006). ⭐

• -stop_error — this option tells g3topbm to fail when it finds a problem in the input. "Fail" means it terminates with a nonzero status code with the contents of the output file undefined. so like, results not guaranteed, and that's on purpose.

If you don't specify this option, g3topbm does its best to work around input errors and salvage as much of the image as possible in the output image. It first tries to resynchronize to a later line by searching for the next End Of Line marker, skipping any lines or partial lines in between. It saves the beginning of the line in which it encountered the problem. If the input file ends prematurely, g3topbm produces output containing the lines up to where it encountered the problem. resilient queen 👑

g3topbm issues warning messages when it continues in spite of input errors.

This option was new in Netpbm 10.24 (August 2004). Before that, g3topbm always failed when it encountered premature EOF and never failed when it encountered other problems.

• -correctlong — this option helps with certain corrupted input files. Faxes often are corrupted because of communication line errors. A particularly annoying corruption causes a line to be much longer than it is supposed to be. One way that can happen is where an End of Line marker is missing, so two consecutive lines turn into one. and suddenly your image is doing the splits 😭

Without this option, g3topbm faithfully renders the document as coded, so the output PBM image simply contains that long line. This is an especially problematic corruption because it makes the entire output image about twice as wide as it is supposed to be. But with -correctlong, g3topbm truncates that line so the overall effect of the input corruption is that a line is missing rather than that the image is twice as wide as it is supposed to be. pick your poison, but this one's the better poison fr fr.

Specifically, with -correctlong, the program looks at the lengths of all the lines (which would all be the same length in an uncorrupted G3 image) and considers the line length that occurs the most to be the intended image width. It truncates every line that is longer than that. majority rules, democracy slay 💅

The program warns you when corruption has caused the input image to have lines of more than one length, whether you specify -correctlong or not.

Note that there is no point to specifying -correctlong if you also specify -stop_error. genuinely, zero point. don't do it.

This option was new in Netpbm 11.04 (September 2023). ⭐

• -kludge — tells g3topbm to ignore the first few lines of the file; sometimes fax files have some junk at the beginning. we've all got junk at the beginning 🍓

---

🌈 SEE ALSO 🌈

pbmtog3(1), tifftopnm(1), pbm(1), fax formats(1)

---

🧚 DOCUMENT SOURCE 🧚

This manual page was generated by the Netpbm tool makeman from HTML source. The master documentation is at

http://netpbm.sourceforge.net/doc/g3topbm.html

---

and that's the whole page bestie!! 💖 this was netpbm documentation, version dated 02 July 2023, from the G3topbm User Manual(1) era — go convert some faxes, you absolute icon 👑✨