amos-abk 0.1.0__tar.gz

amos_abk-0.1.0/LICENSE.md

@@ -0,0 +1,7 @@
+# WTFPL + Warranty
+
+Licensed under the WTFPL with one additional clause:
+
+1. Don't blame me.
+
+Do whatever the fuck you want, just don't blame me.

amos_abk-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: amos_abk
+Version: 0.1.0
+Summary: Load AMOS banks in Python
+Author-email: Gareth Davidson <gaz@bitplane.net>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: Pillow
+Requires-Dist: pre-commit ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: coverage ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "dev"
+Requires-Dist: build ; extra == "dev"
+Requires-Dist: twine ; extra == "dev"
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: pydoc-markdown ; extra == "dev"
+Project-URL: Documentation, https://bitplane.net/dev/python/amos-abk/pydoc
+Project-URL: Homepage, https://bitplane.net/dev/python/amos-abk
+Project-URL: Repository, https://github.com/bitplane/amos-abk
+Provides-Extra: dev
+
+# amos-abk
+
+A Python library for loading AMOS `.abk` bank files from the Amiga.
+
+Parses the container format and three image bank types:
+
+* **Sprites** — hardware sprite images with hotspot and transparency
+* **Icons** — software bob images (same format as sprites)
+* **Pac.Pic.** — packed full-screen pictures with three-stream RLE compression
+
+Non-image banks (Music, Samples, Amal, Datas) are loaded as raw `DataBank`
+objects.
+
+## Links
+
+* [🏠 home](https://bitplane.net/dev/python/amos-abk)
+* [📚 pydoc](https://bitplane.net/dev/python/amos-abk/pydoc)
+* [🐍 pypi](https://pypi.org/project/amos-abk)
+* [🐱 github](https://github.com/bitplane/amos-abk)
+
+## Install
+
+```
+pip install amos-abk
+```
+
+## Library usage
+
+```python
+from amos_abk import load, parse_sprites, parse_packed_picture
+
+# Load a bank file
+abk = load("sprites.abk")
+print(abk)  # AbkFile([Sprites])
+
+# Parse sprites and convert to PIL Images
+sprites = parse_sprites(abk.banks[0].data)
+for i, sprite in enumerate(sprites):
+    sprite.to_image().save(f"sprite_{i}.png")
+
+# Parse a packed picture
+abk = load("picture.abk")
+pic = parse_packed_picture(abk.banks[0].data)
+pic.to_image().save("picture.png")
+
+# Access raw data
+print(pic.width, pic.height, pic.num_planes)
+print(pic.palette[:4])  # first 4 RGB tuples
+```
+
+## Pillow plugin
+
+`import amos_abk` registers a Pillow plugin, so you can open `.abk` files
+directly:
+
+```python
+from PIL import Image
+import amos_abk
+
+img = Image.open("sprites.abk")
+img.save("first_sprite.png")
+
+# Multi-frame: seek through all images in the file
+for i in range(img.n_frames):
+    img.seek(i)
+    img.save(f"frame_{i}.png")
+
+# The parsed AbkFile is available in metadata
+abk = img.info["abk"]
+print(abk.banks[0].name)
+```
+
+## Extract all images
+
+The `images()` function extracts every image from every bank in a file:
+
+```python
+import amos_abk
+
+# From a file path
+imgs = amos_abk.images("sprites.abk")
+for i, img in enumerate(imgs):
+    img.save(f"image_{i}.png")
+
+# Or from an already-loaded AbkFile
+abk = amos_abk.load("sprites.abk")
+imgs = amos_abk.images(abk)
+```
+
+## Format overview
+
+AMOS was a game-creation environment for the Amiga, released in 1990. It stored
+graphics and other resources in `.abk` memory bank files.
+
+### Bank container
+
+Each `.abk` file contains one or more banks, either bare (AmSp/AmIc magic) or
+wrapped in an AmBk header with a bank number, name, and memory type.
+
+### Sprite and icon banks
+
+Sprites and icons share the same format: a count, per-image headers (dimensions,
+bitplane count, hotspot), interleaved planar bitmap data, and a shared 32-entry
+12-bit Amiga palette.
+
+### Pac.Pic. banks
+
+Packed pictures are compressed full-screen Amiga images. They have two layers:
+
+1. **Screen header** (magic `0x12031990`) — dimensions, display window, flags,
+   and palette
+2. **Packed bitmap** (magic `0x06071963`) — three-stream RLE compression where
+   POINTS controls RLEDATA, and RLEDATA controls PICDATA
+
+## License
+
+WTFPL: do as you like, but don't blame me if it banks your sprites.
+

amos_abk-0.1.0/README.md

@@ -0,0 +1,117 @@
+# amos-abk
+
+A Python library for loading AMOS `.abk` bank files from the Amiga.
+
+Parses the container format and three image bank types:
+
+* **Sprites** — hardware sprite images with hotspot and transparency
+* **Icons** — software bob images (same format as sprites)
+* **Pac.Pic.** — packed full-screen pictures with three-stream RLE compression
+
+Non-image banks (Music, Samples, Amal, Datas) are loaded as raw `DataBank`
+objects.
+
+## Links
+
+* [🏠 home](https://bitplane.net/dev/python/amos-abk)
+* [📚 pydoc](https://bitplane.net/dev/python/amos-abk/pydoc)
+* [🐍 pypi](https://pypi.org/project/amos-abk)
+* [🐱 github](https://github.com/bitplane/amos-abk)
+
+## Install
+
+```
+pip install amos-abk
+```
+
+## Library usage
+
+```python
+from amos_abk import load, parse_sprites, parse_packed_picture
+
+# Load a bank file
+abk = load("sprites.abk")
+print(abk)  # AbkFile([Sprites])
+
+# Parse sprites and convert to PIL Images
+sprites = parse_sprites(abk.banks[0].data)
+for i, sprite in enumerate(sprites):
+    sprite.to_image().save(f"sprite_{i}.png")
+
+# Parse a packed picture
+abk = load("picture.abk")
+pic = parse_packed_picture(abk.banks[0].data)
+pic.to_image().save("picture.png")
+
+# Access raw data
+print(pic.width, pic.height, pic.num_planes)
+print(pic.palette[:4])  # first 4 RGB tuples
+```
+
+## Pillow plugin
+
+`import amos_abk` registers a Pillow plugin, so you can open `.abk` files
+directly:
+
+```python
+from PIL import Image
+import amos_abk
+
+img = Image.open("sprites.abk")
+img.save("first_sprite.png")
+
+# Multi-frame: seek through all images in the file
+for i in range(img.n_frames):
+    img.seek(i)
+    img.save(f"frame_{i}.png")
+
+# The parsed AbkFile is available in metadata
+abk = img.info["abk"]
+print(abk.banks[0].name)
+```
+
+## Extract all images
+
+The `images()` function extracts every image from every bank in a file:
+
+```python
+import amos_abk
+
+# From a file path
+imgs = amos_abk.images("sprites.abk")
+for i, img in enumerate(imgs):
+    img.save(f"image_{i}.png")
+
+# Or from an already-loaded AbkFile
+abk = amos_abk.load("sprites.abk")
+imgs = amos_abk.images(abk)
+```
+
+## Format overview
+
+AMOS was a game-creation environment for the Amiga, released in 1990. It stored
+graphics and other resources in `.abk` memory bank files.
+
+### Bank container
+
+Each `.abk` file contains one or more banks, either bare (AmSp/AmIc magic) or
+wrapped in an AmBk header with a bank number, name, and memory type.
+
+### Sprite and icon banks
+
+Sprites and icons share the same format: a count, per-image headers (dimensions,
+bitplane count, hotspot), interleaved planar bitmap data, and a shared 32-entry
+12-bit Amiga palette.
+
+### Pac.Pic. banks
+
+Packed pictures are compressed full-screen Amiga images. They have two layers:
+
+1. **Screen header** (magic `0x12031990`) — dimensions, display window, flags,
+   and palette
+2. **Packed bitmap** (magic `0x06071963`) — three-stream RLE compression where
+   POINTS controls RLEDATA, and RLEDATA controls PICDATA
+
+## License
+
+WTFPL: do as you like, but don't blame me if it banks your sprites.

amos_abk-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "amos_abk"
+description = "Load AMOS banks in Python"
+version = "0.1.0"
+authors = [
+    { name = "Gareth Davidson", email = "gaz@bitplane.net" }
+]
+readme = "README.md"
+requires-python = ">=3.10"
+
+dependencies = [
+    "Pillow",
+]
+
+[project.urls]
+Homepage = "https://bitplane.net/dev/python/amos-abk"
+Documentation = "https://bitplane.net/dev/python/amos-abk/pydoc"
+Repository = "https://github.com/bitplane/amos-abk"
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit",
+    "pytest",
+    "coverage",
+    "pytest-cov",
+    "build",
+    "twine",
+    "ruff",
+    "pydoc-markdown",
+]
+
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = ["flit_core >=3.2,<4"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.format]
+docstring-code-format = true

amos_abk-0.1.0/src/amos_abk/__init__.py

@@ -0,0 +1,15 @@
+from amos_abk.bank import AbkFile, DataBank, load
+from amos_abk.pacpic import PackedPicture, parse_packed_picture
+from amos_abk.pillow_plugin import images
+from amos_abk.sprite import Sprite, parse_sprites
+
+__all__ = [
+    "AbkFile",
+    "DataBank",
+    "PackedPicture",
+    "Sprite",
+    "images",
+    "load",
+    "parse_packed_picture",
+    "parse_sprites",
+]

amos_abk-0.1.0/src/amos_abk/bank.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+
+# Magic bytes for supported bank types
+MAGIC_AMBK = b"AmBk"
+MAGIC_AMSP = b"AmSp"
+MAGIC_AMIC = b"AmIc"
+
+# Known but unsupported magic bytes
+MAGIC_AMBS = b"AmBs"
+MAGIC_CRM2 = b"CrM2"
+MAGIC_IMP = b"IMP!"
+MAGIC_PPBK = b"PPbk"
+
+# Conventional bank numbers for bare sprite/icon files
+SPRITE_BANK_NUMBER = 1
+ICON_BANK_NUMBER = 2
+
+# AmBk header: magic(4) + bank_num(2) + mem_type(2) + length(4) + name(8) = 20
+AMBK_HEADER_SIZE = 20
+# The length field counts from byte 12 onward (name + data), so
+# the fixed prefix not counted is magic(4) + bank_num(2) + mem_type(2) + length(4) = 12
+AMBK_PREFIX_SIZE = 12
+
+LENGTH_MASK = 0x0FFFFFFF
+FLAGS_MASK = 0xF0000000
+
+
+@dataclass
+class DataBank:
+    """A single AMOS memory bank."""
+
+    number: int
+    name: str
+    memory_type: int
+    flags: int
+    data: bytes
+
+
+class AbkFile:
+    """An AMOS bank file containing one or more banks."""
+
+    def __init__(self, banks: list[DataBank]):
+        self.banks = banks
+
+    def __repr__(self) -> str:
+        bank_names = ", ".join(b.name for b in self.banks)
+        return f"AbkFile([{bank_names}])"
+
+
+def _read_ambk_bank(stream: BytesIO) -> DataBank:
+    """Read a single AmBk-wrapped bank from the stream."""
+    header = stream.read(AMBK_HEADER_SIZE)
+    if len(header) < AMBK_HEADER_SIZE:
+        raise ValueError(f"Truncated AmBk header: expected {AMBK_HEADER_SIZE} bytes, got {len(header)}")
+
+    magic = header[0:4]
+    if magic != MAGIC_AMBK:
+        raise ValueError(f"Expected AmBk magic, got {magic!r}")
+
+    bank_num, mem_type, length_raw = struct.unpack_from(">HHI", header, 4)
+    name = header[12:20].decode("ascii", errors="replace").rstrip()
+
+    flags = length_raw & FLAGS_MASK
+    data_length = (length_raw & LENGTH_MASK) - 8  # subtract name field (8 bytes)
+
+    if data_length < 0:
+        raise ValueError(f"Invalid bank length: {length_raw:#x} (data_length={data_length})")
+
+    data = stream.read(data_length)
+    if len(data) < data_length:
+        raise ValueError(f"Truncated bank data for '{name}': expected {data_length} bytes, got {len(data)}")
+
+    return DataBank(
+        number=bank_num,
+        name=name,
+        memory_type=mem_type,
+        flags=flags,
+        data=data,
+    )
+
+
+def _read_bare_bank(stream: BytesIO, magic: bytes) -> DataBank:
+    """Read a bare AmSp or AmIc bank (no AmBk wrapper)."""
+    data = stream.read()
+
+    if magic == MAGIC_AMSP:
+        return DataBank(number=SPRITE_BANK_NUMBER, name="Sprites", memory_type=0, flags=0, data=data)
+
+    return DataBank(number=ICON_BANK_NUMBER, name="Icons", memory_type=0, flags=0, data=data)
+
+
+def load(source: str | Path | BytesIO) -> AbkFile:
+    """Load an AMOS bank file.
+
+    Args:
+        source: file path (str or Path) or a readable BytesIO stream.
+
+    Returns:
+        An AbkFile containing the parsed banks.
+    """
+    if isinstance(source, (str, Path)):
+        with open(source, "rb") as f:
+            return _load_stream(BytesIO(f.read()))
+
+    return _load_stream(source)
+
+
+def _load_stream(stream: BytesIO) -> AbkFile:
+    """Parse banks from a byte stream."""
+    magic = stream.read(4)
+    if len(magic) < 4:
+        raise ValueError(f"File too short: expected at least 4 bytes, got {len(magic)}")
+
+    if magic in (MAGIC_AMBS, MAGIC_CRM2, MAGIC_IMP, MAGIC_PPBK):
+        kind = magic.decode("ascii", errors="replace")
+        raise ValueError(f"Unsupported format: {kind} (not a bank file)")
+
+    if magic in (MAGIC_AMSP, MAGIC_AMIC):
+        bank = _read_bare_bank(stream, magic)
+        return AbkFile([bank])
+
+    if magic == MAGIC_AMBK:
+        stream.seek(0)
+        banks = []
+        while True:
+            banks.append(_read_ambk_bank(stream))
+            next_magic = stream.read(4)
+            if len(next_magic) < 4:
+                break
+            if next_magic != MAGIC_AMBK:
+                raise ValueError(f"Expected AmBk magic at offset {stream.tell() - 4}, got {next_magic!r}")
+            stream.seek(stream.tell() - 4)
+        return AbkFile(banks)
+
+    raise ValueError(f"Unknown magic: {magic!r}")

amos_abk-0.1.0/src/amos_abk/pacpic.py

@@ -0,0 +1,213 @@
+"""Parser for AMOS Pac.Pic. (Packed Picture) banks.
+
+A Pac.Pic. bank contains a compressed full-screen Amiga picture with two layers:
+1. A screen header (90 bytes, magic 0x12031990) with dimensions and palette
+2. A packed bitmap (magic 0x06071963) using three-stream RLE compression
+
+Reference: https://www.exotica.org.uk/wiki/AMOS_Pac.Pic._format
+Reference: https://github.com/kyz/amostools (dumpamos.c)
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from PIL import Image
+
+from amos_abk.planar import indexed_to_rgb, indexed_to_rgba, planar_to_indexed
+from amos_abk.sprite import _parse_palette
+
+SCREEN_HEADER_MAGIC = 0x12031990
+SCREEN_HEADER_MAGIC_ALT1 = 0x00031990
+SCREEN_HEADER_MAGIC_ALT2 = 0x12030090
+PACKED_BITMAP_MAGIC = 0x06071963
+PACKED_BITMAP_MAGIC_ALT = 0x06070063
+
+SCREEN_HEADER_SIZE = 90
+
+
+@dataclass
+class PackedPicture:
+    """A decompressed packed picture from an AMOS Pac.Pic. bank."""
+
+    width: int
+    height: int
+    num_planes: int
+    display_width: int
+    display_height: int
+    flags: int
+    palette: list[tuple[int, int, int]]
+    planes: list[bytes]
+
+    @property
+    def num_colors(self) -> int:
+        return 1 << self.num_planes
+
+    def to_indexed(self) -> bytes:
+        """Convert planar data to chunky indexed pixels (1 byte per pixel)."""
+        return planar_to_indexed(self.planes, self.width, self.height)
+
+    def to_rgb(self) -> bytes:
+        """Convert to RGB pixel data (3 bytes per pixel)."""
+        return indexed_to_rgb(self.to_indexed(), self.palette)
+
+    def to_rgba(self) -> bytes:
+        """Convert to RGBA pixel data (4 bytes per pixel).
+
+        Palette index 0 is treated as transparent.
+        """
+        return indexed_to_rgba(self.to_indexed(), self.palette)
+
+    def to_image(self) -> Image.Image:
+        """Convert to a PIL Image (RGB)."""
+        return Image.frombytes("RGB", (self.width, self.height), self.to_rgb())
+
+
+def _decompress_bitmap(data: bytes, packed_offset: int) -> tuple[list[bytes], int, int, int]:
+    """Decompress a packed bitmap from three interleaved RLE streams.
+
+    The three streams are:
+    - PICDATA: the actual pixel bytes
+    - RLEDATA: 1 bit per output byte; bit=1 means read new PICDATA byte, 0=repeat
+    - POINTS: 1 bit per RLEDATA byte; bit=1 means read new RLEDATA byte, 0=repeat
+
+    Args:
+        data: raw data containing the packed bitmap.
+        packed_offset: offset to the packed bitmap header (0x06071963 magic).
+
+    Returns:
+        (planes, width_pixels, height, num_planes) where planes is a list of
+        bytes objects, one per bitplane, in row-major order.
+    """
+    magic = struct.unpack_from(">I", data, packed_offset)[0]
+    if magic not in (PACKED_BITMAP_MAGIC, PACKED_BITMAP_MAGIC_ALT):
+        raise ValueError(f"Bad packed bitmap magic: 0x{magic:08x}")
+
+    (x_offset, y_offset, width_bytes, lumps, lump_height, num_planes, rledata_offset, points_offset) = (
+        struct.unpack_from(">HHHHHHII", data, packed_offset + 4)
+    )
+
+    height = lumps * lump_height
+    width_pixels = width_bytes * 8
+
+    # Stream positions (offsets are relative to packed bitmap header start)
+    picdata = memoryview(data)[packed_offset + 24 :]
+    rledata = memoryview(data)[packed_offset + rledata_offset :]
+    points = memoryview(data)[packed_offset + points_offset :]
+
+    # Initialise streams: first picdata and rledata bytes are read unconditionally
+    pic_pos = 0
+    rle_pos = 0
+    pts_pos = 0
+
+    picbyte = picdata[pic_pos]
+    pic_pos += 1
+
+    rlebyte = rledata[rle_pos]
+    rle_pos += 1
+
+    # Check first points bit (MSB); if set, read another rledata byte
+    rbit = 7  # current bit position in rlebyte (MSB first)
+    rrbit = 6  # current bit position in points byte (bit 7 already checked)
+    if points[pts_pos] & 0x80:
+        rlebyte = rledata[rle_pos]
+        rle_pos += 1
+
+    # Allocate output plane buffers
+    plane_size = width_bytes * height
+    plane_bufs = [bytearray(plane_size) for _ in range(num_planes)]
+
+    # Decompress: iterate in plane/lump/column/row order
+    for plane_idx in range(num_planes):
+        for lump_idx in range(lumps):
+            for col in range(width_bytes):
+                for row in range(lump_height):
+                    # Check rlebyte bit to decide whether to read new picdata
+                    if rlebyte & (1 << rbit):
+                        picbyte = picdata[pic_pos]
+                        pic_pos += 1
+                    rbit -= 1
+
+                    # Write output byte
+                    screen_row = lump_idx * lump_height + row
+                    plane_bufs[plane_idx][screen_row * width_bytes + col] = picbyte
+
+                    # When rlebyte is exhausted (8 bits used), check points
+                    if rbit < 0:
+                        rbit = 7
+                        if points[pts_pos] & (1 << rrbit):
+                            rlebyte = rledata[rle_pos]
+                            rle_pos += 1
+                        rrbit -= 1
+                        if rrbit < 0:
+                            rrbit = 7
+                            pts_pos += 1
+
+    return [bytes(p) for p in plane_bufs], width_pixels, height, num_planes
+
+
+def parse_packed_picture(data: bytes) -> PackedPicture:
+    """Parse a Pac.Pic. bank's raw data.
+
+    Args:
+        data: the raw bank data (after AmBk header). May start with either
+              a screen header (0x12031990) or a bare packed bitmap (0x06071963).
+
+    Returns:
+        A PackedPicture with decompressed bitplane data.
+    """
+    if len(data) < 24:
+        raise ValueError(f"Pac.Pic. data too short: {len(data)} bytes")
+
+    magic = struct.unpack_from(">I", data, 0)[0]
+
+    if magic in (SCREEN_HEADER_MAGIC, SCREEN_HEADER_MAGIC_ALT1, SCREEN_HEADER_MAGIC_ALT2):
+        if len(data) < SCREEN_HEADER_SIZE + 24:
+            raise ValueError(f"Pac.Pic. data too short for screen header: {len(data)} bytes")
+
+        screen_width, screen_height, flags, _unknown = struct.unpack_from(">HHHH", data, 4)
+        display_width, display_height = struct.unpack_from(">HH", data, 12)
+        num_planes = struct.unpack_from(">H", data, 24)[0]
+        palette = _parse_palette(data, 26)
+        packed_offset = SCREEN_HEADER_SIZE
+
+    elif magic in (PACKED_BITMAP_MAGIC, PACKED_BITMAP_MAGIC_ALT):
+        # Bare packed bitmap without screen header
+        packed_offset = 0
+        num_planes_from_header = struct.unpack_from(">H", data, 14)[0]
+        palette = [(((i & 0xF) * 0x111 >> 8) & 0xF) * 17 for i in range(32)]
+        # Generate a greyscale fallback palette
+        palette = [((i * 17) % 256, (i * 17) % 256, (i * 17) % 256) for i in range(32)]
+        screen_width = 0
+        screen_height = 0
+        display_width = 0
+        display_height = 0
+        flags = 0
+        num_planes = num_planes_from_header
+
+    else:
+        raise ValueError(f"Unknown Pac.Pic. magic: 0x{magic:08x}")
+
+    planes, width_pixels, height, num_planes = _decompress_bitmap(data, packed_offset)
+
+    # Use screen header dimensions if available, otherwise derive from packed bitmap
+    if screen_width == 0:
+        screen_width = width_pixels
+    if screen_height == 0:
+        screen_height = height
+    if display_width == 0:
+        display_width = width_pixels
+    if display_height == 0:
+        display_height = height
+
+    return PackedPicture(
+        width=width_pixels,
+        height=height,
+        num_planes=num_planes,
+        display_width=display_width,
+        display_height=display_height,
+        flags=flags,
+        palette=palette,
+        planes=planes,
+    )

amos_abk-0.1.0/src/amos_abk/pillow_plugin.py

@@ -0,0 +1,101 @@
+"""Pillow plugin for AMOS .abk bank files.
+
+Registers the ABK format so that ``Image.open("file.abk")`` works
+after ``import amos_abk``.
+
+Sprite and icon banks produce one frame per image (RGBA, index 0 transparent).
+Pac.Pic. banks produce one frame per picture (RGBA).
+Non-image banks (music, samples, amal, data) are skipped.
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+
+from PIL import Image, ImageFile
+
+from amos_abk.bank import AbkFile
+from amos_abk.bank import load as _load_abk
+from amos_abk.pacpic import parse_packed_picture
+from amos_abk.sprite import parse_sprites
+
+# Bank names that contain parseable image data
+_SPRITE_NAMES = {"Sprites", "Icons"}
+
+
+def _accept(prefix):
+    return prefix[:4] in (b"AmBk", b"AmSp", b"AmIc")
+
+
+def _build_frames(abk: AbkFile) -> list[Image.Image]:
+    """Extract all images from all banks, in bank order."""
+    frames = []
+    for bank in abk.banks:
+        if bank.name in _SPRITE_NAMES:
+            for sprite in parse_sprites(bank.data):
+                frames.append(sprite.to_image())
+        elif bank.name == "Pac.Pic.":
+            pic = parse_packed_picture(bank.data)
+            frames.append(pic.to_image().convert("RGBA"))
+    return frames
+
+
+def images(source) -> list[Image.Image]:
+    """Extract all images from an ABK file.
+
+    Args:
+        source: file path (str/Path), BytesIO, or an already-loaded AbkFile.
+
+    Returns:
+        List of PIL Images (RGBA). Sprites and icons get one image each,
+        packed pictures get one image. Non-image banks are skipped.
+    """
+    if isinstance(source, AbkFile):
+        return _build_frames(source)
+    return _build_frames(_load_abk(source))
+
+
+class AmosAbkFile(ImageFile.ImageFile):
+    format = "ABK"
+    format_description = "AMOS Memory Bank"
+
+    def _open(self):
+        self.fp.seek(0)
+        abk = _load_abk(BytesIO(self.fp.read()))
+        self.info["abk"] = abk
+
+        self._frames = _build_frames(abk)
+        if not self._frames:
+            raise SyntaxError("No image data in ABK file")
+
+        self._frame = 0
+        self._n_frames = len(self._frames)
+        self.is_animated = self._n_frames > 1
+        first = self._frames[0]
+        self._size = first.size
+        self._mode = first.mode
+
+    @property
+    def n_frames(self):
+        return self._n_frames
+
+    def seek(self, frame):
+        if not self._seek_check(frame):
+            return
+        self._frame = frame
+
+    def tell(self):
+        return self._frame
+
+    def load(self):
+        if self._frame >= len(self._frames):
+            raise EOFError("no more frames")
+        im = self._frames[self._frame]
+        self.im = im.im.copy()
+        self._size = im.size
+        self._mode = im.mode
+        return self.im
+
+
+Image.register_open(AmosAbkFile.format, AmosAbkFile, _accept)
+Image.register_extension(AmosAbkFile.format, ".abk")

amos_abk-0.1.0/src/amos_abk/planar.py

@@ -0,0 +1,60 @@
+"""Shared Amiga planar bitmap conversion utilities."""
+
+from __future__ import annotations
+
+
+def planar_to_indexed(planes: list[bytes], width: int, height: int) -> bytes:
+    """Convert planar bitplane data to chunky indexed pixels.
+
+    Args:
+        planes: list of bytearrays/bytes, one per bitplane.
+        width: image width in pixels.
+        height: image height in pixels.
+
+    Returns:
+        One byte per pixel, each byte being a palette index.
+    """
+    width_bytes = (width + 7) // 8
+    num_planes = len(planes)
+    result = bytearray(width * height)
+
+    for y in range(height):
+        for x in range(width):
+            byte_idx = y * width_bytes + x // 8
+            bit = 7 - (x % 8)
+            index = 0
+            for plane_num in range(num_planes):
+                if planes[plane_num][byte_idx] & (1 << bit):
+                    index |= 1 << plane_num
+            result[y * width + x] = index
+
+    return bytes(result)
+
+
+def indexed_to_rgb(indexed: bytes, palette: list[tuple[int, int, int]]) -> bytes:
+    """Convert indexed pixel data to RGB (3 bytes per pixel)."""
+    result = bytearray(len(indexed) * 3)
+    for i, idx in enumerate(indexed):
+        r, g, b = palette[idx] if idx < len(palette) else (0, 0, 0)
+        result[i * 3] = r
+        result[i * 3 + 1] = g
+        result[i * 3 + 2] = b
+    return bytes(result)
+
+
+def indexed_to_rgba(indexed: bytes, palette: list[tuple[int, int, int]]) -> bytes:
+    """Convert indexed pixel data to RGBA (4 bytes per pixel).
+
+    Palette index 0 is treated as transparent.
+    """
+    result = bytearray(len(indexed) * 4)
+    for i, idx in enumerate(indexed):
+        if idx == 0:
+            result[i * 4 : i * 4 + 4] = b"\x00\x00\x00\x00"
+        else:
+            r, g, b = palette[idx] if idx < len(palette) else (0, 0, 0)
+            result[i * 4] = r
+            result[i * 4 + 1] = g
+            result[i * 4 + 2] = b
+            result[i * 4 + 3] = 255
+    return bytes(result)

amos_abk-0.1.0/src/amos_abk/sprite.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from PIL import Image
+
+from amos_abk.planar import indexed_to_rgb, indexed_to_rgba, planar_to_indexed
+
+
+@dataclass
+class Sprite:
+    """A single sprite or icon image from an AMOS bank."""
+
+    width: int
+    height: int
+    num_planes: int
+    hotspot_x: int
+    hotspot_y: int
+    palette: list[tuple[int, int, int]]
+    planes: list[bytes]
+
+    @property
+    def num_colors(self) -> int:
+        return 1 << self.num_planes
+
+    def to_indexed(self) -> bytes:
+        """Convert planar data to chunky indexed pixels.
+
+        Returns one byte per pixel, each byte being a palette index.
+        """
+        return planar_to_indexed(self.planes, self.width, self.height)
+
+    def to_rgb(self) -> bytes:
+        """Convert to RGB pixel data (3 bytes per pixel)."""
+        return indexed_to_rgb(self.to_indexed(), self.palette)
+
+    def to_rgba(self) -> bytes:
+        """Convert to RGBA pixel data (4 bytes per pixel).
+
+        Palette index 0 is treated as transparent.
+        """
+        return indexed_to_rgba(self.to_indexed(), self.palette)
+
+    def to_image(self) -> Image.Image:
+        """Convert to a PIL Image (RGBA, palette index 0 is transparent)."""
+        return Image.frombytes("RGBA", (self.width, self.height), self.to_rgba())
+
+
+def _parse_palette(data: bytes, offset: int) -> list[tuple[int, int, int]]:
+    """Parse a 32-entry Amiga 12-bit palette."""
+    palette = []
+    for i in range(32):
+        color = struct.unpack_from(">H", data, offset + i * 2)[0]
+        r = ((color >> 8) & 0xF) * 17
+        g = ((color >> 4) & 0xF) * 17
+        b = (color & 0xF) * 17
+        palette.append((r, g, b))
+    return palette
+
+
+def parse_sprites(data: bytes) -> list[Sprite]:
+    """Parse sprite or icon image data from a bank's raw data.
+
+    Args:
+        data: the raw bank data (after magic for bare files, after AmBk header
+              for wrapped files). Starts with the u16 image count.
+
+    Returns:
+        List of Sprite objects.
+    """
+    if len(data) < 2:
+        raise ValueError(f"Sprite data too short: {len(data)} bytes")
+
+    num_images = struct.unpack_from(">H", data, 0)[0]
+    if num_images == 0:
+        return []
+
+    # Palette is at the end: 32 entries * 2 bytes = 64 bytes
+    palette = _parse_palette(data, len(data) - 64)
+
+    sprites = []
+    offset = 2
+    for i in range(num_images):
+        if offset + 10 > len(data):
+            raise ValueError(f"Truncated sprite header at image {i}, offset {offset}")
+
+        w_words, h, num_planes, hx, hy = struct.unpack_from(">HHHHH", data, offset)
+        offset += 10
+
+        width = w_words * 16
+        plane_size = w_words * 2 * h  # bytes per bitplane
+        total_size = plane_size * num_planes
+
+        if offset + total_size > len(data):
+            raise ValueError(
+                f"Truncated sprite data at image {i}: need {total_size} bytes at offset {offset}, "
+                f"but only {len(data) - offset} remain"
+            )
+
+        planes = []
+        for p in range(num_planes):
+            plane_start = offset + p * plane_size
+            planes.append(data[plane_start : plane_start + plane_size])
+        offset += total_size
+
+        # Mask out flip flags from hotspot_x (bits 14-15)
+        hotspot_x = hx & 0x3FFF
+        hotspot_y = hy
+
+        sprites.append(
+            Sprite(
+                width=width,
+                height=h,
+                num_planes=num_planes,
+                hotspot_x=hotspot_x,
+                hotspot_y=hotspot_y,
+                palette=palette,
+                planes=planes,
+            )
+        )
+
+    return sprites