\
.\" 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 "Pbmnoise User Manual" 1 "18 December 2021" "netpbm documentation"

.SH NAME
pbmnoise - create a PBM image made up of white noise

.UN synopsis
.SH SYNOPSIS

\fBpbmnoise\fP \fIwidth\fP \fIheight\fP

[\fB-ratio=\fP\fIM\fP\fB/\fP\fIN\fP]
[\fB-pack\fP]
[\fB-randomseed=\fP\fIinteger\fP]
[\fB-endian=\fP]{\fBbig\fP|\fBlittle\fP|\fBnative\fP|\fBswap\fP}] 
.PP
Minimum unique abbreviations of option are acceptable.  You may use double
hyphens instead of single hyphen to denote options.  You may use white space
in place of the equals sign to separate an option name from its value.

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpbmnoise\fP creates a PBM image with random pixels.  You specify the
probability each pixel will be black or white (essentially, the proportion of
black to white pixels in the image).
.PP
You specify the dimensions of the image with the \fIwidth\fP and
\fIheight\fP arguments.


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


.TP
\fB-ratio=\fP\fIM\fP\fB/\fP\fIN\fP
The proportion of black pixels in the generated image.
.sp
To be precise, this is the probability that any given pixel will be black.
By the law of large numbers, we can expect the proportion of black pixels in a
reasonably large image to be close to this fraction.
.sp
The option value is a fraction.  The denominator must be 1 or an integer
power of 2 up to 65536.  the numerator must be 0 or a positive integer not
exceeding denominator.
.sp
The default is 1/2, meaning the output image has essentially the same
number of black and white pixels.
.sp
If the ratio is 0 the output image is entirely white.  If 1, the output is
entirely black.

.TP
\fB-pack\fP
The program generates pixels in 32-bit units discarding any fractional pixels
at row ends by default.  When this option is specified, the unused pixels are
carried over to the next row, eliminating waste in exchange for some overhead
cost.
.sp
Using this option improves performance when the image width is small.

.TP
\fB-randomseed=\fP\fIinteger\fP
This is the seed for the random number generator that generates the pixels.
.sp
Use this to ensure you get the same image on separate invocations.
.sp
By default, \fBpbmnoise\fP uses a seed derived from the time of day and
process ID, which gives you fairly uncorrelated results in multiple
invocations.

.TP
\fB-endian=\fP\fImode\fP
\fBpbmnoise\fP internally generates random 32-bit integers and uses the
machine's binary encoding of those integers as strings of pixels.  Because the
integers are random, it doesn't normally matter what binaary encoding is used
for them, but if you need consistent results between machines using the same
random number generator, it matters.  For that reason (mainly for testing the
program), this option lets you control that encoding, between big-endian and
little-endian.
.sp
\fImode\fP is one of the following:


.TP
\fBbig\fP
Force big-endian output by rearranging bytes on little-endian machines.  No
effect on big-endian machines.

.TP
\fBlittle\fP
Likewise, force little-endian output.

.TP
\fBnative\fP
Do not rearrange anything.  This is the default.

.TP
\fBswap\fP
Always swap regardless of system endianness.




.UN examples
.SH EXAMPLES
.PP
This generates a random PBM image with roughly one-third of pixels colored
black:
.nf\f(CW
  pbmnoise -ratio=11/32 1200 1200 > random.pbm
\fP
.fi
.PP
The following is an alternate method for generating a random PBM image
which uses \fBpgmnoise\fP and \fBpgmtopbm\fP instead of \fBpbmnoise\fP.  It
is less efficient.
.nf\f(CW
  pgmnoise -maxval=100 1200 1200 | \e
    pgmtopbm -threshold -value=0.333 > random.pbm
\fP
.fi
.PP
This generates a random PPM image, maxval 1:
.nf\f(CW
  pbmnoise 600 400 > red.pbm
  pbmnoise 600 400 > green.pbm
  pbmnoise 600 400 > blue.pbm
  rgb3topbm red.pbm green.pbm blue.pbm > random.ppm
\fP
.fi


.UN seealso
.SH SEE ALSO
.BR "pbm" (1)\c
\&
.BR "pgmnoise" (1)\c
\&
.BR "pgmtopbm" (1)\c
\&

.UN history
.SH HISTORY
.PP
\fBpbmnoise\fP was new in Netpbm 10.97 (December 2021).
.PP
In Netpbm before that, you can use \fBpgmnoise\fP.

  
.UN author
.SH AUTHOR
.PP
Akira F Urushibata wrote this program and contributed it to the public domain
in December 2021.
.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/pbmnoise.html
.PP