ppmtoapplevol

Convert a PPM image into an Apple volume label image

$ ppmtoapplevol [path/to/image.ppm] > [path/to/output]

ppmtoapplevol [-name filename] [-volname volume_name] [-notime] [-date month day year] [-time hour minute second] [ppmfile]

-name filename
    Specifies the filename for the volume header within the ProDOS directory. The default is "PICTURE.SHR".

-volname volume_name
    Sets the volume name for the created ProDOS 8 volume. The default is "MY_VOLUME". This name can be up to 15 characters long.

-notime
    Disables the embedding of time and date stamps into the volume header, which might otherwise reflect the current system time at conversion.

-date month day year
    Allows manual specification of the date to be embedded in the volume header, overriding the system's current date.

-time hour minute second
    Allows manual specification of the time to be embedded in the volume header, overriding the system's current time.

ppmfile
    The input Portable Pixmap (PPM) file to be converted. If omitted, ppmtoapplevol reads the PPM data from standard input.

ppmtoapplevol is a specialized command within the Netpbm suite, designed to convert a Portable Pixmap (PPM) image into an Apple IIgs ProDOS 8 volume header. This conversion is crucial for creating custom bootable disks or disk images for the Apple IIgs, where a graphical header appears upon boot.

The command expects a specific input: a PPM file that is exactly 320 pixels wide by 200 pixels high. This resolution matches the Apple IIgs Super Hires (SHR) graphics mode. Furthermore, the input image must be a 16-color image, chosen from the extensive 4096-color palette of the Apple IIgs. ppmtoapplevol intelligently attempts to select the best 16-color palette from the provided image. If the image uses more than 16 colors or if a suitable palette cannot be determined, the conversion will fail.

The output is raw volume header binary data, intended to be written directly to the beginning of an Apple IIgs disk image, often using tools like dd. This allows for a personalized graphical splash screen to be displayed when the volume is accessed or booted on an Apple IIgs system, making it a unique tool for enthusiasts and retro-computing projects.

This command has strict requirements for the input image:

1. Input Dimensions: The PPM file must be exactly 320 pixels wide by 200 pixels high.

2. Color Palette: The image must be a 16-color image or contain colors that can be closely mapped to 16 colors from the Apple IIgs 4096-color palette. ppmtoapplevol does not perform complex color reduction; it expects the image to be inherently suitable for this conversion.

3. Output Format: The output is a raw binary volume header, not a standalone graphical file. It is typically used with disk imaging tools like dd to be written to the beginning of an Apple IIgs disk image or physical disk.

A ProDOS 8 volume header is a special data block at the beginning of an Apple IIgs disk or disk image. It contains metadata about the volume and, in this specific case, can include a Super Hires (SHR) graphical splash screen. This screen is displayed by the Apple IIgs operating system when the volume is mounted or booted, providing a visual identity to the disk.

The binary output of ppmtoapplevol is designed to be written directly to the start of an Apple IIgs disk image (e.g., a .PO or .2MG file). A common usage pattern involves piping the output to the dd command, like:

ppmtoapplevol myimage.ppm > header.bin
dd if=header.bin of=mydisk.2mg bs=512 count=1 conv=notrunc

This ensures the graphical header is placed at the correct offset on the disk image without overwriting existing data if only the header block needs to be updated.

ppmtoapplevol is an integral part of the Netpbm graphics toolkit, which has a long and rich history in Unix-like systems, evolving from the original PBMplus package. Its specific function catering to the Apple IIgs underscores Netpbm's broad utility in converting between a vast array of niche and historical image formats. While not a mainstream command, its existence highlights the toolkit's commitment to supporting retro-computing and preserving compatibility with older systems, particularly for tasks like custom disk image creation.

ppm(5), netpbm(1), dd(1), ppmtopict(1), ppmtoarc(1)