pbmpage

Generate a test pattern for printing onto US standard paper

$ pbmpage > [path/to/file.pbm]

$ pbmpage -a4 > [path/to/file.pbm]

$ pbmpage [1|2|3] > [path/to/file.pbm]

pbmpage [-columns=N] [-rows=N] [-margin=N] [-header] [-trailer] [-landscape | -portrait] [-page=NAME] [-left=N] [-right=N] [-top=N] [-bottom=N] [-lmargin=N] [-rmargin=N] [-tmargin=N] [-bmargin=N] [-headerfont=NAME] [-footerfont=NAME] [-headertext=TEXT] [-footertext=TEXT] [-nohdr] [-nofoot] [-scale=N] [-xres=N] [-yres=N] [-dpi=N] [pbmfile ...]

-columns=N
    Specifies the number of columns per page.

-rows=N
    Specifies the number of rows per page.

-margin=N
    Sets a uniform margin in pixels around the entire page and between images. Overridden by specific margin options.

-header
    Includes a header on each page, showing the filename.

-trailer
    Includes a trailer (footer) on each page, showing the filename.

-landscape
    Formats pages in landscape orientation (width > height).

-portrait
    Formats pages in portrait orientation (height > width). This is the default.

-page=NAME
    Specifies a predefined page size (e.g., letter, a4). Overrides xres and yres.

-left=N
    Sets the left margin in pixels.

-right=N
    Sets the right margin in pixels.

-top=N
    Sets the top margin in pixels.

-bottom=N
    Sets the bottom margin in pixels.

-lmargin=N
    Sets the left margin in pixels (same as left).

-rmargin=N
    Sets the right margin in pixels (same as right).

-tmargin=N
    Sets the top margin in pixels (same as top).

-bmargin=N
    Sets the bottom margin in pixels (same as bottom).

-headerfont=NAME
    Specifies the font for the header text. Defaults to fixed.

-footerfont=NAME
    Specifies the font for the footer text. Defaults to fixed.

-headertext=TEXT
    Specifies custom text for the header. Overrides header option.

-footertext=TEXT
    Specifies custom text for the footer. Overrides trailer option.

-nohdr
    Suppresses all headers.

-nofoot
    Suppresses all footers.

-scale=N
    Scales all input images by a factor of N (e.g., 0.5 for half size).

-xres=N
    Sets the desired page width in pixels.

-yres=N
    Sets the desired page height in pixels.

-dpi=N
    Sets the dots per inch for resolution calculations, affecting xres and yres if page option is used. Defaults to 75.

pbmpage is a utility from the Netpbm package designed to combine several portable bitmap (PBM) images into a single, larger PBM image, formatted as pages suitable for printing. It allows users to specify the layout, such as the number of columns and rows, margins, and the inclusion of headers and footers.
This command is particularly useful for creating contact sheets, printing multiple small images on one sheet of paper, or preparing image sequences for output. It takes one or more PBM files as input and outputs a single PBM file to standard output, which can then be converted to other formats (e.g., PostScript) using other Netpbm tools or printed directly if the printer supports PBM. The tool handles scaling and positioning to fit the specified page dimensions and layout.

pbmpage specifically works with PBM (Portable BitMap) format files. Input files must be in PBM format. While other Netpbm tools can convert to/from PBM (e.g., anytopnm), pbmpage itself does not perform format conversions. Output is also in PBM format, meaning further conversion (e.g., to PostScript using pnmtops) is often required for printing or viewing in common image viewers. Header/footer text formatting is basic and uses specific fonts; advanced text layout or graphics are not supported.

pbmpage reads PBM images from the files specified on the command line. If no files are given, it reads from standard input. The resulting single, combined PBM image is written to standard output. This design allows for easy piping with other Netpbm tools, such as anytopnm before pbmpage and pnmtops after it.

When using the -page option, pbmpage uses standard paper sizes (like letter or a4) combined with the -dpi setting to calculate the output page dimensions in pixels. For example, -page=letter -dpi=300 would produce an 8.5x11 inch image at 300 DPI. If -xres and -yres are used, they directly specify the pixel dimensions, overriding any -page or -dpi calculations.

pbmpage is a long-standing utility within the Netpbm suite of graphics manipulation tools. The Netpbm project itself originated from Jef Poskanzer's pbmplus package, released in 1988, which introduced the Portable Anymap (PNM) formats (PBM, PGM, PPM). pbmpage was developed as part of this suite to provide basic page layout capabilities for bitmap images, primarily for printing on monochrome dot-matrix or laser printers common at the time. It has been maintained and refined over decades as part of the Netpbm project, though its core functionality remains focused on the PBM format, reflecting its historical roots.

pbm(5), pnm(5), anytopnm(1), pnmtoppm(1), pnmtops(1), pbmreduce(1), netpbm(1)