ppmlabel

Add text to a PPM image at the specified location

$ ppmlabel -x [pos_x] -y [pos_y] [[-t|-text]] [text] [path/to/input_file.ppm] > [path/to/output_file.ppm]

$ ppmlabel -x [pos_x1] -y [pos_y1] [[-t|-text]] [text1] -x [pos_x2] -y [pos_y2] [[-t|-text]] [text2] [path/to/input_file.ppm] > [path/to/output_file.ppm]

$ ppmlabel -x [pos_x] -y [pos_y] [[-c|-color]] [line_color] [[-b|-background]] [background_color] [[-a|-angle]] [tilt] [[-s|-size]] [size] [[-t|-text]] [text] [path/to/input_file.ppm] > [path/to/output_file.ppm]

ppmlabel [options]

-font <fontname>
    Specifies the font to use for the label. This can be a Netpbm font name (e.g., type1) or a path to a font file. Default is type1.

-text <text>
    The actual text string to be added as a label. If the text begins with @, the rest is interpreted as a filename from which to read the text.

-size <pixels>
    Sets the font size in pixels. This determines the height of the characters.

-color <colorname>
    Defines the color of the text. Can be a color name (e.g., red, blue) or a hexadecimal RGB value (e.g., #RRGGBB). Default is black.

-position <gravity>
    Controls the placement of the text label on the image. Common values include northwest, north, northeast, west, center, east, southwest, south, southeast, top, bottom. Default is southwest.

-align <alignment>
    Specifies the horizontal alignment of the text within its bounding box: left, center, or right. Default is left.

-background <colorname>
    Sets a solid background color behind the text. If not specified, the background is transparent, blending the text with the image.

-margin <pixels>
    Adds a margin in pixels between the text and the edge of the image, or between the text and a background box. Default is 10 pixels.

-width <pixels>
    Sets a maximum width for the text. If the text exceeds this width, it will wrap or be truncated depending on other options.

-height <pixels>
    Sets a maximum height for the text. If the text exceeds this height, it will be truncated.

-wrap
    Enables word wrapping for the text when combined with -width. Text will wrap at word boundaries rather than being truncated or overflowing.

-encoding <encoding>
    Specifies the character encoding of the input text (e.g., iso-8859-1, utf8). This is crucial for displaying non-ASCII characters correctly.

-dpi <dpi>
    Sets the dots per inch for font rendering, affecting the visual size and quality of the font. Default is 72 DPI.

-shadow <offset>
    Adds a shadow effect to the text. The offset specifies how many pixels the shadow is shifted from the main text.

-box
    Draws a solid box around the text label. The color of the box is determined by the -background option.

-vbar
    Draws a vertical bar next to the text. Typically used with -align left or -align right for visual emphasis.

-noblend
    Prevents color blending when drawing the text, instead setting pixel values directly. This can result in sharper but less smooth text on complex backgrounds.

The ppmlabel command is a specialized utility within the Netpbm image manipulation suite. It is designed to overlay text labels directly onto Portable Pixmap (PPM) format images. It reads an image from standard input, applies the specified text label with various customizable attributes (font, size, color, position, alignment, background, margins, etc.), and then writes the modified image to standard output. This allows for easy integration into shell scripts and pipelines for automated image processing workflows, such as adding timestamps, captions, or watermarks to image streams.

ppmlabel is part of the Netpbm suite, meaning it expects and outputs images in Netpbm (PPM) format. For TrueType/OpenType fonts, the gttf utility and the FreeType library must be installed and correctly configured within the Netpbm setup. Font availability and rendering quality can depend heavily on system configuration and the specific Netpbm build.
Text wrapping (-wrap) is only effective when combined with -width.

ppmlabel is designed to work seamlessly with Unix pipes. It reads the input PPM image from standard input (stdin) and writes the labeled PPM image to standard output (stdout). This allows it to be easily integrated into complex image processing pipelines, for example:
cat input.ppm | ppmlabel -text 'My Label' -size 20 -color blue > output.ppm
or
jpegtopnm image.jpg | ppmlabel -text 'Watermark' -position southwest | pnmtopng > image_labeled.png

The command primarily uses Type 1 fonts, which are typically found in Netpbm's font directories. For TrueType/OpenType font support, Netpbm relies on the gttf utility and the FreeType library. Users might need to configure Netpbm's NETPBM_FONTDIR environment variable to ensure fonts are located correctly.

ppmlabel is a component of the venerable Netpbm project, which traces its roots back to Jef Poskanzer's PBMPlus toolkit developed in the late 1980s. Netpbm itself evolved from PBMPlus to become a comprehensive suite of utilities for manipulating graphic images in various formats. ppmlabel was introduced to provide a specialized, efficient way to overlay text on PPM images, fitting into the Unix philosophy of small, single-purpose tools that can be chained together via pipes.

ppm(5), pnm(5), ppmtext(1), gttf(1), pnmtopng(1), pnmtojpeg(1), convert(1)