DEV Community: choe seunggyu

Your 16px favicon is blurry because of geometry, not the resampler

choe seunggyu — Sat, 17 Oct 2026 13:34:02 +0000

After my post on PNG entries in .ico files, a commenter asked a fair question: when you generate the small sizes, do you pixel-align them? Their point was that a 16px icon looks soft even when nothing is "resampled badly".

The honest answer for the favicon tool in the image editor I run was no. It takes the artwork, crops it to a square, and draws it once at each target size with the browser's best smoothing:

ctx.imageSmoothingEnabled = true
ctx.imageSmoothingQuality = 'high'
ctx.drawImage(src, sx, sy, square, square, 0, 0, size, size)

No per-size snapping and no hinting. So I measured what that pipeline actually produces, and found that the commenter was right about the cause.

The test

One glyph, a capital "I" (a vertical bar with a bar on top and bottom), drawn on a dark plate in a 512x512 canvas. I drew it two ways:

By eye: 40px strokes at round-number positions (bars at y = 100 and 372, stem at x = 236). This is what you get when you design at 512 and don't think about 16.
On a 16x16 grid: every edge on a multiple of 32px (512 / 16). Same shape, strokes exactly 2 grid units wide.

Then I downscaled each to 16, 32 and 48 with a single drawImage, the same call as above, in headless Chromium 141. I counted soft pixels: pixels whose value is between the plate and white by more than 10% at either end. These are the grey, half-covered pixels you see as blur.

Size	By eye: soft pixels	By eye: fully white	On grid: fully white
16	52	0	52
32	108	68	208
48	168	212	468

At 16px the by-eye version has no fully white pixels at all. All 52 pixels of the glyph came out grey.

The middle and right images are identical, pixel for pixel. A grid-aligned master downscaled with drawImage gives you exactly what you would have drawn by hand.

The resampler is doing its job

Here are the actual values at 16px for the by-eye version (plate = 30, white = 255):

The stem runs from x = 236 to 276 at 512, which is 7.375 to 8.625 at 16. It covers 62.5% of column 7 and 62.5% of column 8. Both columns come out 170, which is 62% of the way to white.
The top bar runs from y = 100 to 140, which is 3.125 to 4.375. Row 3 is 87.5% covered and comes out 226. Row 4 is 37.5% covered and comes out 114.

That is plain area averaging, and it is correct. A 1.25px-wide stroke sitting at x = 7.375 cannot be drawn on a pixel grid. The best any filter can do is split it across two columns, and two 62% grey columns read as one blurry 2px line.

Switching the smoothing setting doesn't help:

'medium' gave the same numbers as 'high' here.
'low' and smoothing off look crisp (0 soft pixels), but only because they pick samples instead of averaging. The glyph lost a third of its pixels (36 white instead of 52), and which strokes survive depends on where the samples land. At other sizes a 1px stroke can disappear entirely.

So the blur is a geometry problem. The fix has to happen in the artwork, not in the resampler.

Fix 1: design the master on the small grid

If every horizontal and vertical edge in the master sits on a 1/16 grid line, every edge lands on a whole pixel at 16. Edges that land on whole pixels don't produce grey.

For a 512px master, the grid unit is 32px. The useful part is that the same master also works at 32 and 48, as the table shows (0 soft pixels at each): one grid unit becomes exactly 2px and 3px. Any output size that is a multiple of 16 inherits the alignment.

What this doesn't fix:

Curves and diagonals are always antialiased. Grid alignment only affects horizontal and vertical edges.
Anything you apply after the master breaks the alignment again (see the next section).
Detail smaller than one grid unit still turns to mush. The grid makes edges sharp, but it doesn't make the icon readable.

The padding trap

Most favicon generators, including mine, have a "safe padding" slider that shrinks the artwork inside the square. That rescales your carefully aligned grid.

I took the grid-aligned master from above and ran it through the tool's own padding math (pad = padding% × size, art drawn at size − 2 × pad):

