NAME

       pnmpad - add borders to a PNM image

SYNOPSIS

       pnmpad  [-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).

       pnmpad  reads  a  PNM  image as input and outputs a PNM image that is the input image plus
       black or white borders of the sizes specified.

       If you just need to convert an  image  to  a  certain  size  regardless  of  the  original
       dimensions, pamcut with the -pad option may be a better choice.

       pnmmargin  does essentially the same thing, but allows you to add borders of any color and
       requires all four borders to be the same size.

       You can use pamcomp to add borders of any content - solid color,
         pattern, or whatever.  For example, if you wanted to add 10 pixels of red
         borders to the top and bottom of a 100x100 image, you could create a
         100x120 red image (e.g. with ppmmake) and then use pamcomp
         to insert your 100x100 image into the center of it.

OPTIONS

       In addition to the options common to all programs based on libnetpbm (most notably -quiet,
       see
        Common Options ⟨index.html#commonoptions⟩ ), 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.

       -white

       -black Set pad color.  Default is -black.

       -left=pixels

       -right=pixels

       -width=width

       -halign=ratio

       -mwidth=pixels
              Specify amount of left and right padding in pixels.

              -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.

              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.  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.

              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.

       -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 ⟨#reportonly⟩  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.

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.

       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

       Before  February  2002, pnmpad had a different option syntax which was less expressive and
       not like conventional Netpbm programs.  That syntax is  still  understood  by  pnmpad  for
       backward compatibility, but not documented or supported for future use.

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.

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