ICNS 1-bit, indexed and mask elements

The oldest element types hold small icons with no compression at all. Each row of pixels starts on a byte boundary, the top row comes first, and every value follows directly after the element’s 8-byte header.

1-bit icons

In these types each pixel is one bit, the highest bit of a byte being the leftmost pixel. A set bit is black and a clear bit is white. Rows are not padded beyond the whole bytes they need, so a 32-pixel row is 4 bytes.

Type	Pixels	Bytes of data	Holds
`ICON`	32 × 32	128	The image only
`ICN#`	32 × 32	256	The image, then a 1-bit mask
`icm#`	16 × 12	48	The image, then a 1-bit mask
`ics#`	16 × 16	64	The image, then a 1-bit mask
`ich#`	48 × 48	576	The image, then a 1-bit mask

0Type ICN#4 bytes
4Length 2644 bytes
8Image 32 rows of 4 bytes, 1 is black128 bytes
136Mask 32 rows of 4 bytes, 1 is opaque128 bytes

An ICN# element

Indexed icons

Each pixel is an index into one of Apple’s standard palettes, which the file does not hold. In the 4-bit types the high nibble of a byte is the left pixel. The types have no mask of their own: the libicns library pairs each with the 1-bit element of the same size.

Type	Pixels	Bits	Bytes of data	Mask from
`icm4`	16 × 12	4	96	`icm#`
`icm8`	16 × 12	8	192	`icm#`
`ics4`	16 × 16	4	128	`ics#`
`ics8`	16 × 16	8	256	`ics#`
`icl4`	32 × 32	4	512	`ICN#`
`icl8`	32 × 32	8	1,024	`ICN#`
`ich4`	48 × 48	4	1,152	`ich#`
`ich8`	48 × 48	8	2,304	`ich#`

On macOS 27 the sips command ignores those 1-bit masks and draws these icons opaque. The explorer applies the mask, so its pictures show the transparency that libicns describes.

Masks

A mask gives transparency to an icon that holds only colours. The 1-bit masks live inside the # elements above: a set bit is opaque and a clear bit transparent, with the same layout as the image.

The 8-bit masks are elements of their own, one byte a pixel with no compression, and go with the run-length encoded 24-bit types. 0 is transparent and 255 opaque.

Mask	Pixels	Bytes of data	Goes with
`s8mk`	16 × 16	256	`is32`
`l8mk`	32 × 32	1,024	`il32`
`h8mk`	48 × 48	2,304	`ih32`
`t8mk`	128 × 128	16,384	`it32`

The ARGB, PNG and JPEG 2000 elements carry their own alpha and use no mask.

Apple’s standard palettes

Apple does not give these tables with the format. The values below are the ones the libicns library tabulates.

16 colours

The 4-bit icons index this table. On macOS 27, sips does not use it: it reads a 4-bit value n as entry n × 17 of the 256-colour palette, so 1 is FF9900 and 12 is 0033FF. The explorer draws the table below.

Index	Colour	Index	Colour
0	`FFFFFF`	8	`1FB714`
1	`FCF305`	9	`006411`
2	`FF6402`	10	`562C05`
3	`DD0806`	11	`90713A`
4	`F20884`	12	`C0C0C0`
5	`4600A5`	13	`808080`
6	`0000D4`	14	`404040`
7	`02ABEA`	15	`000000`

256 colours

The 8-bit icons index this table. All 256 entries matched sips on macOS 27. It has two parts:

Indexes	Colours
0 to 214	A colour cube of 6 levels each of red, green and blue (`FF`, `CC`, `99`, `66`, `33`, `00`), starting at white and counting blue fastest, without the final black
215 to 224	Red alone: `EE`, `DD`, `BB`, `AA`, `88`, `77`, `55`, `44`, `22`, `11`
225 to 234	Green alone, the same ten levels
235 to 244	Blue alone, the same ten levels
245 to 254	Grey, the same ten levels
255	Black