Debian Codegraph @

upstream/debian-unstable/man1/pambackground.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pambackground User Manual" 1 "24 November 2014" "netpbm documentation"
7
8 .SH NAME
9 pambackground - create a mask of the background area of an image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpambackground\fP
15
16 [\fInetpbmfile\fP]
17
18 [\fB-verbose\fP]
19 .PP
20 Minimum unique abbreviations of options are acceptable. You may
21 use double hyphens instead of single hyphen to denote options. You
22 may use white space in place of the equals sign to separate an option
23 name from its value.
24
25
26 .UN description
27 .SH DESCRIPTION
28 .PP
29 This program is part of
30 .BR "Netpbm" (1)\c
31 \&.
32 .PP
33 \fBpambackground\fP reads a PNM or PAM image as input. It generates as
34 output a PAM image that identifies the background area of the image (a mask).
35 .PP
36 To identify the background, \fBpambackground\fP assumes the image is a
37 foreground image, smaller than the total image size, placed over a
38 single-color background. It assumes that foreground image is solid -- it does
39 not have holes through which the background can be seen. So in
40 specific, \fBpambackground\fP first identifies the background color, then
41 finds all contiguous pixels of that color in regions touching any edge of the
42 image. Think of it as starting at each of the four edges and moving inward
43 and spreading out as far as possible until it hits pixels of another color
44 (the foreground image).
45 .PP
46 \fBpambackground\fP identifies the background color as follows:
47 If any 3 corners of the image are the same color, that's the background
48 color. If not, but 2 corners are the same color, the background color
49 is the color of a pair of identically colored corners in this priority
50 order: top, right, left, bottom. If no two corners have the same color,
51 the background color is the color of the upper left corner.
52 .PP
53 In a typical photograph, the area that you would consider the
54 background is many shades of a color, so to \fBpambackground\fP it is
55 multiple colors and \fBpambackground\fP will not meaningfully
56 identify the background of your image. To use \fBpambackground\fP in
57 this case, you might use \fBppmchange\fP to change all similar colors
58 to a single one first. For example, if the photograph is a building
59 against a blue sky, where nothing remotely sky-blue appears in the
60 building, you could use \fBppmchange\fP to change all pixels within
61 20% of "SkyBlue" to SkyBlue, then run \fBpambackground\fP
62 on it.
63 .PP
64 You might even extract the argument for \fBppmchange\fP from the image in
65 question, using \fBpamgetcolor\fP. In the foregoing example, we knew the
66 background was approximately SkyBlue, but if we didn't we could just get the
67 color of the top left pixel, in a form suitable for the color arguments
68 of \fBppmchange\fP like this:
69
70 .nf
71 \f(CW
72 $ color=$(pamgetcolor 0,0 -infile=/tmp/bodyskl|cut --fields=2 -delim=' ')
73 \fP
74
75 .fi
76 .PP
77 A more convenient means of dealing with a multi-shade background is
78 to use \fBpnmquant\fP to produce a version of the image with a very small
79 number of colors. The background would likely then be all one color.
80 .PP
81 If the \fBpnmquant\fP and \fBppmchange\fP methods above do not adequately
82 distinguish foreground colors from background colors, you can try a more
83 elaborate method using \fBpnmremap\fP. If you can manually create a palette
84 with one color to which all the background pixels are similar, and other
85 colors to which the foreground pixels are similar, you can use it as input to
86 \fBpnmremap\fP to create a smarter version of what you get with the
87 \fBpnmquant\fP or \fBppmchange\fP methods, so that \fBpambackground\fP is
88 more likely to separate background from foreground as your eye does.
89 .PP
90 The PAM that \fBpambackground\fP creates has a single plane, with a maxval
91 of 1. The sample value 1 means background; 0 means foreground. There is no
92 tuple type. Some older programs (but none that are part of Netpbm) don't know
93 what a PAM is and expect a mask to be in the form of a PGM or PBM image. To
94 convert \fBpambackground\fP's output to PBM, use \fBpamtopnm -assume\fP. To
95 convert to PGM, use \fBpgmtopgm\fP.
96 .PP
97 \fInetpbmfile\fP is the file specification of the input file, or
98 \fB-\fP to indicate Standard Input. The default is Standard Input.
99 .PP
100 A common use for a background mask is with \fBpamcomp\fP. You
101 could replace the entire background (or foreground) of your
102 image with something else.
103 .PP
104 Another common use is to make an image with the background transparent (in
105 some image format that has a concept of transparency) so that image can be
106 overlaid onto another image later. Netpbm's converters to image formats that
107 have transparency (e.g. PNG) let you use the mask that \fBpambackground\fP
108 generates to identify the transparent areas for the output. You can create
109 a PAM image with transparency with \fBpamstack\fP.
110 .PP
111 To simply make a mask of all the areas of a specified color, use
112 \fBppmcolormask\fP. If you have a unique background color (one that
113 doesn't occur in the foreground) and know what it is, this can create
114 a background mask in cases that \fBpambackground\fP cannot: where there
115 are see-through holes in the foreground image.
116
117
118 .UN options
119 .SH OPTIONS
120 .PP
121 In addition to the options common to all programs based on libnetpbm
122 (most notably \fB-quiet\fP, see
123 .UR index.html#commonoptions
124 Common Options
125 .UE
126 \&), \fBpambackground\fP recognizes the following
127 command line option:
128
129
130
131 .TP
132 \fB-verbose\fP
133 Tell interesting facts about the process.
134
135
136
137 .UN examples
138 .SH EXAMPLES
139
140 .nf
141 \f(CW
142 $ pambackground test.ppm | pnminvert >/tmp/bgmask.pgm
143 $ pamcomp -alpha=bgmask.pgm test.ppm wallpaper.ppm >output.ppm
144 \fP
145
146 .fi
147 .nf
148 \f(CW
149 $ pnmquant 5 test.pgm | pambackground test.ppm >/tmp/bgmask.pam
150 \fP
151
152 .fi
153
154
155 .UN seealso
156 .SH SEE ALSO
157 .BR "ppmcolormask" (1)\c
158 \&,
159 .BR "pamcomp" (1)\c
160 \&,
161 .BR "ppmchange" (1)\c
162 \&,
163 .BR "pnmquant" (1)\c
164 \&,
165 .BR "pnmremap" (1)\c
166 \&,
167 .BR "pamtopnm" (1)\c
168 \&,
169 .BR "pgmtopgm" (1)\c
170 \&,
171 .BR "pamstack" (1)\c
172 \&,
173 .BR "pamgetcolor" (1)\c
174 \&,
175 .BR "pbmmaskd" (1)\c
176 \&,
177 .BR "pnm" (1)\c
178 \&,
179 .BR "pam" (1)\c
180 \&,
181
182 .UN history
183 .SH HISTORY
184 .PP
185 \fBpambackground\fP was new in Netpbm 10.37 (December 2006).
186 .SH DOCUMENT SOURCE
187 This manual page was generated by the Netpbm tool 'makeman' from HTML
188 source. The master documentation is at
189 .IP
190 .B http://netpbm.sourceforge.net/doc/pambackground.html
191 .PP