path: root/upstream/debian-unstable/man1/ppmtoarbtxt.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 "Ppmtoarbtxt User Manual" 1 "26 November 2014" "netpbm documentation"

.SH NAME
ppmtoarbtxt - generate image in arbitrary text format from PPM image

.UN synopsis
.SH SYNOPSIS

\fBppmtoarbtxt\fP
\fIbodytmpl\fP
[\fB-hd\fP \fIheadtmpl\fP]
[\fB-tl\fP \fItailtmpl\fP]
[\fIppmfile\fP]

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBppmtoarbtxt\fP generates simple text-based graphics formats based on
format descriptions given as input.  A text-based graphics format is one in
which an image is represented by text (like PNM plain format, but unlike
PNM raw format).

\fBppmtoarbtxt\fP reads a PPM image as input.  For each pixel in the
image, \fBppmtoarbtxt\fP writes the contents of the template file
\fIbodytmpl\fP, with certain substitutions based on the value of the
pixel, to Standard Output.
.PP
You may also supply a head template file, in which case \fBppmtoarbtxt\fP
generates text from the template file, based on the image dimensions, and
includes it in the output before anything else.
.PP
Likewise, you may supply a tail template file to cause text to be placed
at the end of the output.


.UN templatefiles
.SS Template Files
.PP
The text that \fBppmtoarbtxt\fP generates from a template file is the
literal text of the template file, except with substitution specifier replaced
with something else.  The program recognizes a substitution specifier as
text of the form \fB#(\fP...\fB)\fP.
.PP
\fBppmtoarbtxt\fP treats white space in the template files the same as any
other characters, placing it in the output, with one exception: If the
template file ends with a newline character, \fBppmtoarbtxt\fP ignores it --
it does not include it in the output.
.PP
Many substitution specifiers use format strings (another form of template)
to specify the substitution.  You should make these format strings as minimal
as possible, placing literal text outside the substitution specifier instead
of inside the format string.  For example,
.PP
Wrong: \f(CW#(flum %%%2.2f 0 1) \fP
.PP
Right: \f(CW%#(flum %2.2f 0 1) \fP
.PP
The valid substitution specifiers are as follows.  Text that has the
form of a substitution specifier but is not actually valid (e.g.
\fB#(random junk)\fP usually just specifies its literal value, but if it is
close enough to something valid, \fBppmtoarbtxt\fP assumes you made a mistake
and fails.
.PP
Useful in a body template, to do substitutions based on a particular pixel:


.TP
\fB#(ired\fP\fI format blackref whiteref\fP\fB)\fP
generates an integer in the range \fIblackref\fP to
\fIwhiteref\fP in a format specified by \fIformat\fP representing the red
intensity of the pixel.  A red intensity of 0 becomes \fIblackref\fP; a red
intensity of maxval becomes \fIwhiteref\fP, with the rest linearly
interpolated in between.
.sp
\fIformat\fP is a printf-like format specifier like "%d".
\fBppmtoarbtxt\fP uses as the entire format string to a \fBfprintf\fP POSIX
library call whose only other argument is the red itensity as an integer data
type.  \fBppmtoarbtxt\fP does not necessarily verify that your format string
makes sense; there are values you could specify that could even crash the
program.  To avoid unexpected behavior, keep format strings simple and
hardcoded, and never include a per cent sign or newline.
.sp
\fB#(ired)\fP is equivalent to \fB#(ired %d 0 255)\fP.

.TP
\fB#(igreen\fP\fI format blackref whiteref\fP\fB)\fP
Same as \fB#(ired...\fP, but for green.

.TP
\fB#(iblue\fP\fI format blackref whiteref\fP\fB)\fP
Same as \fB#(ired...\fP, but for blue.

.TP
\fB#(ilum\fP\fI format blackref whiteref\fP\fB)\fP
Same as \fB#(ired...\fP, but representing the luminance value
(0.299*red + 0.587*green + 0.114*blue) of the pixel.

.TP
\fB#(fred\fP\fI format blackref whiteref\fP\fB)\fP
Same as \fB#(ired...\fP, but generates a floating point number instead
of an integer.
.sp
In this case, the second argument to the \fBfprintf\fP that uses 
\fIformat\fP has a double precision floating point data type.
.sp
\fB#(fred)\fP is equivalent to \fB#(fred %f 0.0 1.0)\fP.

.TP
\fB#(fgreen \fP\fIformat blackref whiteref\fP\fB)\fP
Same as \fB#(fred...\fP, but for green.

.TP
\fB#(fblue \fP\fIformat blackref whiteref\fP\fB)\fP
Same as \fB#(fred...\fP, but for blue.

.TP
\fB#(flum \fP\fIformat blackref whiteref\fP\fB)\fP
Same as \fB#(fred...\fP, but representing the luminance value
(0.299*red + 0.587*green + 0.114*blue) of the pixel.

.TP
\fB#(posx \fP\fIformat\fP\fB)\fP
Generates the horizontal position of the pixel, in pixels from the left
edge of the image.
.sp
The second argument to the \fBfprintf\fP that uses \fIformat\fP has an
unsigned integer data type.
.sp
\fIformat\fP defaults to \fB%u\fP

.TP
\fB#(posy \fP\fIformat\fP\fB)\fP
Same as \fB#(width...\fP, but for the vertical position.


.PP
If you use any of the above substitution specifiers in a head or tail
template, the result is undefined.
.PP
Useful in a head or tail template, to do substitutions based on whole-image
attributes:


.TP
\fB#(width \fP\fIformat\fP\fB)\fP
Generates the width in pixels of the image.
.sp
The second argument to the \fBfprintf\fP that uses \fIformat\fP
has an unsigned integer data type.
.sp
\fIformat\fP defaults to \fB%u\fP

.TP
\fB#(height \fP\fIformat\fP\fB)\fP
Same as \fB#(width...\fP, but for the height of the image.




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


.TP
\fB-hd\fP \fIheadtmpl\fP
This option specifies a head template (\fIheadtmpl\fP is the name of the
head template file); it causes \fBppmtoarbtxt\fP to place the contents of the
file named \fIheadtmpl\fP at the beginning of the output

.TP
\fB-tl\fP \fItailtmpl\fP
This option specifies a tail template; it is analogous to \fB-hd\fP.



.UN examples
.SH EXAMPLES

.SS gray inversion
.PP
Here we generate a PGM plain-format image with gray inversion
(like \fBppmtopgm | pnminvert\fP).
.PP
Contents of our head template file:

.nf
P2
#(width) #(height)
255

.fi
.PP
Contents of our body skeleton file:

.nf
#(ilum %d 255 0)

.fi

.SS povray file
.PP
Here we generate a povray file where each pixel is represented by a
sphere at location (x,y,z) = (posx,height-posy,luminance).  The color
of the sphere is the color of the pixel.
.PP
Contents of our head skeleton:

.nf
#include "colors.inc"
#include "textures.inc"
camera {
   location  <#(width) * 0.6, #(height) * 0.7, 80>
   look_at   <#(width) * 0.5, #(height) * 0.5, 0>
}

light_source { <#(width) * 0.5, #(height) * 0.5, 25> color White
}

.fi
.PP
Contents of our body skeleton:

.nf
sphere { <#(posx),#(height)-#(posy),#(ilum %d 0 10)>, 0.5
  texture {
    pigment {
      color rgb <#(fred),#(fgreen),#(fblue)>
    }
    finish {
      phong 1
    }
  }
}

.fi

.UN seealso
.SH SEE ALSO
.BR "pnmtoplainpnm" (1)\c
\&
.BR "pamtable" (1)\c
\&
.BR "ppm" (1)\c
\&

.UN history
.SH HISTORY
.PP
\fBppmtoarbtxt\fP was added to Netpbm in Release 10.14 (March 2003).
It existed under the name \fBppmtotxt\fP since 1995.

.UN author
.SH AUTHOR

Copyright (C) 1995 by Peter Kirchgessner
.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/ppmtoarbtxt.html
.PP