Padding	16px: offset	16px: soft pixels	32px: soft pixels	48px: soft pixels
0%	0	0	0	0
5%	0.8px	40	48	108
10%	1.6px	20	44	28
12.5%	2px	36	84	120
25%	4px	28	0	84

The 12.5% row shows why. The offset is a whole 2px, but the glyph is now drawn at 12px instead of 16, so one grid unit becomes 0.75px and every edge is fractional again. Only an accident like 25% at 32px (art drawn at exactly 16px) comes out clean.

Put the padding in the master, in whole grid units, and leave the slider at 0. The same applies to cropping: if your source isn't square, the center crop can shift everything by a fraction of a pixel. Start from a square master.

Fix 2: draw 16 (and maybe 32) separately

Grid alignment gets you sharp edges. It doesn't get you a recognizable icon. At 16x16 you have 256 pixels, and a design that works at 512 usually has too much in it.

This is what hinting means for icons: the small sizes are different drawings, not smaller copies. Typical changes at 16:

Drop inner detail, shadows and secondary shapes
Make strokes 1 or 2 full pixels, never 1.5
Open up gaps between shapes to at least 1px so they don't merge
Exaggerate the one feature that makes the icon recognizable

The usual split is to hand-draw 16 (and 32 if it matters to you), and generate 48 and up from the master. From 48 up there are enough pixels that a grid-aligned downscale is good enough.

The ICO format is built for this. Each entry is its own image, so nothing requires 16 to be derived from 48. Browsers pick the 16 or 32 entry for the tab, so whatever you put there is what people see.

Here is how to combine a hand-drawn 16 with generated larger sizes. Decode the hand-drawn file to RGBA at 1:1 (no scaling), and let the encoder write it as a DIB entry. That keeps you clear of the PNG-entry problem at small sizes.

import { encodeIco } from '@editpot/ico-encoder'

// Draws the file at size x size and returns RGBA.
// A size x size file is copied 1:1; a larger master is downscaled.
async function rgbaAt(url, size) {
  const img = await createImageBitmap(await (await fetch(url)).blob())
  const c = new OffscreenCanvas(size, size)
  const ctx = c.getContext('2d')
  ctx.imageSmoothingQuality = 'high'
  ctx.drawImage(img, 0, 0, size, size)
  return ctx.getImageData(0, 0, size, size).data
}

const ico = encodeIco([
  { width: 16, rgba: await rgbaAt('/art/icon-16.png', 16) }, // drawn
  { width: 32, rgba: await rgbaAt('/art/icon-32.png', 32) }, // drawn
  { width: 48, rgba: await rgbaAt('/art/master-512.png', 48) } // master
])

Make sure icon-16.png really is 16x16. If it is, the drawImage call is a straight copy and nothing gets resampled.

What the tool does today

To be clear about my own tool: editpot's favicon generator does the single-downscale pipeline described at the top, with no snapping, no per-size hinting, and no way to upload your own 16px drawing. The padding slider behaves exactly as the second table shows. If you give it a grid-aligned square master and leave padding at 0, you get the clean column. If you give it artwork drawn by eye at 512, you get the grey one.

Letting you drop in your own 16 and 32 drawings is the obvious next step, and it's on my list because of that comment.

Check your own icon

Two quick checks. First, look at the 16px output scaled up with nearest-neighbour, not in a viewer that smooths it. Then count the grey pixels:

// Soft pixels in RGBA, given background and foreground values
function softPixels(rgba, bg, fg) {
  let soft = 0
  for (let i = 0; i < rgba.length; i += 4) {
    const t = (rgba[i] - bg) / (fg - bg)
    if (t > 0.1 && t < 0.9) soft++
  }
  return soft
}

For a flat, orthogonal design, the number should be zero or close to it. If most of your glyph is in the soft count, the master is off-grid.

The short version

