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

1"""Read an image's pixel size from its header bytes. 

2 

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""" 

9 

10from __future__ import annotations 

11 

12import struct 

13from typing import Optional 

14 

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}) 

32 

33Size = tuple[int, int] 

34 

35 

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) 

41 

42 

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) 

48 

49 

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 

73 

74 

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 

95 

96 

97def image_dimensions(data: Optional[bytes]) -> Optional[Size]: 

98 """Return ``(width, height)`` for *data*, or ``None`` if unreadable.""" 

99 

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 

118 

119 

120def image_short_side(data: Optional[bytes]) -> int: 

121 """The smaller of the two sides, or ``0`` when the size is unknown. 

122 

123 Covers are square in practice; using the short side keeps a wide 

124 banner from counting as high-resolution art. 

125 """ 

126 

127 size = image_dimensions(data) 

128 return min(size) if size else 0