Coverage for downtify/image_size.py: 76%
76 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Read an image's pixel size from its header bytes.
3The library upgrade needs to know how big a cover already is before it
4decides to replace it, and it asks that question once per track across a
5whole library — so it reads the few header bytes that carry the size
6instead of decoding the image. JPEG, PNG, WebP and GIF cover every cover
7Downtify writes or finds.
8"""
10from __future__ import annotations
12import struct
13from typing import Optional
15#: Start-of-frame markers that carry the size. SOF4/SOF8/SOF12 (0xC4,
16#: 0xC8, 0xCC) are Huffman/arithmetic tables, not frames.
17_JPEG_SOF = frozenset({
18 0xC0,
19 0xC1,
20 0xC2,
21 0xC3,
22 0xC5,
23 0xC6,
24 0xC7,
25 0xC9,
26 0xCA,
27 0xCB,
28 0xCD,
29 0xCE,
30 0xCF,
31})
33Size = tuple[int, int]
36def _png_size(data: bytes) -> Optional[Size]:
37 if len(data) < 24 or data[12:16] != b'IHDR':
38 return None
39 width, height = struct.unpack('>II', data[16:24])
40 return (width, height)
43def _gif_size(data: bytes) -> Optional[Size]:
44 if len(data) < 10:
45 return None
46 width, height = struct.unpack('<HH', data[6:10])
47 return (width, height)
50def _jpeg_size(data: bytes) -> Optional[Size]:
51 # Walk the segment chain: 0xFF, marker, 2-byte length, payload.
52 pos = 2
53 end = len(data)
54 while pos + 9 < end:
55 if data[pos] != 0xFF:
56 # Skip fill bytes; anything else means the chain is broken.
57 pos += 1
58 continue
59 marker = data[pos + 1]
60 pos += 2
61 if marker in {0xD8, 0x01} or 0xD0 <= marker <= 0xD7:
62 continue
63 if marker == 0xDA: # start of scan: no size past this point
64 return None
65 (length,) = struct.unpack('>H', data[pos : pos + 2])
66 if length < 2:
67 return None
68 if marker in _JPEG_SOF:
69 height, width = struct.unpack('>HH', data[pos + 3 : pos + 7])
70 return (width, height)
71 pos += length
72 return None
75def _webp_size(data: bytes) -> Optional[Size]:
76 if len(data) < 30:
77 return None
78 chunk = data[12:16]
79 if chunk == b'VP8 ':
80 if data[23:26] != b'\x9d\x01\x2a':
81 return None
82 width, height = struct.unpack('<HH', data[26:30])
83 return (width & 0x3FFF, height & 0x3FFF)
84 if chunk == b'VP8L':
85 if data[20] != 0x2F:
86 return None
87 (bits,) = struct.unpack('<I', data[21:25])
88 return ((bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1)
89 if chunk == b'VP8X':
90 # 24-bit little-endian, stored as size - 1.
91 width = int.from_bytes(data[24:27], 'little') + 1
92 height = int.from_bytes(data[27:30], 'little') + 1
93 return (width, height)
94 return None
97def image_dimensions(data: Optional[bytes]) -> Optional[Size]:
98 """Return ``(width, height)`` for *data*, or ``None`` if unreadable."""
100 if not data or len(data) < 10:
101 return None
102 try:
103 if data[:8] == b'\x89PNG\r\n\x1a\n':
104 size = _png_size(data)
105 elif data[:3] == b'\xff\xd8\xff':
106 size = _jpeg_size(data)
107 elif data[:4] == b'RIFF' and data[8:12] == b'WEBP':
108 size = _webp_size(data)
109 elif data[:6] in {b'GIF87a', b'GIF89a'}:
110 size = _gif_size(data)
111 else:
112 return None
113 except (struct.error, IndexError):
114 return None
115 if size is None or size[0] <= 0 or size[1] <= 0:
116 return None
117 return size
120def image_short_side(data: Optional[bytes]) -> int:
121 """The smaller of the two sides, or ``0`` when the size is unknown.
123 Covers are square in practice; using the short side keeps a wide
124 banner from counting as high-resolution art.
125 """
127 size = image_dimensions(data)
128 return min(size) if size else 0