A high-quality downscale is area averaging. It is correct, and it still can't put a 1.25px stroke on a pixel grid
In my test, a glyph drawn by eye at 512 had 0 fully white pixels at 16px. The same glyph on a 16-grid had 0 grey ones
Align the master to a 16x16 grid (32px units at 512). 16, 32 and 48 all come out exact
Padding and cropping after the fact rescale the grid. Put padding in the master instead
Grid alignment fixes edges, not legibility. Hand-draw 16 (and maybe 32), and generate 48 and up
ICO entries are independent images, so you can mix hand-drawn and generated sizes in one file

The measurements came from headless Chromium 141 on Linux. Firefox and Safari implement imageSmoothingQuality differently, so the soft-pixel counts will differ for the by-eye version. The grid-aligned result doesn't depend on the filter, because every output pixel is fully inside or fully outside a shape.

The encoder used above is @editpot/ico-encoder on npm (MIT). The favicon tool it came from is part of editpot, a browser-based image editor.

PNG entries in an .ico: who can actually read them

choe seunggyu — Wed, 30 Sep 2026 13:10:28 +0000

The favicon tool in an image editor I run used to write every entry in its favicon.ico as a PNG. Browsers are fine with that. Then I loaded the file with System.Drawing from Windows PowerShell, and it threw:

Exception calling "ToBitmap" with "0" argument(s):
"Requested range extends past the end of the array."

The file was not corrupt. Every byte of the container was legal. The payload encoding of the small entries was the problem — and the usual advice about it ("Windows can't read PNG entries") is too vague to act on, because most of Windows reads them fine.

So I measured which consumers do and which don't.

Two payload formats in one container

An ICO file is a tiny archive:

ICONDIR       6 bytes      reserved(0), type(1 = ICO), image count
ICONDIRENTRY  16 bytes xN  width, height, colours, reserved,
                           planes, bpp, byte length, offset
payload       N blobs      one image per entry

The payload of each entry can be either of two things, and the directory entry does not say which:

DIB — a BITMAPINFOHEADER followed by raw pixels. The original format.
PNG — a complete PNG file, magic bytes and all, dropped in as a blob. Added in Windows Vista, mainly for 256x256.

PNG entries are convenient in a browser, because canvas.toBlob() hands you one for free. That is why so much generator code emits PNG at every size.

What I measured

I generated two .ico files that differ only in payload encoding: same artwork, same 16/32/48 entries, one written as PNG, one as 32-bit DIB. Then I ran four checks on Windows 11 (Windows PowerShell 5.1.26100, .NET Framework 4.8.1, release key 533509).

Check	PNG entries	DIB entries
`new System.Drawing.Icon(path)`	passes	passes
`.ToBitmap()`	throws `Requested range extends past the end of the array`	pixels and alpha intact
Entry extracted and loaded as a standalone PNG	fine, 16/32/48 all `Format32bppArgb`	n/a
`PrivateExtractIcons` (user32) at 16/32/48	all three extracted correctly	all three

Two things fall out of that table.

The Win32 icon loader is not the problem. On Windows 11, user32's icon extraction reads PNG entries at 16, 32 and 48 without complaint. If you have read that small PNG entries "don't show up in Explorer", I could not reproduce that failure on this path.

System.Drawing is. And the entry itself is valid — pulled out of the container, the same bytes load as a PNG image without complaint. It is specifically PNG-inside-ICO that Icon.ToBitmap() refuses.

Why System.Drawing fails, and why the docs suggest it shouldn't

System.Drawing grew PNG-frame support in .NET Framework 4.6. It is governed by an opt-out switch:

Switch.System.Drawing.DontSupportPngFramesInIcons

The catch is how the default is chosen. It is not the runtime version — the machine above runs .NET Framework 4.8.1. It is the target framework of the host application. An app that targets anything below 4.6 gets the legacy default, and powershell.exe (Windows PowerShell 5.1) gets it too.

You can watch the mechanism work. Same file, same session, with the switch flipped first:

