Loading AI tools
From Wikipedia, the free encyclopedia
The Apple Icon Image format (.icns) is an icon format used in Apple Inc.'s macOS. It supports icons of 16 × 16, 32 × 32, 48 × 48, 128 × 128, 256 × 256, 512 × 512 points at 1x and 2x scale, with both 1- and 8-bit alpha channels and multiple image states (example: open and closed folders). The fixed-size icons can be scaled by the operating system and displayed at any intermediate size.
![]() | |
Filename extension |
.icns |
---|---|
Internet media type | image/x-icns |
Type code | icns |
Uniform Type Identifier (UTI) | com.apple.icns |
Magic number | 69 63 6e 73 |
Developed by | Apple Inc. |
Type of format | Icon file format |
As of macOS 11, asset catalogs are the preferred file format for macOS custom icons instead.[1]
The file format consists of an 8 byte header, followed by any number of icons.
Offset | Size | Purpose |
---|---|---|
0 | 4 | Magic literal, must be "icns" (0x69, 0x63, 0x6e, 0x73) |
4 | 4 | Length of file, in bytes, msb first |
Offset | Size | Purpose |
---|---|---|
0 | 4 | Icon type, see OSType below. |
4 | 4 | Length of data, in bytes (including type and length), msb first |
8 | Variable | Icon data |
OSType | Length (bytes) | Size (pixels) | Supported OS Version | Description |
---|---|---|---|---|
ICON | 128 | 32×32 | 1.0 | 1-bit mono icon |
ICN# | 256 | 32×32 | 6.0 | 1-bit mono icon with 1-bit mask |
icm# | 48 | 16×12 | 6.0 | 1 bit mono icon with 1-bit mask |
icm4 | 96 | 16×12 | 7.0 | 4 bit icon |
icm8 | 192 | 16×12 | 7.0 | 8 bit icon |
ics# | 64 | 16×16 | 6.0 | 1-bit mono icon with 1-bit mask |
ics4 | 128 | 16×16 | 7.0 | 4-bit icon |
ics8 | 256 | 16×16 | 7.0 | 8 bit icon |
is32 | varies1 (768) | 16×16 | 8.5 | 24-bit RGB icon |
s8mk | 256 | 16×16 | 8.5 | 8-bit mask |
icl4 | 512 | 32×32 | 7.0 | 4-bit icon |
icl8 | 1024 | 32×32 | 7.0 | 8-bit icon |
il32 | varies1 (3072) | 32×32 | 8.5 | 24-bit RGB icon |
l8mk | 1024 | 32×32 | 8.5 | 8-bit mask |
ich# | 576 | 48×48 | 8.5 | 1-bit mono icon with 1-bit mask |
ich4 | 1152 | 48×48 | 8.5 | 4-bit icon |
ich8 | 2304 | 48×48 | 8.5 | 8-bit icon |
ih32 | varies1 (6912) | 48×48 | 8.5 | 24-bit RGB icon |
h8mk | 2304 | 48×48 | 8.5 | 8-bit mask |
it32 | varies1 (49152 + 4)2 | 128×128 | 10.0 | 24-bit RGB icon |
t8mk | 16384 | 128×128 | 10.0 | 8-bit mask |
icp4 | varies | 16x16 | 10.7 | JPEG 2000† or PNG† format or 24-bit RGB icon[2] |
icp5 | varies | 32x32 | 10.7 | JPEG 2000† or PNG† format or 24-bit RGB icon[2] |
icp6 | varies | 48x48 | 10.7 | JPEG 2000† or PNG† format |
ic07 | varies | 128x128 | 10.7 | JPEG 2000 or PNG format |
ic08 | varies | 256x256 | 10.5 | JPEG 2000 or PNG format |
ic09 | varies | 512x512 | 10.5 | JPEG 2000 or PNG format |
ic10 | varies | 1024x1024 | 10.7 | JPEG 2000 or PNG format (512x512@2x "retina" in 10.8) |
ic11 | varies | 32x32 | 10.8 | JPEG 2000 or PNG format (16x16@2x "retina") |
ic12 | varies | 64x64 | 10.8 | JPEG 2000 or PNG format (32x32@2x "retina") |
ic13 | varies | 256x256 | 10.8 | JPEG 2000 or PNG format (128x128@2x "retina") |
ic14 | varies | 512x512 | 10.8 | JPEG 2000 or PNG format (256x256@2x "retina") |
ic04 | varies1 (1024) | 16x16 | ARGB or JPEG 2000† or PNG† format | |
ic05 | varies1 (4096) | 32x32 | ARGB or JPEG 2000† or PNG† format (16x16@2x "retina") | |
icsb | varies1 (1296) | 18x18 | ARGB or JPEG 2000† or PNG† format | |
icsB | varies | 36x36 | JPEG 2000 or PNG format (18x18@2x "retina") | |
sb24 | varies | 24x24 | JPEG 2000 or PNG format | |
SB24 | varies | 48x48 | JPEG 2000 or PNG format (24x24@2x "retina") |
OSType | Description |
---|---|
'TOC ' |
"Table of Contents" a list of all image types in the file, and their sizes (added in Mac OS X 10.7).
A TOC is written out as an identifier (4 bytes) and size (4 bytes). Each subsequent record (8 bytes each) maps to the icon formats found in the file. The data isn't included in this phase. |
'icnV' |
4-byte big endian float - equal to the bundle version number of Icon Composer.app that created the icon |
'name' |
Usage unknown (all tested files use either "icon"[3] or "template"[4]). |
'info' |
Info binary plist. Usage unknown (only name field seems to be used). |
'sbtp' |
Nested "template" icns file. Usage unknown. |
'slct' |
Nested "selected" icns file. Usage unknown. |
FD D9 2F A8 |
Nested "dark" icns file. Allows automatic icon switching in Dark mode. (added in macOS 10.14).
Note: The contents of this record is a full .icns file with multiple formats. If the record bytes are written out to disk, the icns file header and file size are still required to see the full dark mode icon. |
Element types that deal with ARGB (32-bit) or RGB (24-bit) image formats require different types of headers before the binary data. It is important to note that this header is part of the image data and is not the 4-byte big endian icon element type value (e.g. ic04 or ic05).[5]
ARGB Elements ARGB images must have their binary portion of the image data preceded by the four byte 'ARGB' header. After that, instead of each pixel with each of its four channels stored together (e.g. ARGBARGBARGB), an image with three pixels would be stored in individual channels of pixel data (e.g. AAARRRGGGBBB). In addition, each channel of pixel data needs to be encoded as mentioned below.
RGB Elements RGB images have their binary portion of the image data preceded by four zero byte characters only when the element type is 'it32'. In all other cases, no header is needed. Channel data is separated as with the ARGB binary data (e.g. RRRGGGBBB instead of RGBRGBRGB). Each channel must also be encoded as mentioned below.
Mask Elements Mask elements are not encoded like ARGB and RGB image color channel data. The data is the same as that of an ARGB image except only the alpha channel data is provided. So for an image that has two pixels, ARGBARGB, the mask data is AA.
lead value |
tail bytes |
result uncompressed |
---|---|---|
0...127 | 1...128 | 1...128 bytes |
128...255 | 1 byte | 3...130 copies |
Over time the format has been improved and there is support for compression of some parts of the pixel data. The 24-bit RGB (is32, il32, ih32, it32, icp4, icp5) and ARGB (ic04, ic05, icsb) pixel data are compressed (per channel) with a format similar to PackBits.[6] Some sources mention that the OS supports both compressed or uncompressed data chunks.[citation needed] However, manually crafting icns files with uncompressed 24-bit RGB or ARGB images will not display properly – at least on newer macOS releases (tested on macOS 11).
Here is a GitHub repo with some swift code that appears to pass the test for both encoding and decoding as described here: ByteRunLengthCoder
The following pseudocode decompresses the data:
'''While''' there '''is''' compressed data: Read one byte '''as''' an '''unsigned number''' N '''If''' N < 0x80: Output the next (N + 1) bytes '''Else''': Output the next byte (N - 0x80 + 3) times
Example: 02 01 02 02 80 03 81 04 82 05
should decompress to 01 02 02 03 03 03 04 04 04 04 05 05 05 05 05
The following pseudocode compresses the data:
'''function''' Encode(input data) '''Initialize''' output '''as''' an '''empty array''' '''Set''' index '''to''' 0 '''While''' index <dfn class="explain " ><span title="is less than"><</span></dfn> the count of data '''Initialize''' sequence '''as''' an '''empty array''' '''Set''' count '''to''' 0 ''// Unique sequence'' '''While''' count <dfn class="explain " ><span title="is less than or equal to">≤</span></dfn> 0x7F '''and''' index <dfn class="explain " ><span title="is less than"><</span></dfn> count of data '''If''' index + 2 <dfn class="explain " ><span title="is less than"><</span></dfn> count of data '''and''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted " title="at index">[index]</span> <dfn class="explain " ><span title="is equal to">=</span></dfn> data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted " title="at index + 1">[index+1]</span> '''and''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted " title="at index">[index]</span> <dfn class="explain " ><span title="is equal to">=</span></dfn> data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted " title="at index + 2">[index+2]</span> '''Break''' the '''loop''' ''// Start of a repeating sequence'' '''End''' '''If''' '''Append''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted " title="at index">[index]</span> '''to''' sequence Increment index Increment count '''End''' '''While''' '''If''' sequence '''is not empty''' '''Append''' (count - 1) '''to''' output '''Append''' all items '''in''' sequence '''to''' output '''End''' '''If''' '''If''' index <dfn class="explain " ><span title="is greater than or equal to">≥</span></dfn> count of data '''Break''' the '''loop''' '''End''' '''If''' ''// Repeating sequence'' '''Set''' repeatedByte '''to''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted " title="at index">[index]</span> '''Set''' count '''to''' 0 '''While''' count <dfn class="explain " ><span title="is less than or equal to">≤</span></dfn> 0x7F '''and''' index <dfn class="explain " ><span title="is less than count of">≤</span></dfn> data '''and''' data<templatestyles src="Template:Tooltip/styles.css" /><span class="rt-commentedText tooltip tooltip-dotted " title="at index">[index]</span> <dfn class="explain " ><span title="is equal to">=</span></dfn> repeatedByte Increment index Increment count '''End''' '''While''' '''If''' count <dfn class="explain " ><span title="is greater than or equal to">≥</span></dfn> 3 '''Append''' (0x80 + count - 3) '''to''' output '''Append''' repeatedByte '''to''' output '''Else''' ''// Less than 3 repeating bytes'' '''Append''' (count - 1) '''to''' output '''Repeat''' (count) times '''Append''' repeatedByte '''to''' output '''End''' '''Repeat''' '''End''' '''If''' '''End''' '''While''' '''Return''' output '''End''' '''function'''
Example: 01 02 02 03 03 03 04 04 04 04 05 05 05 05 05
should compress to 02 01 02 02 80 03 81 04 82 05
As of macOS 11, there are certain issues / bugs with the file format:
69636E73 00000024 69633034 0000001C 41524742 FFFFFBFF FF00FB00 FF00FB00 FFFFFBFF
69636E73 00000025 69633034 0000001D 41524742 FFFFFBFF FF00FB00 FF00FB00 FFFFFBFF 00
Various image viewers can load *.icns files, and free and open source converters from or to PNG also exist.[7][8] GTK+ can load *.icns resources since 2007.[9] Other tools supporting the format include the Apple Icon Composer and icns Browser, The Iconfactory, and IconBuilder.
MacOS[clarification needed] offers the built-in iconutil
command line tool to pack and unpack *.icns files.
Seamless Wikipedia browsing. On steroids.
Every time you click a link to Wikipedia, Wiktionary or Wikiquote in your browser's search results, it will show the modern Wikiwand interface.
Wikiwand extension is a five stars, simple, with minimum permission required to keep your browsing private, safe and transparent.