PNMPAD(1)

📦
version 11.13.03 · 10 versions
, in ubuntu stonking

okay so <rainbow>Pnmpad User Manual(1)</rainbow> — it hangs out in the General Commands Manual section, and bestie, it's a tiny little tool with one job and it does it flawlessly 💅✨

✨ NAME ✨

pnmpad — add borders to a PNM image. That's the whole vibe. Borders. On your PNM. 🎀

🌸 SYNOPSIS 🌸

pnmpad [-color=color [-promote={none|format|all}] |-detect-background
|-extend-edge |-white |-black ] [-width=pixels] [-halign=ratio]
[-mwidth=pixels] [-left=pixels] [-right=pixels] [-height=pixels]
[-valign=ratio] [-mheight=pixels] [-top=pixels] [-bottom=pixels]
[-reportonly] [-verbose] [pnmfile]

🦋 DESCRIPTION 🦋

This program is part of Netpbm(1). iykyk 🌈

pnmpad reads a Netpbm image as input and outputs a PNM image that is the input image plus borders of the color and sizes specified. boom. framed. periodt 💖

Now, listen, if you want borders that are a whole situation — solid color, pattern, whatever your heart desires — you can also use pamcomp to add borders of any content. For real. For example, if you wanted to add 10 pixels of rainbow borders to the top and bottom of a 100x100 image, you could create a 100x120 rainbow image (e.g. with ppmrainbow) and then use pamcomp to insert your 100x100 image into the center of it. main character framing energy, no cap 🌈✨

👑 OPTIONS 👑

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

All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. so flexible of it 🫶

  • -color=color
  • -detect-background
  • -extend-edge
  • -white
  • -black

All of those cuties above specify the color of the padding. Here's the whole tea ☕

color is like the argument of the pnm_parsecolor() library routine.

-detect-background means the program uses the color of the top left pixel of the input as the pad color. > heads up bestie: this could cause odd results if you aren't padding the top or left of the image. you've been warned 💀

You may specify only one of -white, -black, -color, and -detect-background. pick a lane, babe 💅

-extend-edge says to pad by duplicating the adjacent edge of the image pixel by pixel. E.g. if the top row of the image is 20 white pixels followed by 10 black pixels, every row of padding added to the top of the image is 20 white pixels followed by 20 black pixels. literally smearing the edge outward, obsessed ✨

By default, the padding is black.

