winicontopam

Read an ICO file and convert the best quality image contained therein to the PAM format

$ winicontopam [path/to/input_file.ico] > [path/to/output.pam]

$ winicontopam [[-al|-allimages]] [path/to/input_file.ico] > [path/to/output.pam]

$ winicontopam [[-i|-image]] [n] [path/to/input_file.ico] > [path/to/output.pam]

$ winicontopam [[-an|-andmasks]] [path/to/input_file.ico] > [path/to/output.pam]

winicontopam [-width=] [-height=] [-depth=] [-index=] [-verbose] [-list] [-alpha] [-forecolor=] [-backcolor=] [-reportsize] [-reportformat] [iconfile]

-width=
    Selects the image within the icon file that has the specified width W (in pixels).

-height=
    Selects the image within the icon file that has the specified height H (in pixels).

-depth=
    Selects the image within the icon file that has the specified color depth D (in bits per pixel).

-index=
    Selects the image at the specified zero-based index N within the icon file. The first image is at index 0.

-verbose
    Prints detailed information about the icon file and the selected image to standard error.

-list
    Lists all images contained within the icon file, showing their dimensions, depth, and index. No image is converted when this option is used.

-alpha
    Ensures that the output PAM image includes an alpha channel, even if the input image's alpha information is minimal or implicit. By default, an alpha channel is only output if one is truly present in the source icon.

-forecolor=
    Specifies the foreground color to use for 1-bit (monochrome) icons. COLOR can be a color name or a hexadecimal RGB value (e.g., '#RRGGBB'). Defaults to black.

-backcolor=
    Specifies the background color to use for 1-bit (monochrome) icons. COLOR can be a color name or a hexadecimal RGB value. Defaults to white.

-reportsize
    Outputs only the width and height of the selected image to standard output, without converting the image itself.

-reportformat
    Outputs only the Netpbm format (PBM, PGM, PPM, or PAM) that the selected image would convert to, without performing the conversion.

winicontopam is a specialized utility from the Netpbm toolkit, designed to convert images embedded within a Windows icon (.ico) file into the Portable Arbitrary Map (PAM) format. Windows icon files can contain multiple images, varying in size, color depth, and resolution, to suit different display contexts. winicontopam allows users to precisely select which of these embedded images to extract for conversion, using criteria such as specific width, height, color depth, or its index within the icon file. The output PAM image is a versatile Netpbm super-format capable of representing various types of pixel data, making it suitable for further processing with other Netpbm tools or conversion to other image formats. This command is invaluable for developers and designers who need to extract specific icon representations from .ico files for use in cross-platform applications or detailed image manipulation.

Only one image can be converted per execution of winicontopam. If multiple image selection criteria (width, height, depth, index) are provided, they are applied sequentially to find the best match. If no criteria are specified, the first image found in the ICO file is chosen. For 1-bit monochrome icons, the foreground and background colors are determined by the icon's color table or can be specified using -forecolor and -backcolor options.

winicontopam reads the Windows icon file from the specified iconfile argument. If iconfile is omitted, it reads the icon data from standard input. The converted PAM image is always written to standard output, making it easy to pipe the output to other Netpbm tools or programs that can handle PAM images, such as pamtopng or pamtojpeg for further format conversion.

When multiple selection criteria (e.g., -width, -height, -depth, -index) are provided, winicontopam searches for an image that matches all specified criteria. If no image matches all criteria, or if only partial criteria are given, it attempts to find the best suitable image based on an internal priority, typically preferring exact matches and then the first available image if no specific criteria uniquely identify one. It's often recommended to use -list first to understand the contents of an ICO file before attempting a conversion.

winicontopam is an integral part of the Netpbm project, a comprehensive suite of graphics programs that originated in the late 1980s with Jef Poskanzer's PBMPlus package. The Netpbm project has continuously evolved to support a wide array of image formats and manipulations, with winicontopam specifically developed by Bryan Henderson to address the need for converting proprietary Windows icon formats into open, versatile Netpbm formats for broader interoperability and image processing capabilities on Linux and Unix-like systems.

pam(5), icotool(1), pnmtoico(1), pamtopng(1)