diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/ppmtoarbtxt.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/ppmtoarbtxt.1 | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/ppmtoarbtxt.1 b/upstream/mageia-cauldron/man1/ppmtoarbtxt.1 new file mode 100644 index 00000000..46c1adb5 --- /dev/null +++ b/upstream/mageia-cauldron/man1/ppmtoarbtxt.1 @@ -0,0 +1,278 @@ +\ +.\" 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" 0 "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
\ No newline at end of file |