\
.\" 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 "Pammixmulti User Manual" 1 "18 November 2018" "netpbm documentation"

  

.SH NAME
.PP
pammixmulti - blend together multiple PAM images


.UN synopsis
.SH SYNOPSIS
.PP
\fBpammixmulti\fP
  [\fB--blend\fP=average|random|mask]
  [\fB--maskfile\fP=\fIfilename\fP]
  [\fB--stdev\fP=\fInumber\fP]
  [\fB--randomseed\fP \fIinteger\fP]
  \fIfilename\fP ...
.PP
Minimum unique abbreviation of an option is acceptable. You can use a
single hyphen instead of double hyphens to denote options. You can use white
space in place of the equals sign to separate an option name from its
value.


.UN description
.SH DESCRIPTION
.PP
This file is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpammixmulti\fP mixes two or more images to produce a new image. The
program provides multiple ways to interpret "mix."


.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
\&), \fBpammixmulti\fP recognizes the following
command line options:


.TP
\fB--blend\fP=average|random|mask
.sp
This option specifies how the input images should be mixed to produce the
output image.  With \fB--blend\fP=\f(CWaverage\fP (the default), each
pixel in the output is produced by averaging the corresponding pixels from all
the input images.  With \fB--blend\fP=\f(CWrandom\fP, each pixel in the
output is produced by selecting the corresponding pixel from one of the input
images, chosen at random on a per-pixel basis.  With
\fB--blend\fP=\f(CWmask\fP, each pixel in the output is produced by a
weighted average of the corresponding pixels from all the input images based
on the grayscale level of an additional mask image.


.TP
\fB--maskfile\fP=\fIfilename\fP
.sp
In conjunction with \fB--blend\fP=\f(CWmask\fP, this option names a
grayscale mask file to control the blending of each pixel.  (If the file is
not grayscale, the first channel is treated as gray).  Where the mask file is
black, the first image is selected. Where the mask file is white, the last
image is selected.  Intermediate levels of gray select intermediate
images.


.TP
\fB--stdev\fP=\fInumber\fP
.sp
When used with \fB--blend\fP=\f(CWmask\fP, this option controls how
smoothly the various input images are mixed to produce each output pixel.  For
example, consider running \fBpammixmulti\fP with three input images and a
mask image that uses gray levels from 0 to 255. Given \fB--stdev\fP=0.0, gray
levels 0-84 produce exclusively image 1; gray levels 85-170 produce
exclusively image 2; and gray levels 171-255 produce exclusively image 3.  If
the argument to \fB--stdev\fP is positive, images are blended according to a
normal distribution.  Hence, gray levels around 85 produce an output pixel
that includes roughly equal amounts of the corresponding pixel from images 1
and 2 but less of the corresponding pixel from image 3.  As \fInumber\fP
tends towards the number of input images (going beyond that has diminishing
impact), the output tends to look more
like \fB--blend\fP=average. \fInumber\fP defaults to 0.25.


.TP
\fB--randomseed\fP \fIinteger\fP
This is the seed for the random number generator used with
\fB--blend=random\fP
.sp
Use this to ensure you get the same image on separate invocations.



.UN arguments
.SH ARGUMENTS
.PP
You supply the names of the files to mix as non-option arguments.


.UN examples
.SH EXAMPLES
.PP
Average a bunch of PPM images to produce a new PAM image:
.nf\f(CW
    pammixmulti input*.ppm >output.ppm
\fP
.fi
.PP
Mix these same images by taking each pixel from a randomly selected input
image:

.nf\f(CW
    pammixmulti --blend=random input*.ppm >output.ppm
\fP
.fi
.PP
Use a mask image to control the fading among input images on a
pixel-by-pixel basis:

.nf\f(CW
    pammixmulti --blend=mask --maskfile=mask.pgm >output.pam \e
       one.pam two.pam three.pam four.pam
\fP
.fi
.PP
Do the same but with more abrupt transitions:

.nf\f(CW
    pammixmulti --blend=mask --maskfile=mask.pgm --stdev=0.0 >output.pam \e
       one.pam two.pam three.pam four.pam
\fP
.fi
.PP
and now with more gradual transitions:

.nf\f(CW
    pammixmulti --blend=mask --maskfile=mask.pgm --stdev=1.0 >output.pam \e
       one.pam two.pam three.pam four.pam
\fP
.fi


.UN history
.SH HISTORY
.PP
\fBpammixmulti\fP was new in Netpbm 10.85 (December 2018).


.UN author
.SH AUTHOR
.PP
Copyright 2018 Scott Pakin, scott+pbm@pakin.org.

.UN seealso
.SH SEE ALSO
.PP
.BR "pamcomp" (1)\c
\&,
.BR "ppmmix" (1)\c
\&,
.BR "pamarith" (1)\c
\&,
.BR "pnm" (1)\c
\&,
.BR "pam" (1)\c
\&


.UN index
.SH Table Of Contents


.IP \(bu

.UR #synopsis
SYNOPSIS
.UE
\&
.IP \(bu

.UR #description
DESCRIPTION
.UE
\&
.IP \(bu

.UR #options
OPTIONS
.UE
\&
.IP \(bu

.UR #arguments
ARGUMENTS
.UE
\&
.IP \(bu

.UR #examples
EXAMPLES
.UE
\&
.IP \(bu

.UR #history
HISTORY
.UE
\&
.IP \(bu

.UR #author
AUTHOR
.UE
\&
.IP \(bu

.UR #seealso
SEE ALSO
.UE
\&
.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/pammixmulti.html
.PP