path: root/upstream/mageia-cauldron/man1/pnmpad.1

\
.\" 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 "25 December 2021" "netpbm documentation"

.SH NAME

pnmpad - add borders to a PNM image

.UN synopsis
.SH SYNOPSIS

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


.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.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.
.PP
You can use \fBpamcomp\fP 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 \fBppmmake\fP) and then use \fBpamcomp\fP
  to insert your 100x100 image into the center of it.
  

.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see 
.UR index.html#commonoptions
 Common Options
.UE
\&), \fBpnmpad\fP recognizes the following
command line 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-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
.TP
\fB-mwidth=\fP\fIpixels\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 to make the output \fIwidth\fP pixels wide.  If
the \fB-width\fP value is less than the width of the input image plus the
specified padding, \fBpnmpad\fP ignores \fB-width\fP.
.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
\fB-mwidth=\fP\fIpixels\fP says to pad to a multiple of
\fIpixels\fP pixels.  E.g. if \fIpixels\fP is 10, the output image width
will be a multiple of 10 pixels.  \fBpnmpad\fP 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 \fB-left=10 -right=10 -mwidth=50\fP 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, \fBpnmpad\fP adds padding in the ratio specified by \fB-halign\fP
and if \fB-halign\fP is not specified, equally on both sides.
.sp
Before Netpbm 10.97 (December 2021), \fBpnmpad\fP does not allow
\fB-halign\fP with \fB-mwidth\fP and adds padding only on the right
when \fB-mwidth\fP is specified and the other options indicate no padding.
.sp
Before Netpbm 10.72 (September 2015), there is no \fB-mwidth\fP.
.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
.TP
\fB-mheight=\fP\fIpixels\fP
These options determine the vertical padding.  They are analogous to the
horizontal padding options above.

.TP
\fB-reportonly\fP
  This causes \fBpnmpad\fP to write to Standard Output a description of the
  padding it would have done instead of producing an output image.  See
  
.UR #reportonly
below
.UE
\& for a description of this output and ways
  to use it.
.sp
This option was new in Netpbm 10.89 (December 2019).

.TP
\fB-verbose\fP
This causes verbose messages.



.UN reportonly
.SH REPORT ONLY
.PP
When you specify \fB-reportonly\fP, \fBpnmpad\fP does not produce an
  output image.  Instead, it writes to Standard Output a description of the
  padding it would have done without \fB-reportonly\fP.
.PP
That description is one line of text, containing 6 decimal numbers of
  pixels, separated by spaces:


.IP \(bu
left padding
.IP \(bu
right padding
.IP \(bu
top padding
.IP \(bu
bottom padding
.IP \(bu
output width
.IP \(bu
output height

.PP
Example:
.nf
    
      4 3 0 2 100 100
    

.fi
.PP
One use for this is to make padding which is fancier than the black and
  white that \fBpnmpad\fP can do.
.PP
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 \fBpbmmake\fP and then pasting the
  subject image into the middle of it.
.PP
The example uses shell arrays, such as exist in Bash, but not Dash.
  
.nf
    \f(CW
    pad=($(pnmpad -reportonly -left=10 -right=10 -top=10 -bottom=10 input.ppm))
    pbmmake -gray ${pad[4]} ${pad[5]} | \e
      pnmpaste input.ppm ${pad[0]} ${pad[2]} -
    \fP

.fi
    

.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)\c
\&,
.BR "pnmpaste" (1)\c
\&,
.BR "pamcut" (1)\c
\&,
.BR "pnmcrop" (1)\c
\&,
.BR "pamcomp" (1)\c
\&,
.BR "pnmmargin" (1)\c
\&,
.BR "pbm" (1)\c
\&


.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.
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/pnmpad.html
.PP