$sw = 'Switch.System.Drawing.DontSupportPngFramesInIcons'
[AppContext]::SetSwitch($sw, $false)

Add-Type -AssemblyName System.Drawing
$icon = New-Object System.Drawing.Icon('C:\png-entries.ico')
$icon.ToBitmap()   # now succeeds

Which means the failure has nothing to do with how current your Windows is. It follows the consumer, and it is invisible from the outside: you cannot tell by looking at a tool whether it will read your icon. Any .NET Framework app that uses System.Drawing with the legacy default — internal utilities, build scripts, installers, resource pipelines, older WinForms tools — silently sits in the failing column.

So what should you write?

16, 32 and 48 as uncompressed 32-bit DIB. PNG only at 256x256.

DIB costs you bytes and buys you a format that has no opt-out switch anywhere. At these sizes the bytes are nothing: 16 + 32 + 48 as DIB is about 15 KB.

At 256 the trade flips — an uncompressed 256x256 DIB is 256 KB of XOR bitmap plus 8 KB of mask — and no consumer that old is asking for a 256px icon anyway.

For a favicon you can stop at 48 entirely. Browsers never ask the .ico for more, and bigger artwork is better served as separate PNG files plus an apple-touch-icon. Add the 256 entry only when the same file also has to act as a desktop or application icon.

Writing a 32-bit DIB entry

Four rules, and each one breaks differently:

1. The height field is doubled. A DIB entry stores an XOR bitmap (the colours) and an AND bitmap (the 1-bit legacy transparency mask), stacked. biHeight must be size * 2 even though the image is size tall. Get it wrong and readers take half your image, or reject the entry.

2. Rows go bottom-up. BMP scanlines start at the bottom. Canvas ImageData starts at the top. Somebody has to flip.

3. Channels are BGRA, not RGBA. Swap the red and blue bytes.

4. The AND mask still has to exist, padded to a 4-byte boundary per row: ceil(size / 32) * 4. With 32bpp the alpha channel carries the real transparency, so leaving the mask all zeros is fine for anything that reads alpha. A consumer that ignores alpha uses this mask instead, and all-zero means "fully opaque" — transparent areas come out as a black box there. If you care about that tier, set the mask bit for every pixel whose alpha is 0.

function bmpEntry(canvas: HTMLCanvasElement, size: number) {
  const ctx = canvas.getContext('2d')!
  const src = ctx.getImageData(0, 0, size, size).data

  const xorBytes = size * size * 4
  // AND mask rows are aligned to 4 bytes
  const maskStride = Math.ceil(size / 32) * 4
  const andBytes = maskStride * size

  const out = new Uint8Array(40 + xorBytes + andBytes)
  const dv = new DataView(out.buffer)
  dv.setUint32(0, 40, true)            // BITMAPINFOHEADER size
  dv.setInt32(4, size, true)           // width
  dv.setInt32(8, size * 2, true)       // height: XOR + AND stacked
  dv.setUint16(12, 1, true)            // planes
  dv.setUint16(14, 32, true)           // bits per pixel
  dv.setUint32(16, 0, true)            // BI_RGB - no compression
  dv.setUint32(20, xorBytes + andBytes, true)   // biSizeImage

  // bottom-up rows, BGRA channel order
  for (let y = 0; y < size; y++) {
    let s = (size - 1 - y) * size * 4
    let d = 40 + y * size * 4
    for (let x = 0; x < size; x++) {
      out[d] = src[s + 2]!       // B
      out[d + 1] = src[s + 1]!   // G
      out[d + 2] = src[s]!       // R
      out[d + 3] = src[s + 3]!   // A
      s += 4
      d += 4
    }
  }
  return out
}

(TypeScript; drop the types and the ! for plain JS.)

Note what is not in there: no BITMAPFILEHEADER. A standalone .bmp starts with a 14-byte file header; an ICO entry does not. Prepend one and every reader misparses the entry.

Wrapping the entries in a container

