PPMDRAW(1)

📦
version 11.13.03 · 6 versions
, in ubuntu stonking

💅 PPMDRAW(1) — the Ppmdraw User Manual, but make it make sense

okay bestie, pull up a chair, we're learning ppmdraw from General Commands Manual and honestly? she's an icon. let's go 🎀

✨ NAME ✨

ppmdraw — draw lines, text, etc on a PPM image 🖍️

✨ SYNOPSIS ✨

ppmdraw

{ -script=script | -scriptfile=filename } [-verbose]

[ppmfile]

okay so a few lil shortcuts you can take, no big deal:

  • every option can be abbreviated down to its shortest unique prefix (so yes, be lazy, it's fine 💅)
  • you can use two hyphens instead of one to designate an option
  • you can put either white space or an equals sign between an option name and its value

✨ DESCRIPTION ✨

so this program is part of Netpbm(1) 🫶

ppmdraw draws lines, shapes, text, etc. on a PPM image. it is essentially an easy-to-program front end to libnetpbm's ppmd subroutines, and the whole point is that it lets you write a human-friendly script to describe the drawing instead of, like, writing a whole C program. main character energy, tbh.

you supply drawing instructions with a script, and you hand that script over either in a file named by a -scriptfile option or as the value of a -script option. here's an example script, look at her:

setpos 50 50;
text_here 10 30 "hello";
setcolor black;
text_here 10 0 "there";
line_here 5 20;

so what's happening here, ok? this example starts at Column 50, Row 50 of the input image and writes the word "hello" there in 10 pixel high white letters at a 30 degree angle up from horizontal. then, from where that leaves off, the script writes "there" in 10 pixel high black letters horizontally. finally, it draws a black line to a point 5 pixels over and 20 pixels down from the end of "there." and yes that's the whole vibe 🌸

if you don't specify ppmfile, ppmdraw reads its input PPM image from Standard Input.

the output image goes to Standard Output.

ppmdraw works on multi-image streams — it executes the same script on each input image and produces an output stream with one image for each input image. but 💀 before Netpbm 10.32 (February 2006), ppmdraw ignored every image after the first. era-defining bug, honestly.

if you just want to add a single line of text to an image, ppmlabel may be more what you want 👑

✨ OPTIONS ✨

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

  • -script=script — this option gives the script. see Script. ⚠️ you may not specify both -script and -scriptfile.
  • -scriptfile=filename — this option names a file that contains the script. - means Standard Input. ⚠️ you may not specify both -script and -scriptfile. also ⚠️ you may not specify - (Standard Input) for both -scriptfile and the input image file.

✨ SCRIPT ✨

the heart of ppmdraw function is its script 💖 the script is a character stream. the stream consists of commands, and commands are separated by semicolons. white space is regarded just like in C: any contiguous stretch of unquoted white space is equivalent to a single space character. note that this means newlines have no particular significance. ngl that trips people up every time.

a command is composed of tokens, separated from each other by white space. to write a token that contains white space, enclose it in double quotes — everything between two matched quotation marks is one token.

the first token of a command is the verb, which determines the basic function of the command. the rest of the tokens of the command are arguments, the meaning of which depends upon the verb. the following list gives all the valid verbs, and for each its meaning and its arguments 📝

many commands have arguments that specify a position on the canvas, which you specify by row and column. Row 0 is the top row. Column 0 is the leftmost column. you may specify negative numbers (but such a position would necessarily be off the canvas). 🫠

your drawing instructions may involve positions not on the canvas. but any pixels you draw there just get discarded. bye 👋

  • setpos — set the "current position" in the image. this affects where subsequent commands draw things. the 2 arguments are the column and row number. at the start of the script, the current position is (0,0).
  • setlinetype — the 1 argument is "normal" or "nodiag.". this effects a ppmd_setlinetype() call. further details are not yet documented. (mysterious. love that for her 💀)
  • setlineclip — this effects a ppmd_setlineclip() call. not yet documented.
  • setcolor — this sets the "current color", which determines the color in which subsequent drawing commands draw. before the first setcolor, the current color is white. there is one argument. it specifies the color as described for the argument of the pnm_parsecolor() library routine.
  • setfont — this sets the "current font", which determines the font in which subsequent text drawing commands draw. before the first setfont, the current font is a built in font called "standard." the argument of this command is a file name — it is the name of a Netpbm PPMD font file. a Netpbm PPMD font file typically has a name that ends in .ppmdfont and its first 8 bytes are the ASCII encoding of "ppmdfont". there is only one of these fonts as far as we know. it is distributed with Netpbm as the file standard.ppmdfont, but you don't need to use that file because the same font is built into the Netpbm library and is the default. if you want to make a new font, you can find the format of a ppmdfont file in the Netpbm interface header file ppmdfont.h, but you'll have to make your own tools to build it. the program ppmdmkfont generates standard.ppmdfont, so you can use that as an example 👑
  • line — this draws a one pixel wide line in the current color. the 4 arguments are: starting column, starting row, ending column, ending row. this command does not affect the current position.
  • line_here — this is like line, except it works in a more relative way. the line starts at the current point. the two arguments are the rightward and downward displacement from there to the terminal point. the command moves the current position to the terminal point after drawing.
  • spline3 — this draws a spline in the current color between 2 points, using a third as a control point. it approximates a cubic spline segment. the shape of the curve is such that it passes through the specified endpoints, and lines tangent to the curve at those endpoints intersect at the control point. controlling the tangents allows you to connect this curve to other curves generated the same way without having corners at the connection points. the 6 arguments are the starting point column, starting point row, control point column, control point row, ending point column, and ending point row. this command does not affect the current position.
  • circle — this command draws a circle in the current color. the three arguments are the column number and row number of the center of the circle and the radius of the circle in pixels.
  • filledcircle — this is the same as circle except that the circle is filled with the current color. this command class was new Netpbm 10.59 (June 2012) ✨
  • filledrectangle — this command draws a rectangle filled with the current color. the 4 arguments are the column and row numbers of the upper left corner of the rectangle, the width of the rectangle, and the height of the rectangle.
  • text — this command draws text in the current color in the built-in font. the 5 arguments are:
    1. column number of starting point of baseline
    2. row number of starting point of baseline
    3. height of characters, in pixels
    4. angle of baseline in degrees elevated from the horizontal
    5. text

note that if your text contains white space, you'll have to use double quotes to cause it to be a single token.

  • text_here — this is like text, except that the baseline starts at the current position and the command updates the current position to the other end of the baseline after it draws.
⚠️ bear in mind that a script starts with the current position in the top line, so if you leave it there, only the bottom line of your text will be within the image! 😭

✨ HISTORY ✨

ppmdraw was new in Netpbm 10.29 (August 2005). a lil baby 🍼

✨ SEE ALSO ✨

ppmlabel(1), ppm(1) libnetpbm_draw(1)

✨ 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/ppmdraw.html

and that's the whole thing bestie 🫶 this page was cooked up by netpbm documentation on 17 mAY 2025 (yes the caps are like that, we don't ask questions), and it is, as ever, the Ppmdraw User Manual(1). slay, go draw something 🎀✨

📦 where this page comes from