PAMDICE(1)

📦
version 11.13.03 · 11 versions
, in ubuntu stonking

💖 PAMDICE(1) — the Pamdice User Manual, bestie edition 💖

okay so. hi. you're in the General Commands Manual section and today we're talking about pamdice, which is genuinely one of the most underrated little Netpbm girlies out there. it slices images. that's the whole vibe. let's get into it 💅

✨ NAME ✨

pamdice — slice a Netpbm image into many horizontally and/or vertically

(yeah bestie the original sentence just kinda stops there, I'm not gonna make up an ending for it, I'm faithful like that 🫶)

🌸 EXAMPLE 🌸

k so in all of these, myimage.ppm is an image that is 10,000 pixels wide and 8,000 pixels high. absolute unit of an image. iconic honestly.

$ pamdice myimage.ppm -width=1000 -height=1000 -outstem=myimage_part
$ pamundice myimage_part_%1d_%1a.ppm -across=10 -down=8 >myimage.ppm
$ pamdice myimage.ppm -height=1000 -voverlap=90 -outstem=myimage_part
$ pamdice myimage.ppm -width=1000 -height=1000 -outstem=myimage_part \
    -listfile=tiles.txt
$ pamundice -across=10 -down=8 -listfile=tiles.txt >myimage.ppm
$ pamdice myimage.ppm -width=1000 -height=1000 -outstem=myimage_part \
    -indexfile=tiles.pam
$ pamundice myimage_part_%1d_%1a.ppm -indexfile=tiles.pam >myimage.ppm

see how she dice, then pamundice un-dices? it's giving cut and paste. it's giving arts and crafts. we love a reversible operation 😌

✨ SYNOPSIS ✨

pamdice

-outstem=filenamestem

[-outsuffix=filenamesuffix]

[-width=width]

[-height=height]

[-hoverlap=hoverlap]

[-voverlap=voverlap]

[-numberwidth=N]

[-listfile=textfilename]

