Initial commit
This commit is contained in:
193
app/images.py
Normal file
193
app/images.py
Normal file
@@ -0,0 +1,193 @@
|
||||
"""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
|
||||
Reference in New Issue
Block a user