-white and -black are for backward compatibility; they do the same thing as -color=white and -color=black respectively (except that the latter fail if you don't have a color dictionary set up in your environment, so they are really more like -color=rgbi:0/0/0 and -color=rgbi:1/1/1). -color, -detect-background, and -extend-edge were new with Netpbm 11.05 (December 2023). 🎀

  • -left=pixels
  • -right=pixels
  • -width=width
  • -halign=ratio
  • -mwidth=pixels

These specify the amount of left and right padding in pixels. horizontal girlies unite 🦋

-left and -right directly specify the amount of padding added to the left and right sides, respectively, of the image.

Alternatively, you can specify -width and just one of -left and -right, and pnmpad calculates the required padding on the other side to make the output width pixels wide. If the -width value is less than the width of the input image plus the specified padding, pnmpad ignores -width. (it simply does not see it. it is not the moment.)

If you specify all three of -width, -left, and -right, you must ensure that the -left and -right padding are sufficient to make the image at least as wide as -width specifies, and in that case -width has no effect on the output. Otherwise, pnmpad fails. 😭

When you specify -width without -left or -right, and -width is larger than the input image, pnmpad chooses left and right padding amounts in a certain ratio. That ratio defaults to half, but you can set it to anything (from 0 to 1) with the -halign option. If the input image is already at least as wide as -width specifies, pnmpad adds no padding.

Common values for -halign are:

  • 0.0 — left aligned
  • 0.5 — center aligned (default)
  • 1.0 — right aligned

-mwidth=pixels says to pad to a multiple of pixels pixels. E.g. if pixels is 10, the output image width will be a multiple of 10 pixels. pnmpad adds to whatever padding the other options say to do to get to this multiple. It divides that padding between the left and right sides of the image to maintain the ratio the other options produce. E.g. if you say -left=10 -right=10 -mwidth=50 with a 100-pixel image, you end up with a 150-pixel image with the extra padding split evenly between left and right for a total of 25 pixels of padding on the left and 25 on the right. If the other options indicate no padding, pnmpad adds padding in the ratio specified by -halign and if -halign is not specified, equally on both sides. mathematical and fair, we love to see it ✨

history moment 🕰️ Before Netpbm 10.97 (December 2021), pnmpad does not allow -halign with -mwidth and adds padding only on the right when -mwidth is specified and the other options indicate no padding. Before Netpbm 10.72 (September 2015), there is no -mwidth. Before Netpbm 10.23 (July 2004), pnmpad did not allow the -left or -right option together with -width.
  • -top=pixels
  • -bottom=pixels
  • -height=height
  • -valign=ratio
  • -mheight=pixels

These options determine the vertical padding. They are analogous to the horizontal padding options above. same energy, different axis 💜

🎨 the -promote one 🎨

  • -promote={none|format|all} — this option tells what to do when the -color option specifies a color that cannot be represented in the input format, which ordinarily is also the output format. For example, if the input is PGM (which can represent only shades of gray), and you specify -color=red, should pnmpad make the padding gray or make the output PPM? the drama 😭

Here are the three flavors:

  • none — Make the output have the same format and maxval as the input. Adjust the pad color to the nearest color possible in that format (black, white, or a shade of gray).
  • format — Make the output have the same maxval as the input, but make the output format PPM if the pad color is not black, white, or gray.
  • all — Make the format and maxval of the output capable of representing the pad color. Make the format the least expressive format capable of representing the pad color. Make the maxval the larger of 255 and the maxval of the input image.

The default is -promote=all. 👑

Note that this promotion happens even if no actual padding happens, meaning it isn't really necessary. The promotion is based on what would be required to represent padding of the specified color. it's doing it for the plot, not the practicality 💅

This option is valid only when you also specify -color.

This option was new in Netpbm 11.05 (December 2023).

🗣️ the reporty ones 🗣️

  • -reportonly — This causes pnmpad to write to Standard Output a description of the padding it would have done instead of producing an output image. See below for a description of this output and ways to use it.

This option was new in Netpbm 10.89 (December 2019).

  • -verbose — This causes verbose messages. chatty queen 🫶

📋 REPORT ONLY 📋

When you specify -reportonly, pnmpad does not produce an output image. Instead, it writes to Standard Output a description of the padding it would have done without -reportonly. like a little preview, so thoughtful 🌸

That description is one line of text, containing 6 decimal numbers of pixels, separated by spaces:

  • left padding
  • right padding
  • top padding
  • bottom padding
  • output width
  • output height

Example:

4 3 0 2 100 100

One use for this is to make padding which is fancier than the black and white that pnmpad can do. ✨

In the following example, we pad an image with 10 pixels of gray all around, without knowing the original image dimensions beforehand. We do this by generating a gray image with pbmmake and then pasting the subject image into the middle of it.

The example uses shell arrays, such as exist in Bash, but not Dash.

pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm))
pbmmake -gray ${pad[4]} ${pad[5]} | \
  pnmpaste input.ppm ${pad[0]} ${pad[2]} -

🕰️ HISTORY 🕰️

The command line syntax was originally more of a traditional Unix syntax, with single-character margin size options -l, -r, -t, and -b that took arguments concatenated to the option name, such as -l50. This is in contrast to the more modern syntax used by essentially all Netpbm programs, in which an option such as -left (which can still be abbreviated -l) must have its name and value as separate command line arguments (e.g. -l 50).

The new syntax was accepted and the old syntax deprecated and removed from documentation in Netpbm 9.25 (March 2002), and was no longer accepted in Netpbm 11.05 (December 2023).

The code was broken for most of that time so that an attempt to use the old syntax would fail anyway. The bug was discovered only in testing; no user ever reported encountering it. 💀 a stealth bug that literally nobody noticed, iconic behaviour

🔗 SEE ALSO 🔗

pbmmake(1), pnmpaste(1), pamcut(1), pnmcrop(1), pamcomp(1), pnmmargin(1), pbm(1)

🌟 AUTHOR 🌟

Copyright (C) 2002 by Martin van Beilen

Copyright (C) 1990 by Angus Duggan

Copyright (C) 1989 by Jef Poskanzer.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty. 🫶 legal besties said yes to sharing

📄 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/pnmpad.html

and that's the whole thing bestie 💖 this page came to you from the netpbm documentation, dated 26 December 2025, and it's the Pnmpad User Manual(1) — go forth and pad, you gorgeous thing 🎀✨🌈💅

📦 where this page comes from