[-indexfile=pamfilename

[-dry-run]

[-verbose]

[filename]

okay housekeeping, listen up 📢 you can use the minimum unique abbreviation of the options (so like, be lazy, she'll figure out what you meant). you can use two hyphens instead of one. and you can separate an option name from its value with white space instead of an equals sign. so flexible. so accommodating. queen behavior 👑

💖 DESCRIPTION 💖

This program is part of Netpbm(1). yes, the whole family. we stan a cohesive ecosystem.

so here's the tea: pamdice reads a PAM, PBM, PGM, or PPM image as input and splits it horizontally and/or vertically into equal size pieces, then writes them into separate files as the same kind of image. and get this — you can optionally make the pieces overlap 🔥

for the naming of the output files, go peek at the -outstem option (it's down there, it explains everything, it's very thorough).

the -width and -height options determine the size of the output pieces. that's their whole job. they're doing great.

pamundice can rejoin the images. and if you want finer control, you can also use pamcat. options upon options, bestie.

one use for this (the practical one): making pieces that take less computer resources than the whole image to process. like imagine you have an image SO large that an image editor can't read it all into memory, or it processes it very slowly 😭 with pamdice you split it into smaller pieces, edit one at a time, and then reassemble them. chef's kiss. problem solved.

another use: printing a large image in small printer-sized pieces that you can glue together 🎀 ppmglobe does a similar thing; it lets you glue the pieces together into a sphere. yes, a sphere. crafting hour fr fr.

and if you want to cut pieces from an image individually, not in a regular grid, use pamcut. different tool, different vibe, know the difference okay? ✨

💅 OPTIONS 💅

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

  • -outstem=filenamestem — this is the moment. this option determines the names of the output files. Each output file is named filenamestem_y_x.type, where filenamestem is the value of the -outstem option, x and y are the horizontal and vertical locations, respectively, in the input image of the output image, with zero being the leftmost and top, and type is .pbm, .pgm, .ppm, or .pam, depending on the type of image. your tiles get government names and they're adorable.

x and y are filled with leading zeroes so they are the same width in every file. Use -numberwidth to specify that width; otherwise, it defaults to the minimum width that works for all the files. For example, if you have 25 slices across and no -numberwidth, x is 2 digits for all the output files. The leftmost slice is numbered '00'; the next one is '01', etc. With -numberwidth=3, x is '000', '001', etc.

You can override the file type suffix with an -outsuffix option. 💖

  • -outsuffix=filenamesuffix — this specifies the suffix for the output file names. note that pamdice does not add a period. so you bring your own punctuation, she's not gonna do it for you 🫶

Example: -outsuffix=.pnm

The default is an appropriate suffix for the image type, e.g. '.ppm'.

This option was new in Netpbm 11.11 (June 2025). fresh off the press, baby ✨

  • -numberwidth=N — this option determines the width of the numbers in the output file names. go read the -outstem option for the details, it spills all the tea.
⚠️ it is not valid to specify a width less than is necessary to represent all the slices. don't do it. she will not accept it. the math must math.

This option was new in Netpbm 11.10 (March 2025).

  • -width=width — this gives the width in pixels of the output images. The rightmost pieces are smaller than this if the input image is not a multiple of width pixels wide. (ragged edge behavior, we accept her as she is)

If you don't specify this, the default is the entire width of the image; i.e. pamdice does not split vertically.

  • -height=height — this gives the height in pixels of the output images. The bottom pieces are smaller than this if the input image is not a multiple of height pixels high.

If you don't specify this, the default is the entire height of the image; i.e. pamdice does not split horizontally.

  • -hoverlap=hoverlap — this gives the horizontal overlap in pixels between output images. Each image in a row will overlap the previous one by hoverlap pixels. By default, there is no overlap.

This option was new in Netpbm 10.23 (July 2004). vintage 💜

  • -voverlap=voverlap — this gives the vertical overlap in pixels between output images. Each row of images will overlap the previous row by voverlap pixels. By default, there is no overlap.

This option was new in Netpbm 10.23 (July 2004). twins 🫶

  • -listfile=textfilename — this causes the program to generate a file listing the names of all the tile files it creates. It is in row-major order. For example,
$ pamdice -width=100 -height=100 -outstem=myimage_part
-listfile=mylist.txt \
      -numberwidth=3 myimage.ppm

on a 200x200 image generates the file mylist.txt containing this:

myimage_part_000_000.ppm
myimage_part_000_001.ppm
myimage_part_001_000.ppm
myimage_part_001_001.ppm

You can use this list file with pamundice -listfile in lieu of an input file name pattern argument, which may save you the trouble of coordinating the patterns used in your invocations of pamdice and pamundice. no more pattern-syncing anxiety. we're free 🌈

This option was new in Netpbm 11.10 (March 2025).

  • -indexfile=pamfilename — this causes the program to generate a file containing a PAM image that contains rank and file numbers for the tiles. It is simply an image whose width and height are the number of horizontal and vertical slices, respectively, in which each tuple is just the row and column number of that tuple. For example, if pamdice produces 3 slices across and 2 down, the image looks like this:
(0,0) (0,1) (0,2)
(1,0) (1,1) (1,2)

The depth of the image is 2, the tuple type is 'grid_coord' (a tuple type invented for use with pamdice and pamundice), and the maxval is 255 unless the height or width is greater than 256, in which case it is 65535.

This image can be useful as input to pamundice, particularly after doing transformations on it. The prime example of such usage is in flipping a large image. You can dice the image with pamdice, then flip each of the tiles produced (with pamflip), then flip the index image (again with pamflip), then use pamundice with the flipped tiles and the flipped index image to generate a flipped version of the original large image. the way that actually works is so satisfying, iykyk 😭

This option was new in Netpbm 11.10 (March 2025).

  • -dry-run — this makes pamdice skip creating the output tile images. It still creates the list file (with -listfile) and the index file (with -indexfile) and checks for most errors. it's the rehearsal, not the show. test run energy ✨

This option was new in Netpbm 11.10 (March 2025).

  • -verbose — Print information about the processing to Standard Error. she's chatty and we love that for her 💬

🦋 HISTORY 🦋

pamdice was new in Netpbm 9.25 (March 2002). a legend from the start, truly.

Before Netpbm 10.29 (August 2005), there was a limit of 100 slices in each direction, and the output file names always used two digits for the slice number. ancient times. dark ages. we don't go back 💀

🌈 SEE ALSO 🌈

pamundice(1), pamcut(1), pamcat(1), pgmslice(1), ppmglobe(1) pamflip(1) pnm(1) pam(1)

(the whole friend group, go say hi ✨)

🎀 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/pamdice.html

okay that's the whole page bestie, you're officially certified in pamdice 🎓💖

netpbm documentation, 27 May 2025, Pamdice User Manual(1) — that's the footer, and I'm folding it in right here as a lil sign-off: this was netpbm documentation, dated 27 May 2025. bye pookie, go slice something 👑🌸
📦 where this page comes from