\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Pnmpad User Manual" 0 "20 March 2009" "netpbm documentation"

.SH NAME

pnmpad - add borders to a PNM image

.UN synopsis
.SH SYNOPSIS

\fBpnmpad \fP
[\fB-verbose\fP]
[\fB-white\fP|\fB-black\fP]
[\fB-width=\fP\fIpixels\fP]
[\fB-halign=\fP\fIratio\fP]
[\fB-left=\fP\fIpixels\fP]
[\fB-right=\fP\fIpixels\fP]
[\fB-height=\fP\fIpixels\fP]
[\fB-valign=\fP\fIratio\fP]
[\fB-top=\fP\fIpixels\fP]
[\fB-bottom=\fP\fIpixels\fP]
[\fIpnmfile\fP]


.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR Netpbm (1)
.
.PP
\fBpnmpad\fP 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.
.PP
If you just need to convert an image to a certain size regardless
of the original dimensions, \fBpamcut\fP with the \fB-pad\fP option
may be a better choice.
.PP
\fBpnmmargin\fP does essentially the same thing, but allows you to
add borders of any color and requires all four borders to be the same
size.


.UN options
.SH OPTIONS
.PP
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.


.TP
\fB-verbose\fP
Verbose output.

.TP
\fB-white\fP
.TP
\fB-black\fP
Set pad color.  Default is \fB-black\fP.


.TP
\fB-left=\fP\fIpixels\fP
.TP
\fB-right=\fP\fIpixels\fP
.TP
\fB-width=\fP\fIwidth\fP
.TP
\fB-halign=\fP\fIratio\fP
Specify amount of left and right padding in pixels.
.sp
\fB-left\fP and \fB-right\fP directly specify the amount of
padding added to the left and right sides, respectively, of the image.
.sp
Alternatively, you can specify \fB-width\fP and just one of
\fB-left\fP and \fB-right\fP and \fBpnmpad\fP calculates the required
padding on the other side based on the width of the input image.  If
the \fB-width\fP value is less than the width of the image plus the
specified padding, the \fB-width\fP values is ignored.
.sp
If you specify all three of \fB-width\fP, \fB-left\fP, and
\fB-right\fP, you must ensure that the \fB-left\fP and \fB-right\fP
padding are sufficient to make the image at least as wide as
\fB-width\fP specifies.  Otherwise, \fBpnmpad\fP fails.
.sp
When you specify \fB-width\fP without \fB-left\fP or
\fB-right\fP, and \fB-width\fP is larger than the input image,
\fBpnmpad\fP 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 \fB-halign\fP option.  If the input image is
already at least as wide as \fB-width\fP specifies, \fBpnmpad\fP
adds no padding.
.sp
Common values for \fB-halign\fP are:

.TP
\fB0.0\fP 
left aligned

.TP
\fB0.5\fP 
center aligned (default)

.TP
\fB1.0\fP 
right aligned

.sp
Before Netpbm 10.23 (July 2004), \fBpnmpad\fP did not allow the
\fB-left\fP or \fB-right\fP option together with \fB-width\fP.

.TP
\fB-top=\fP\fIpixels\fP
.TP
\fB-bottom=\fP\fIpixels\fP
.TP
\fB-height=\fP\fIheight\fP
.TP
\fB-valign=\fP\fIratio\fP
These options determine the vertical padding.  They are analogous
to the horizontal padding options above.




.UN history
.SH HISTORY
.PP
Before February 2002, \fBpnmpad\fP had a different option syntax
which was less expressive and not like conventional Netpbm programs.
That syntax is still understood by \fBpnmpad\fP for backward
compatibility, but not documented or supported for future use.


.UN seealso
.SH SEE ALSO
.BR pbmmake (1)
,
.BR pnmpaste (1)
,
.BR pamcut (1)
,
.BR pnmcrop (1)
,
.BR pamcomp (1)
,
.BR pnmmargin (1)
,
.BR pbm (5)



.UN author
.SH AUTHOR
.PP
Copyright (C) 2002 by Martin van Beilen
.PP
Copyright (C) 1990 by Angus Duggan
.PP
Copyright (C) 1989 by Jef Poskanzer.
.PP
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.