PPMTOARBTXT(1)

💖 ppmtoarbtxt — the manual, but make it cute 💖

okay bestie, this is a page from the Ppmtoarbtxt User Manual, section 1 (General Commands Manual), and I'm gonna walk you through it like we're texting at 2am. no cap.

---

🌸 NAME 🌸

ppmtoarbtxt — turns a PPM image into literally any text-based format you want, based on a template. it's giving "pixel art but make it text." 🎀

---

✨ SYNOPSIS ✨

ppmtoarbtxt bodytmpl [-hd headtmpl] [-tl tailtmpl] [ppmfile]

---

🦋 DESCRIPTION 🦋

okay so first things first: this program is part of Netpbm(1). it's in the family. 🫶

ppmtoarbtxt generates simple text-based graphics formats based on format descriptions you hand it as input. and what's a "text-based graphics format"? it's when an image is represented by text — like PNM plain format, but not like PNM raw format. plain vibes, not raw vibes. ✨

ppmtoarbtxt reads a PPM image as input. for every single pixel in the image, it writes out the contents of the template file bodytmpl, with certain substitutions based on the value of that pixel, straight to Standard Output. one pixel, one template dump, repeat. 🔁

you may also supply a head template file, in which case ppmtoarbtxt generates text from that template file based on the image dimensions, and drops it into the output before anything else. it's the pre-game. 💅

likewise, you may supply a tail template file to cause text to be placed at the end of the output. the outro. the credits scene. 🌙

💜 Template Files 💜

the text that ppmtoarbtxt generates from a template file is the literal text of the template file, except with substitution specifiers swapped out for something else. the program recognizes a substitution specifier as text of the form #(...). that's the shape. that's the tell. 👀

ppmtoarbtxt treats white space in the template files the same as any other characters and places it in the output, with one exception: if the template file ends with a newline character, ppmtoarbtxt ignores it — it does not include it in the output. sneaky little newline? not invited. 🙈

many substitution specifiers use format strings (which are, yes, another form of template) to specify the substitution. you should make these format strings as minimal as possible — put literal text outside the substitution specifier instead of inside the format string. for example:

Wrong: #(flum %%%2.2f 0 1)

Right: %#(flum %2.2f 0 1)

the valid substitution specifiers are as follows. text that has the form of a substitution specifier but isn't actually valid (like #(random junk)) usually just specifies its literal value — but if it's close enough to something valid, ppmtoarbtxt assumes you made a mistake and fails. so close bestie, but no. 😭

useful in a body template, to do substitutions based on a particular pixel:

• #(ired format blackref whiteref) — generates an integer in the range blackref to whiteref, in a format specified by format, representing the red intensity of the pixel. a red intensity of 0 becomes blackref; a red intensity of maxval becomes whiteref, with everything in between linearly interpolated. 🌈

format is a printf-like format specifier like "%d". ppmtoarbtxt uses it as the entire format string to a fprintf POSIX library call whose only other argument is the red intensity as an integer data type. ppmtoarbtxt 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. 💀

#(ired) is equivalent to #(ired %d 0 255).

• #(igreen format blackref whiteref) — same as #(ired..., but for green. 💚
• #(iblue format blackref whiteref) — same as #(ired..., but for blue. 💙
• #(ilum format blackref whiteref) — same as #(ired..., but representing the luminance value (0.299*red + 0.587*green + 0.114*blue) of the pixel. ✨
• #(fred format blackref whiteref) — same as #(ired..., but generates a floating point number instead of an integer. 🫧

in this case, the second argument to the fprintf that uses format has a double precision floating point data type.

#(fred) is equivalent to #(fred %f 0.0 1.0).

• #(fgreen format blackref whiteref) — same as #(fred..., but for green.
• #(fblue format blackref whiteref) — same as #(fred..., but for blue.
• #(flum format blackref whiteref) — same as #(fred..., but representing the luminance value (0.299*red + 0.587*green + 0.114*blue) of the pixel.
• #(posx format) — generates the horizontal position of the pixel, in pixels from the left edge of the image.

the second argument to the fprintf that uses format has an unsigned integer data type.

format defaults to %u

• #(posy format) — same as #(width..., but for the vertical position. (yes that's what the original says, i'm just the messenger 🫡)

⚠️ if you use any of the above substitution specifiers in a head or tail template, the result is undefined. don't do it unless you're feeling chaotic.

useful in a head or tail template, to do substitutions based on whole-image attributes:

• #(width format) — generates the width in pixels of the image.

the second argument to the fprintf that uses format has an unsigned integer data type.

format defaults to %u

• #(height format) — same as #(width..., but for the height of the image.

---

✨ OPTIONS ✨

in addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options), ppmtoarbtxt recognizes the following command line options:

• -hd headtmpl — this option specifies a head template (headtmpl is the name of the head template file); it causes ppmtoarbtxt to place the contents of the file named headtmpl at the beginning of the output. entrance music. 🎬
• -tl tailtmpl — this option specifies a tail template; it is analogous to -hd. exit music. 🎶

---

🔥 EXAMPLES 🔥

gray inversion

here we generate a PGM plain-format image with gray inversion (like ppmtopgm | pnminvert). lowkey iconic. 🩶

contents of our head template file:

P2
#(width) #(height)
255

contents of our body skeleton file:

#(ilum %d 255 0)

povray file

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. spheres!! as pixels!! main character energy fr fr. 🔮

contents of our head skeleton:

#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
}

contents of our body skeleton:

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

---

👀 SEE ALSO 👀

pnmtoplainpnm(1) pamtable(1) ppm(1)

---

🌈 HISTORY 🌈

ppmtoarbtxt was added to Netpbm in Release 10.14 (March 2003). it existed under the name ppmtotxt since 1995. glow-up of the century honestly. ✨

---

👑 AUTHOR 👑

Copyright (C) 1995 by Peter Kirchgessner

---

🎀 DOCUMENT SOURCE 🎀

this manual page was generated by the Netpbm tool 'makeman' from HTML source. the master documentation is at

http://netpbm.sourceforge.net/doc/ppmtoarbtxt.html

---

okay that's the whole thing, you ate it, you're so good at this 🫶 netpbm documentation, 26 November 2014 — mwah, bye bestie, go make some text-based art 💅✨