pamsplit

Split a multi-image Netpbm file into multiple single-image Netpbm files

$ pamsplit [path/to/image.pam]

$ pamsplit [path/to/image.pam] [file_%d.pam]

pamsplit [-pad] [-width width] [-height height] [-left left] [-top top] [-cols cols] [-rows rows] [-exact] [-output output_name_template] [-filenumber start_number] [-digits digits] [-nullpad] [-rowmajor] [-frame frame_number] [-frames number_of_frames] [-startframe start_frame_number] [-verbose] [inputfile]

-pad
    Pads split images that are smaller than the specified dimensions with black pixels.

-width width
    Specifies the desired width in pixels for each split output image.

-height height
    Specifies the desired height in pixels for each split output image.

-left left
    Sets the X-coordinate of the left edge of the first split image's bounding box.

-top top
    Sets the Y-coordinate of the top edge of the first split image's bounding box.

-cols cols
    Divides the input image into the specified number of columns. The width of each split image is then determined implicitly.

-rows rows
    Divides the input image into the specified number of rows. The height of each split image is then determined implicitly.

-exact
    Requires that the split images exactly match the specified dimensions. If not, an error occurs.

-output output_name_template
    Defines the template for the output filenames. Use %n for sequential numbers and %N for frame numbers.

-filenumber start_number
    Sets the starting number for the %n placeholder in the output filenames (default is 0).

-digits digits
    Specifies the minimum number of digits for the sequential number in output filenames, padding with leading zeros if necessary.

-nullpad
    Pads the sequential numbers with null characters (ASCII 0) instead of zeros. Useful for specific naming schemes.

-rowmajor
    Changes the splitting order to proceed row by row first, then column by column (default is column by column first).

-frame frame_number
    Extracts a single specific frame from a multi-image stream (0-indexed).

-frames number_of_frames
    Specifies the total number of frames to extract, starting from the frame defined by -startframe.

-startframe start_frame_number
    Specifies the starting frame number for extraction when using -frames.

-verbose
    Prints informational messages during processing, detailing the actions pamsplit performs.

inputfile
    The path to the input Netpbm image file. If omitted, pamsplit reads from standard input.

pamsplit is a Netpbm command-line utility designed to divide a single Netpbm image or a stream of images into multiple smaller, separate image files. It reads input from standard input by default or from a specified file.

Users can define how the image should be split: either by specifying the exact width and height for each output sub-image, or by defining a grid using -cols and -rows. When using grid dimensions, the output image dimensions are implicitly calculated from the input image size. It also supports padding smaller sub-images with black using the -pad option.

Beyond spatial splitting, pamsplit is capable of extracting individual frames or a sequence of frames from multi-image streams (e.g., animated PAMs), making it a versatile tool for processing image animations. Output filenames are generated automatically based on a user-defined template specified with -output, allowing for flexible naming conventions incorporating sequential numbers or frame numbers. This utility is invaluable for tasks such as creating image sprites, tiling large images, or isolating frames from video-like image sequences.

When specifying both explicit dimensions (-width, -height) and a grid (-cols, -rows), the explicit dimensions will take precedence if they define a grid that fits the input image. If the input image dimensions are not exact multiples of the specified -width and -height, some output images might be smaller unless -pad is used.

pamsplit adheres to the standard Netpbm pipeline philosophy. It can read image data from standard input (e.g., piped from another Netpbm command) or from a specified inputfile. Output images are written to individual files whose names are constructed based on the -output template, allowing for automated batch processing and organized file management.

The command offers highly flexible splitting methods. Users can precisely define the size of each output chunk using -width and -height for fixed-size splits. Alternatively, for grid-based layouts, -cols and -rows divide the image into an equal number of horizontal and vertical sections. For multi-frame images, the -frame, -frames, and -startframe options enable precise control over frame extraction, making it suitable for animations or image sequences.

pamsplit is a core utility within the Netpbm project, a comprehensive toolkit for manipulating graphic files. As part of Netpbm, its development is integrated into the larger suite's evolution, providing fundamental image splitting capabilities that have been refined over time as part of this venerable open-source project.

pamcut(1), pamflip(1), pnmcat(1), pamstack(1), pam(5)