{"id":50309776,"url":"https://github.com/swisstopo/mbtiles2vtpk","last_synced_at":"2026-05-28T20:01:55.144Z","repository":{"id":351741910,"uuid":"1212242570","full_name":"swisstopo/mbtiles2vtpk","owner":"swisstopo","description":"This tool converts a MapBox Vector MBtiles to an ESRI VTPK file.","archived":false,"fork":false,"pushed_at":"2026-04-16T08:48:56.000Z","size":8147,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T10:33:23.359Z","etag":null,"topics":["mbtiles","tool","vtpk"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swisstopo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T07:37:48.000Z","updated_at":"2026-04-16T08:49:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/swisstopo/mbtiles2vtpk","commit_stats":null,"previous_names":["swisstopo/mbtiles2vtpk"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/swisstopo/mbtiles2vtpk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisstopo%2Fmbtiles2vtpk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisstopo%2Fmbtiles2vtpk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisstopo%2Fmbtiles2vtpk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisstopo%2Fmbtiles2vtpk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swisstopo","download_url":"https://codeload.github.com/swisstopo/mbtiles2vtpk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisstopo%2Fmbtiles2vtpk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33624221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mbtiles","tool","vtpk"],"created_at":"2026-05-28T20:01:51.980Z","updated_at":"2026-05-28T20:01:55.136Z","avatar_url":"https://github.com/swisstopo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mbtiles2vtpk\n\nConvert MBTiles vector tile packages to the **ESRI VTPK** format.  \nTested with ArcGIS Pro and QGIS.\n\n---\n\n## Installation\n\n```bash\n# 1. Clone with submodules\ngit clone --recurse-submodules https://github.com/swisstopo/mbtiles2vtpk.git\ncd mbtiles2vtpk\n\n# If you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n```bash\n# 2. Create a virtual environment\npython -m venv .venv\n```\n\n**Windows**\n```powershell\n.venv\\Scripts\\activate\n```\n\n**Linux / macOS**\n```bash\nsource .venv/bin/activate\n```\n\n```bash\n# 3. Install the package and its dependencies\npip install -e .\npip install joblib\n```\n\nAfter activation, the `mbtiles2vtpk` command is available in the terminal.  \nAlternatively, use the venv Python directly without activating:\n\n**Windows**\n```powershell\n.venv\\Scripts\\python.exe mbtiles2vtpk -i input.mbtiles -o output.vtpk\n```\n\n**Linux / macOS**\n```bash\n.venv/bin/python mbtiles2vtpk -i input.mbtiles -o output.vtpk\n```\n\n---\n\n## Usage\n\n### Basic conversion\n\n```bash\nmbtiles2vtpk -i input.mbtiles -o output.vtpk\n```\n\n### With a custom Mapbox GL style\n\nProvide a URL or a local path to a Mapbox GL style JSON.\nFonts (PBF glyphs) and sprites are downloaded automatically and\n**cached locally** so subsequent conversions are instant.\nThe pipeline **stops immediately** if any required resource cannot be downloaded.\n\n```bash\n# From a public URL\nmbtiles2vtpk -i input.mbtiles -o output.vtpk \\\n  --style https://raw.githubusercontent.com/mapbox/mapbox-gl-styles/master/styles/basic-v8.json\n\n# From a local file\nmbtiles2vtpk -i input.mbtiles -o output.vtpk --style ./style/dark_minimal.json\n\n# With a custom working directory\nmbtiles2vtpk -i input.mbtiles -o output.vtpk --style ./my-style.json --work-dir C:\\Temp\\work\n```\n\n### All options\n\n```\nmbtiles2vtpk -i INPUT -o OUTPUT [--style URL_OR_PATH] [--work-dir DIR]\nmbtiles2vtpk --cache-info\nmbtiles2vtpk --clear-cache\n\nconversion:\n  -i, --input   PATH        Source .mbtiles file\n  -o, --output  PATH        Output .vtpk file\n  --style       URL_OR_PATH Mapbox GL style to embed (URL or local path)\n  --work-dir    DIR         Intermediate working directory (default: auto temp)\n\ncache:\n  --cache-info              Show cache location and size, then exit\n  --clear-cache             Delete all cached resources, then exit\n```\n\n### PyCharm / no install\n\n```\nRun \u003e Edit Configurations\n  → Module name : mbtiles2vtpk.cli\n  → Parameters  : -i input.mbtiles -o output.vtpk [--style ...]\n  → Working dir : \u003crepo root\u003e\n```\n\n---\n\n## Resource cache\n\nDownloaded fonts and sprites are cached in:\n\n```\n~/.mbtiles2vtpk/cache/\n    styles/     ← style JSON files\n    fonts/      ← PBF glyph files  (256 ranges × N fonts)\n    sprites/    ← sprite.json / sprite.png / @2x variants\n```\n\nThe cache key is the SHA-256 of the resource URL **without** the query string,\nso changing API keys does not invalidate existing entries.\n\n```bash\nmbtiles2vtpk --cache-info    # show size\nmbtiles2vtpk --clear-cache   # wipe everything\n```\n\n---\n\n## MapTiler API credentials\n\nWhen the style, fonts, or sprites are served from **api.maptiler.com**,\nset these environment variables before running:\n\n| Variable | Purpose |\n|---|---|\n| `MAPTILER_KEY` | API key — appended to every request as `?key=\u003cvalue\u003e` |\n| `MAPTILER_ORIGIN` | Allowed origin — sent as the `Origin:` HTTP header |\n\nIf either variable is missing and the URL targets api.maptiler.com,\nthe conversion **stops with a clear error message**.\n\n**Windows (PowerShell)**\n\n```powershell\n$env:MAPTILER_KEY    = \"your_key_here\"\n$env:MAPTILER_ORIGIN = \"https://your-app.example.com\"\nmbtiles2vtpk -i input.mbtiles -o output.vtpk --style https://api.maptiler.com/...\n```\n\n**Windows (CMD)**\n\n```cmd\nset MAPTILER_KEY=your_key_here\nset MAPTILER_ORIGIN=https://your-app.example.com\nmbtiles2vtpk -i input.mbtiles -o output.vtpk --style https://api.maptiler.com/...\n```\n\n**Linux / macOS**\n\n```bash\nexport MAPTILER_KEY=your_key_here\nexport MAPTILER_ORIGIN=https://your-app.example.com\nmbtiles2vtpk -i input.mbtiles -o output.vtpk --style https://api.maptiler.com/...\n```\n\nThe credentials are injected at fetch time and **never stored in the cache**.\n\n---\n\n## External dependency\n\nTile bundle creation is delegated to\n[ltbam/python-mbtiles2compactcache](https://github.com/ltbam/python-mbtiles2compactcache),\nincluded as a git submodule under `mbtiles2vtpk/vendor/`.\n\n```bash\n# Populate after cloning\ngit submodule update --init --recursive\n```\n\n---\n\n## Conversion pipeline\n\n| # | Class | Description |\n|---|-------|-------------|\n| 1 | `StructureCreator` | Create VTPK folder skeleton |\n| 2 | `TileExtractor` | Extract tiles → Compact Cache V2 bundles (via submodule) |\n| 3 | `TilemapEditor` | Build presence quadtree → `p12/tilemap/root.json` |\n| 4 | `StyleCopier` | Embed Mapbox GL style + download fonts \u0026 sprites |\n| 5 | `RootJsonCreator` | Write `p12/root.json`, `metadata.json`, `esriinfo/` |\n| 6 | `TileSizeEditor` | Patch tile size to 512 × 512 |\n| 7 | `LodsEditor` | Verify LODs match extracted zoom levels |\n| 8 | `FontResolver` | Write `p12/resources/info/root.json` resource index |\n| 9 | `Repacker` | ZIP everything into a `.vtpk` archive (ZIP_STORED) |\n\n---\n\n## Output VTPK structure\n\n```\noutput.vtpk  (ZIP, no compression)\n├── esriinfo/\n│   ├── item.pkinfo\n│   └── iteminfo.xml\n└── p12/\n    ├── root.json\n    ├── metadata.json\n    ├── tile/\n    │   ├── L00/R0000C0000.bundle\n    │   └── ...\n    ├── tilemap/\n    │   └── root.json\n    └── resources/\n        ├── styles/root.json\n        ├── fonts/\u003cFontName\u003e/\u003crange\u003e.pbf\n        ├── sprites/sprite.json|png|@2x.*\n        └── info/root.json\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswisstopo%2Fmbtiles2vtpk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswisstopo%2Fmbtiles2vtpk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswisstopo%2Fmbtiles2vtpk/lists"}