194 lines
6.4 KiB
Python
194 lines
6.4 KiB
Python
"""Image metadata: media type sniffing and dimension parsing.
|
|
|
|
Two small jobs, both in service of the EPUB writer.
|
|
|
|
*Sniffing.* A feed image is as likely to arrive as ``application/octet-stream``
|
|
or ``text/plain`` as with a correct ``Content-Type``. An EPUB manifest entry
|
|
whose media type does not match the bytes is invalid, so the type is decided from
|
|
the actual magic bytes and the response header is only a fallback.
|
|
|
|
*Dimensions.* Picking a cover means knowing which image is big enough to be one.
|
|
Reading a PNG header or a JPEG start-of-frame costs nothing and avoids pulling in
|
|
an imaging library (and its C dependencies) just to answer "is this wide?".
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import struct
|
|
|
|
# Types the EPUB writer will embed. SVG is deliberately absent: it can carry
|
|
# script and external references, and an image in an article body has no reason
|
|
# to need either.
|
|
MEDIA_TYPES = {
|
|
"image/jpeg": ".jpg",
|
|
"image/png": ".png",
|
|
"image/gif": ".gif",
|
|
"image/webp": ".webp",
|
|
}
|
|
|
|
_MEDIA_TYPE_ALIASES = {
|
|
"image/jpg": "image/jpeg",
|
|
"image/pjpeg": "image/jpeg",
|
|
"image/x-png": "image/png",
|
|
"image/x-gif": "image/gif",
|
|
}
|
|
|
|
|
|
def normalise_media_type(raw: str | None) -> str | None:
|
|
"""Map a Content-Type header onto a media type this server will embed."""
|
|
if not raw:
|
|
return None
|
|
# Strip parameters: "image/jpeg; charset=binary" is still a JPEG.
|
|
base = raw.split(";", 1)[0].strip().lower()
|
|
base = _MEDIA_TYPE_ALIASES.get(base, base)
|
|
return base if base in MEDIA_TYPES else None
|
|
|
|
|
|
def sniff_media_type(data: bytes) -> str | None:
|
|
"""Identify an image from its leading bytes, or None if unrecognised."""
|
|
if len(data) < 12:
|
|
return None
|
|
if data.startswith(b"\xff\xd8\xff"):
|
|
return "image/jpeg"
|
|
if data.startswith(b"\x89PNG\r\n\x1a\n"):
|
|
return "image/png"
|
|
if data.startswith((b"GIF87a", b"GIF89a")):
|
|
return "image/gif"
|
|
if data.startswith(b"RIFF") and data[8:12] == b"WEBP":
|
|
return "image/webp"
|
|
return None
|
|
|
|
|
|
def identify(data: bytes, declared: str | None) -> str | None:
|
|
"""Decide the media type for a fetched image.
|
|
|
|
The bytes win. A declared type is used only when the bytes are recognisable
|
|
as nothing else, and never to *override* a successful sniff -- otherwise a
|
|
mislabelled payload would produce an invalid EPUB manifest.
|
|
"""
|
|
sniffed = sniff_media_type(data)
|
|
if sniffed is not None:
|
|
return sniffed
|
|
return normalise_media_type(declared)
|
|
|
|
|
|
def dimensions(data: bytes) -> tuple[int, int] | None:
|
|
"""Return ``(width, height)`` in pixels, or None when it cannot be read.
|
|
|
|
Only the container headers are parsed: the value is used to decide whether an
|
|
image is a plausible cover, so "unknown" is a perfectly good answer.
|
|
"""
|
|
sniffed = sniff_media_type(data)
|
|
try:
|
|
if sniffed == "image/png":
|
|
return _png_dimensions(data)
|
|
if sniffed == "image/gif":
|
|
return _gif_dimensions(data)
|
|
if sniffed == "image/jpeg":
|
|
return _jpeg_dimensions(data)
|
|
if sniffed == "image/webp":
|
|
return _webp_dimensions(data)
|
|
except (struct.error, IndexError, ValueError):
|
|
return None
|
|
return None
|
|
|
|
|
|
def _png_dimensions(data: bytes) -> tuple[int, int] | None:
|
|
# IHDR is required to be the first chunk: 8 signature bytes, then length and
|
|
# type, so width and height sit at a fixed offset.
|
|
if len(data) < 24:
|
|
return None
|
|
width, height = struct.unpack(">II", data[16:24])
|
|
return (width, height) if width and height else None
|
|
|
|
|
|
def _gif_dimensions(data: bytes) -> tuple[int, int] | None:
|
|
if len(data) < 10:
|
|
return None
|
|
width, height = struct.unpack("<HH", data[6:10])
|
|
return (width, height) if width and height else None
|
|
|
|
|
|
def _webp_dimensions(data: bytes) -> tuple[int, int] | None:
|
|
if len(data) < 30:
|
|
return None
|
|
chunk = data[12:16]
|
|
if chunk == b"VP8X":
|
|
width = int.from_bytes(data[24:27], "little") + 1
|
|
height = int.from_bytes(data[27:30], "little") + 1
|
|
return (width, height)
|
|
if chunk == b"VP8 ":
|
|
# Lossy: dimensions are 14 bytes into the frame header, after the
|
|
# start code, with 14 bits of width and 14 of height.
|
|
if len(data) < 30:
|
|
return None
|
|
start = 26
|
|
width = int.from_bytes(data[start : start + 2], "little") & 0x3FFF
|
|
height = int.from_bytes(data[start + 2 : start + 4], "little") & 0x3FFF
|
|
return (width, height) if width and height else None
|
|
if chunk == b"VP8L":
|
|
bits = int.from_bytes(data[21:25], "little")
|
|
width = (bits & 0x3FFF) + 1
|
|
height = ((bits >> 14) & 0x3FFF) + 1
|
|
return (width, height)
|
|
return None
|
|
|
|
|
|
# JPEG start-of-frame markers, which carry the dimensions.
|
|
_SOF_MARKERS = frozenset(
|
|
{
|
|
0xC0,
|
|
0xC1,
|
|
0xC2,
|
|
0xC3,
|
|
0xC5,
|
|
0xC6,
|
|
0xC7,
|
|
0xC9,
|
|
0xCA,
|
|
0xCB,
|
|
0xCD,
|
|
0xCE,
|
|
0xCF,
|
|
}
|
|
)
|
|
|
|
|
|
def _jpeg_dimensions(data: bytes) -> tuple[int, int] | None:
|
|
"""Walk the JPEG segment chain to the start-of-frame marker.
|
|
|
|
A JPEG has no fixed header offset, so the segments have to be stepped over
|
|
until the frame header appears. This is bounded work: it stops at the first
|
|
frame marker, which always precedes the image data.
|
|
"""
|
|
index = 2 # skip the SOI marker (FF D8)
|
|
limit = len(data)
|
|
while index + 9 < limit:
|
|
if data[index] != 0xFF:
|
|
index += 1
|
|
continue
|
|
marker = data[index + 1]
|
|
if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
|
|
index += 2
|
|
continue
|
|
if marker == 0xDA: # start of scan: no frame header found
|
|
return None
|
|
length = struct.unpack(">H", data[index + 2 : index + 4])[0]
|
|
if length < 2:
|
|
return None
|
|
if marker in _SOF_MARKERS:
|
|
height, width = struct.unpack(">HH", data[index + 5 : index + 9])
|
|
return (width, height) if width and height else None
|
|
index += 2 + length
|
|
return None
|
|
|
|
|
|
def looks_like_a_cover(width: int, height: int) -> bool:
|
|
"""Whether an image is a plausible book cover.
|
|
|
|
A lead image is usually landscape and wide; a thumbnail, icon or tracking
|
|
pixel is not. The bar is deliberately low -- it only has to beat a blank
|
|
tile in a reader's library view.
|
|
"""
|
|
return width >= 400 and height >= 200
|