ppmspread

Displace the pixels in a PPM image by a randomized amount that is at most a

Specify a seed to a the pseudo-random number generator

ppmspread [options] [spreader_file [base_file]]

Note: The interpretation of file arguments is flexible. If spreader_file is not specified, it is read from standard input. If base_file is not specified, it is read from standard input. If only one file argument is provided, it is treated as the base_file, and the spreader_file is read from standard input.

-width=W
    Specifies the target width for the spreader image in pixels. The spreader is scaled to fit this width if provided.

-height=H
    Specifies the target height for the spreader image in pixels. The spreader is scaled to fit this height if provided.

-xscale=N
    Scales the spreader image horizontally by a floating-point factor of N. For example, 0.5 makes it half size, 2.0 makes it double size. This is applied before -width/-height.

-yscale=N
    Scales the spreader image vertically by a floating-point factor of N. Applied before -width/-height.

-xoffset=N
    Applies a horizontal offset of N pixels to the placement of each spreader instance. Useful for fine-tuning alignment of tiled patterns.

-yoffset=N
    Applies a vertical offset of N pixels to the placement of each spreader instance.

-random
    Places the spreader images at random locations within the base image instead of a regular grid. The number of random placements depends on the size of the spreader relative to the base image. Cannot be used with -brick.

-brick
    Arranges the spreader images in a brick-like pattern, where alternating rows are offset horizontally by half the spreader's width, mimicking brickwork. Cannot be used with -random.

ppmspread is a utility from the Netpbm image manipulation toolkit designed to tile a smaller "spreader" image repeatedly over a larger "base" image. It allows users to create patterned backgrounds, textures, or complex visual effects by repeating a motif across a canvas. The command offers various options to control the size and scaling of the spreader image, its horizontal and vertical offsets, and the tiling pattern, including standard grid, brick-like arrangements, or random placement. The output is a PPM image, which can then be converted to other formats using other Netpbm tools.

ppmspread is part of the Netpbm suite, meaning it primarily operates on PPM (Portable Pixmap) format. While Netpbm tools generally handle automatic conversion from other image formats (like JPEG, PNG, GIF) via anytopnm, direct input/output is in PPM. The flexible handling of input file arguments (standard input vs. explicit files) requires careful attention to avoid unintended behavior.

The command primarily works with PPM (Portable Pixmap) images. Input images in other common graphic formats (like JPEG, PNG, GIF, TIFF) are automatically converted to PPM internally via the anytopnm utility provided by Netpbm. The output image produced by ppmspread is always in PPM format, which can then be converted to other desired formats using specific Netpbm tools like pnmtojpeg, pnmtopng, pnmtopgm, etc.

The command's flexibility in reading input from files or standard input can sometimes be confusing. Here's a breakdown of common scenarios:

• Two file arguments: The first file is the spreader, the second is the base. Example: ppmspread spreader.ppm base.ppm > output.ppm
• One file argument: The file is treated as the base image, and the spreader image is read from standard input. Example: cat spreader.ppm | ppmspread base.ppm > output.ppm
• No file arguments: The spreader image is read from standard input first, and then the base image is also read from standard input. This setup is less common for `ppmspread` and usually implies piping concatenated streams, which can be tricky.

It's generally clearer to specify at least one file argument or explicitly pipe a single input.
Example of piping the base image and providing spreader as a file:
cat base.ppm | ppmspread spreader.ppm > output.ppm

ppmspread is a component of the Netpbm project, a comprehensive suite of graphics utilities that originated from the PBMplus package developed by Jef Poskanzer in 1988. Netpbm maintains a long history of providing robust and flexible tools for manipulating portable pixmap, graymap, and bitmap files, adhering to the Unix philosophy of small, specialized programs that can be chained together via pipes for complex operations.

pnmstitch(1), ppmtile(1), pnmcut(1), netpbm(1)