tilepack 0.1.0__tar.gz

tilepack-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Lint
+        run: uv run ruff check tilepack/ tests/
+      - name: Format check
+        run: uv run ruff format --check tilepack/ tests/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Tests
+        run: uv run pytest tests/ -v
+
+  minimum:
+    name: test (minimum versions)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+      - name: Install minimum dependencies
+        run: uv sync --group dev --resolution lowest-direct
+      - name: Tests
+        run: uv run pytest tests/ -v
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.head.label || github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

tilepack-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tilepack-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Test data
+*_TMS*/
+*.zip
+
+# Generated archives
+*.mbtiles
+*.pmtiles
+
+# Tile images
+*.png
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.venv/
+

tilepack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ashwin Nair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tilepack-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: tilepack
+Version: 0.1.0
+Summary: Convert TMS tile folders to MBTiles/PMTiles and serve them as TMS/WMTS endpoints
+Author-email: Ashwin Nair <ashnair0007@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pmtiles>=3.4
+Requires-Dist: uvicorn[standard]>=0.29
+Description-Content-Type: text/markdown
+
+# tilepack
+
+[![CI](https://github.com/ashnair1/tilepack/actions/workflows/ci.yml/badge.svg)](https://github.com/ashnair1/tilepack/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tilepack)](https://pypi.org/project/tilepack/)
+[![Python](https://img.shields.io/pypi/pyversions/tilepack)](https://pypi.org/project/tilepack/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Pack raster tile folders (TMS or XYZ) into single-file archives (MBTiles / PMTiles) and serve them as TMS and WMTS endpoints over HTTP.
+
+## Why
+
+Raster tile folders contain thousands of small PNG files in deeply nested `z/x/y` directories. This makes them slow to copy, hard to manage, and fragile to transfer. Tilepack solves this by packing tiles into a single archive file while still exposing standard TMS and WMTS HTTP endpoints that clients like QGIS and CesiumForUnreal can consume directly.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install tilepack
+```
+
+For development:
+
+```bash
+git clone https://github.com/ashnair1/tilepack.git
+cd tilepack
+uv sync --group dev
+```
+
+## Usage
+
+### Verify a tile folder
+
+Scan a tile folder and report zoom levels, tile counts, format, and detected Y-axis scheme (TMS vs XYZ).
+
+```bash
+tilepack verify ./path/to/tiles
+```
+
+### Convert to archive
+
+The output format is inferred from the file extension. The input tile scheme (TMS or XYZ) is auto-detected, or can be specified explicitly.
+
+```bash
+# Auto-detect input scheme
+tilepack convert ./path/to/tiles output.mbtiles
+tilepack convert ./path/to/tiles output.pmtiles
+
+# Specify input scheme explicitly
+tilepack convert ./path/to/tiles output.mbtiles --scheme xyz
+```
+
+### Serve as TMS + WMTS endpoint
+
+Start a local HTTP server exposing both TMS and OGC WMTS 1.0.0 endpoints from an archive file.
+
+```bash
+tilepack serve output.mbtiles --port 8000
+tilepack serve output.pmtiles --port 8000
+```
+
+**TMS endpoints:**
+- `http://localhost:8000/tilemapresource.xml`
+- `http://localhost:8000/{z}/{x}/{y}.png`
+
+**WMTS endpoints:**
+- `http://localhost:8000/WMTSCapabilities.xml` — GetCapabilities
+- `http://localhost:8000/wmts/{Layer}/{TileMatrixSet}/{z}/{row}/{col}.png` — RESTful tiles
+- `http://localhost:8000/wmts?Service=WMTS&Request=GetTile&...` — KVP tiles
+
+To load in QGIS: **Layer > Add WMS/WMTS Layer > New**, set URL to `http://localhost:8000/WMTSCapabilities.xml`, then Connect and Add.
+
+### Validate correctness
+
+Randomly sample tiles from the original folder, fetch them from the running server, and verify byte-exact matches.
+
+```bash
+# Start the server in one terminal, then in another:
+tilepack selftest ./path/to/tiles --base-url http://127.0.0.1:8000 --samples 200
+```
+
+## MBTiles vs PMTiles
+
+| | MBTiles | PMTiles |
+|---|---------|---------|
+| Format | SQLite database | Cloud-optimised archive (Hilbert-curve index) |
+| File count | 1 | 1 |
+| Needs a tile server | Yes | No (supports HTTP range requests) |
+| Best for | Local / on-prem serving | Cloud storage (S3, Azure Blob, GCS) |
+
+**Use MBTiles** for local or on-prem serving (e.g. feeding CesiumForUnreal on the same machine or network). It's a SQLite file with fast tile lookups and no coordinate flipping at read time.
+
+**Use PMTiles** if you plan to host tiles in cloud storage. PMTiles can be served directly from a bucket via HTTP range requests with no tile server needed. However, TMS clients like CesiumForUnreal cannot consume PMTiles directly — they still need a server translating to TMS endpoints.
+
+**Either format** works identically when served through `tilepack serve` — clients see the same TMS and WMTS endpoints regardless of the backing archive.
+
+## License
+
+MIT

tilepack-0.1.0/README.md

@@ -0,0 +1,99 @@
+# tilepack
+
+[![CI](https://github.com/ashnair1/tilepack/actions/workflows/ci.yml/badge.svg)](https://github.com/ashnair1/tilepack/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tilepack)](https://pypi.org/project/tilepack/)
+[![Python](https://img.shields.io/pypi/pyversions/tilepack)](https://pypi.org/project/tilepack/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Pack raster tile folders (TMS or XYZ) into single-file archives (MBTiles / PMTiles) and serve them as TMS and WMTS endpoints over HTTP.
+
+## Why
+
+Raster tile folders contain thousands of small PNG files in deeply nested `z/x/y` directories. This makes them slow to copy, hard to manage, and fragile to transfer. Tilepack solves this by packing tiles into a single archive file while still exposing standard TMS and WMTS HTTP endpoints that clients like QGIS and CesiumForUnreal can consume directly.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install tilepack
+```
+
+For development:
+
+```bash
+git clone https://github.com/ashnair1/tilepack.git
+cd tilepack
+uv sync --group dev
+```
+
+## Usage
+
+### Verify a tile folder
+
+Scan a tile folder and report zoom levels, tile counts, format, and detected Y-axis scheme (TMS vs XYZ).
+
+```bash
+tilepack verify ./path/to/tiles
+```
+
+### Convert to archive
+
+The output format is inferred from the file extension. The input tile scheme (TMS or XYZ) is auto-detected, or can be specified explicitly.
+
+```bash
+# Auto-detect input scheme
+tilepack convert ./path/to/tiles output.mbtiles
+tilepack convert ./path/to/tiles output.pmtiles
+
+# Specify input scheme explicitly
+tilepack convert ./path/to/tiles output.mbtiles --scheme xyz
+```
+
+### Serve as TMS + WMTS endpoint
+
+Start a local HTTP server exposing both TMS and OGC WMTS 1.0.0 endpoints from an archive file.
+
+```bash
+tilepack serve output.mbtiles --port 8000
+tilepack serve output.pmtiles --port 8000
+```
+
+**TMS endpoints:**
+- `http://localhost:8000/tilemapresource.xml`
+- `http://localhost:8000/{z}/{x}/{y}.png`
+
+**WMTS endpoints:**
+- `http://localhost:8000/WMTSCapabilities.xml` — GetCapabilities
+- `http://localhost:8000/wmts/{Layer}/{TileMatrixSet}/{z}/{row}/{col}.png` — RESTful tiles
+- `http://localhost:8000/wmts?Service=WMTS&Request=GetTile&...` — KVP tiles
+
+To load in QGIS: **Layer > Add WMS/WMTS Layer > New**, set URL to `http://localhost:8000/WMTSCapabilities.xml`, then Connect and Add.
+
+### Validate correctness
+
+Randomly sample tiles from the original folder, fetch them from the running server, and verify byte-exact matches.
+
+```bash
+# Start the server in one terminal, then in another:
+tilepack selftest ./path/to/tiles --base-url http://127.0.0.1:8000 --samples 200
+```
+
+## MBTiles vs PMTiles
+
+| | MBTiles | PMTiles |
+|---|---------|---------|
+| Format | SQLite database | Cloud-optimised archive (Hilbert-curve index) |
+| File count | 1 | 1 |
+| Needs a tile server | Yes | No (supports HTTP range requests) |
+| Best for | Local / on-prem serving | Cloud storage (S3, Azure Blob, GCS) |
+
+**Use MBTiles** for local or on-prem serving (e.g. feeding CesiumForUnreal on the same machine or network). It's a SQLite file with fast tile lookups and no coordinate flipping at read time.
+
+**Use PMTiles** if you plan to host tiles in cloud storage. PMTiles can be served directly from a bucket via HTTP range requests with no tile server needed. However, TMS clients like CesiumForUnreal cannot consume PMTiles directly — they still need a server translating to TMS endpoints.
+
+**Either format** works identically when served through `tilepack serve` — clients see the same TMS and WMTS endpoints regardless of the backing archive.
+
+## License
+
+MIT

tilepack-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "tilepack"
+version = "0.1.0"
+description = "Convert TMS tile folders to MBTiles/PMTiles and serve them as TMS/WMTS endpoints"
+authors = [{ name = "Ashwin Nair", email = "ashnair0007@gmail.com" }]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+dependencies = [
+    "click>=8.0",
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "pmtiles>=3.4",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+tilepack = "tilepack.cli:cli"
+
+[dependency-groups]
+dev = ["ruff>=0.9", "ty>=0.0.2", "pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"tilepack/tms_utils.py" = ["E501"]  # XML template strings

tilepack-0.1.0/tests/conftest.py

@@ -0,0 +1,92 @@
+"""Shared test fixtures for tilepack tests."""
+
+from pathlib import Path
+
+import pytest
+
+from tilepack.convert import run_convert
+from tilepack.tms_utils import PNG_SIGNATURE
+
+# Minimal valid PNG: 1x1 pixel, 8-bit RGBA
+# PNG signature + IHDR + IDAT + IEND (the smallest valid PNG possible)
+_MINIMAL_PNG = (
+    PNG_SIGNATURE
+    + b"\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde"
+    + b"\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05\x18\xd8N"
+    + b"\x00\x00\x00\x00IEND\xaeB`\x82"
+)
+
+
+def _write_tile(root: Path, z: int, x: int, y: int) -> Path:
+    """Write a minimal PNG tile at root/z/x/y.png."""
+    tile_dir = root / str(z) / str(x)
+    tile_dir.mkdir(parents=True, exist_ok=True)
+    tile_path = tile_dir / f"{y}.png"
+    tile_path.write_bytes(_MINIMAL_PNG)
+    return tile_path
+
+
+@pytest.fixture()
+def tiny_tms_dir(tmp_path: Path) -> Path:
+    """Create a minimal TMS tile directory (y=0 at south).
+
+    Uses z=1 with a tile in the northern hemisphere:
+      - TMS y=1 (north half), x=0 (western half)
+      - TMS y=1, x=1 (eastern half)
+
+    And z=2 with a couple tiles:
+      - TMS y=2, x=0
+      - TMS y=3, x=1
+    """
+    root = tmp_path / "tms_tiles"
+    root.mkdir()
+
+    # z=1: 2x2 grid. TMS y=1 = northern hemisphere
+    _write_tile(root, 1, 0, 1)
+    _write_tile(root, 1, 1, 1)
+
+    # z=2: 4x4 grid. TMS y=2,3 = northern hemisphere
+    _write_tile(root, 2, 0, 2)
+    _write_tile(root, 2, 1, 3)
+
+    return root
+
+
+@pytest.fixture()
+def tiny_xyz_dir(tmp_path: Path) -> Path:
+    """Create a minimal XYZ tile directory (y=0 at north).
+
+    Equivalent geographic area to tiny_tms_dir but with flipped y values.
+    z=1: XYZ y=0 (north half) = TMS y=1
+    z=2: XYZ y=1 (TMS y=2), XYZ y=0 (TMS y=3)
+    """
+    root = tmp_path / "xyz_tiles"
+    root.mkdir()
+
+    # z=1: XYZ y=0 = TMS y=1 (northern hemisphere)
+    _write_tile(root, 1, 0, 0)
+    _write_tile(root, 1, 1, 0)
+
+    # z=2: XYZ y=1 = TMS y=2, XYZ y=0 = TMS y=3
+    _write_tile(root, 2, 0, 1)
+    _write_tile(root, 2, 1, 0)
+
+    return root
+
+
+@pytest.fixture()
+def tiny_mbtiles(tmp_path: Path, tiny_tms_dir: Path) -> Path:
+    """Convert tiny_tms_dir to a small .mbtiles file."""
+
+    out = tmp_path / "test.mbtiles"
+    run_convert(str(tiny_tms_dir), str(out), scheme="tms")
+    return out
+
+
+@pytest.fixture()
+def tiny_pmtiles(tmp_path: Path, tiny_tms_dir: Path) -> Path:
+    """Convert tiny_tms_dir to a small .pmtiles file."""
+
+    out = tmp_path / "test.pmtiles"
+    run_convert(str(tiny_tms_dir), str(out), scheme="tms")
+    return out

tilepack-0.1.0/tests/test_cli.py

@@ -0,0 +1,46 @@
+"""Tests for tilepack.cli."""
+
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from tilepack.cli import cli
+
+
+class TestVerifyCommand:
+    def test_verify_tms_dir(self, tiny_tms_dir: Path):
+        runner = CliRunner()
+        result = runner.invoke(cli, ["verify", str(tiny_tms_dir)])
+        assert result.exit_code == 0
+        assert "Zoom range" in result.output
+        assert "Detected scheme: TMS" in result.output
+
+    def test_verify_empty_dir(self, tmp_path: Path):
+        empty = tmp_path / "empty"
+        empty.mkdir()
+        runner = CliRunner()
+        result = runner.invoke(cli, ["verify", str(empty)])
+        assert result.exit_code == 1
+
+
+class TestConvertCommand:
+    def test_convert_to_mbtiles(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        runner = CliRunner()
+        result = runner.invoke(cli, ["convert", str(tiny_tms_dir), str(out)])
+        assert result.exit_code == 0
+        assert out.exists()
+
+    def test_convert_with_scheme_flag(self, tmp_path: Path, tiny_xyz_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        runner = CliRunner()
+        result = runner.invoke(cli, ["convert", str(tiny_xyz_dir), str(out), "--scheme", "xyz"])
+        assert result.exit_code == 0
+        assert "Using specified scheme: XYZ" in result.output
+
+    def test_convert_auto_detect(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        runner = CliRunner()
+        result = runner.invoke(cli, ["convert", str(tiny_tms_dir), str(out)])
+        assert result.exit_code == 0
+        assert "Detected input scheme:" in result.output

tilepack-0.1.0/tests/test_convert.py

@@ -0,0 +1,108 @@
+"""Tests for tilepack.convert."""
+
+import sqlite3
+from pathlib import Path
+
+from tilepack.convert import run_convert
+
+
+class TestConvertToMbtiles:
+    def test_creates_mbtiles_file(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        run_convert(str(tiny_tms_dir), str(out), scheme="tms")
+        assert out.exists()
+        assert out.stat().st_size > 0
+
+    def test_mbtiles_tile_count(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        run_convert(str(tiny_tms_dir), str(out), scheme="tms")
+        conn = sqlite3.connect(str(out))
+        count = conn.execute("SELECT COUNT(*) FROM tiles").fetchone()[0]
+        conn.close()
+        assert count == 4
+
+    def test_mbtiles_metadata(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        run_convert(str(tiny_tms_dir), str(out), scheme="tms")
+        conn = sqlite3.connect(str(out))
+        meta = dict(conn.execute("SELECT name, value FROM metadata").fetchall())
+        conn.close()
+        assert meta["format"] == "png"
+        assert "minzoom" in meta
+        assert "maxzoom" in meta
+        assert meta["minzoom"] == "1"
+        assert meta["maxzoom"] == "2"
+
+    def test_xyz_input_flips_y(self, tmp_path: Path, tiny_xyz_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        run_convert(str(tiny_xyz_dir), str(out), scheme="xyz")
+        conn = sqlite3.connect(str(out))
+        # z=1, x=0, XYZ y=0 should become TMS y=1
+        row = conn.execute(
+            "SELECT tile_data FROM tiles WHERE zoom_level=1 AND tile_column=0 AND tile_row=1"
+        ).fetchone()
+        conn.close()
+        assert row is not None, "Expected XYZ y=0 to be stored as TMS y=1"
+
+    def test_auto_detect_scheme(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.mbtiles"
+        # No scheme specified — should auto-detect as TMS
+        run_convert(str(tiny_tms_dir), str(out))
+        assert out.exists()
+        conn = sqlite3.connect(str(out))
+        count = conn.execute("SELECT COUNT(*) FROM tiles").fetchone()[0]
+        conn.close()
+        assert count == 4
+
+
+class TestConvertToPmtiles:
+    def test_creates_pmtiles_file(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.pmtiles"
+        run_convert(str(tiny_tms_dir), str(out), scheme="tms")
+        assert out.exists()
+        assert out.stat().st_size > 0
+
+    def test_pmtiles_tiles_readable(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.pmtiles"
+        run_convert(str(tiny_tms_dir), str(out), scheme="tms")
+
+        from pmtiles.reader import MmapSource
+        from pmtiles.reader import Reader as PMTilesReader
+
+        source = MmapSource(open(out, "rb"))
+        reader = PMTilesReader(source)
+        header = reader.header()
+        assert header["min_zoom"] == 1
+        assert header["max_zoom"] == 2
+
+    def test_xyz_input_to_pmtiles(self, tmp_path: Path, tiny_xyz_dir: Path):
+        out = tmp_path / "output.pmtiles"
+        run_convert(str(tiny_xyz_dir), str(out), scheme="xyz")
+        assert out.exists()
+
+        from pmtiles.reader import MmapSource
+        from pmtiles.reader import Reader as PMTilesReader
+
+        source = MmapSource(open(out, "rb"))
+        reader = PMTilesReader(source)
+        # z=1, x=0, XYZ y=0 — should be stored directly as XYZ (no flip)
+        data = reader.get(1, 0, 0)
+        assert data is not None
+
+
+class TestConvertErrors:
+    def test_unknown_format(self, tmp_path: Path, tiny_tms_dir: Path):
+        out = tmp_path / "output.unknown"
+        try:
+            run_convert(str(tiny_tms_dir), str(out))
+        except SystemExit as e:
+            assert e.code == 1
+
+    def test_empty_dir(self, tmp_path: Path):
+        empty = tmp_path / "empty"
+        empty.mkdir()
+        out = tmp_path / "output.mbtiles"
+        try:
+            run_convert(str(empty), str(out))
+        except SystemExit as e:
+            assert e.code == 1