type Entry = { size: number, data: Uint8Array }

function buildIco(entries: Entry[]): Uint8Array {
  const headerSize = 6 + entries.length * 16
  const bytes = entries.reduce((n, e) => n + e.data.length, 0)
  const buf = new Uint8Array(headerSize + bytes)
  const dv = new DataView(buf.buffer)

  dv.setUint16(0, 0, true)               // reserved
  dv.setUint16(2, 1, true)               // type 1 = icon
  dv.setUint16(4, entries.length, true)  // image count

  let offset = headerSize
  entries.forEach((e, i) => {
    const o = 6 + i * 16
    const n = e.size >= 256 ? 0 : e.size
    buf[o] = n                                // width
    buf[o + 1] = n                            // height
    dv.setUint16(o + 4, 1, true)              // planes
    dv.setUint16(o + 6, 32, true)             // bpp
    dv.setUint32(o + 8, e.data.length, true)  // byte length
    dv.setUint32(o + 12, offset, true)        // offset
    buf.set(e.data, offset)
    offset += e.data.length
  })
  return buf
}

Width and height are single bytes, so 256 does not fit. The spec says write 0 and let the reader infer 256.

How to check your own file

Browsers are the worst test — they accept everything. These four catch real failures.

1. Dump the entries. PNG payloads start with 89 50 4E 47:

const buf = require('fs').readFileSync('favicon.ico')
const n = buf.readUInt16LE(4)
for (let i = 0; i < n; i++) {
  const o = 6 + i * 16
  const size = buf[o] === 0 ? 256 : buf[o]
  const off = buf.readUInt32LE(o + 12)
  const len = buf.readUInt32LE(o + 8)
  const kind = buf.readUInt32BE(off) === 0x89504e47 ? 'PNG' : 'DIB'
  console.log(`${size}x${size}  ${kind}  ${len} bytes`)
}

You want DIB on 16, 32 and 48.

2. Hand it to System.Drawing in a legacy host. Windows PowerShell 5.1 is exactly that host, which makes it a convenient stand-in for every tool in the failing column. Do not flip the AppContext switch here — the point is to fail the way those tools fail:

Add-Type -AssemblyName System.Drawing
$icon = New-Object System.Drawing.Icon('C:\favicon.ico')
$icon.ToBitmap().Save('C:\check.png')

Note that the constructor is not the test. It succeeds on a file ToBitmap() cannot decode.

3. Look at it in Explorer. Put the .ico in a folder and switch the view between Small icons, Medium icons and Large icons — each view pulls a different entry, so a blank at one size points straight at the broken one. For the 16px path specifically, make a desktop shortcut and set its icon to the file (Properties → Change Icon). The Change Icon dialog itself only previews one size, so it is not a substitute for the view switching.

4. Check the small sizes on their own. 16x16 is what a browser tab, a window title bar and Explorer's small-icon view use (a HiDPI tab pulls 32 instead). It is also the size where artwork downscaled from one big PNG turns to mush. Render each size from the source rather than resampling the largest one.

The short version

An ICO entry is either a DIB or a PNG, and the directory does not tell you which
user32's icon extraction reads PNG entries at 16, 32 and 48; System.Drawing in .NET Framework apps with the legacy default does not, and that includes Windows PowerShell 5.1
The switch is Switch.System.Drawing.DontSupportPngFramesInIcons, and its default follows the app's target framework, not the installed runtime
So: DIB for 16/32/48, PNG only at 256, and for a favicon you can stop at 48
biHeight = size * 2, bottom-up rows, BGRA, AND mask padded to 4 bytes per row, no BITMAPFILEHEADER
256 is written as 0 in the single-byte width and height fields

I wrote this encoder for editpot, a browser-based image editor whose favicon tool builds the .ico on the client — which is why it had to be plain Uint8Array work rather than a native icon library.

Update (Oct 2026): that encoder is now a standalone package on npm — @editpot/ico-encoder.