{"id":26119410,"url":"https://github.com/me9rez/node-mbtiles","last_synced_at":"2026-05-02T11:39:51.382Z","repository":{"id":281466306,"uuid":"945371088","full_name":"me9rez/node-mbtiles","owner":"me9rez","description":"一个用于读写MBTiles格式地图瓦片数据库的Node.js库。","archived":false,"fork":false,"pushed_at":"2025-03-09T09:00:39.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-09T09:27:14.346Z","etag":null,"topics":["mapbox","mbtiles","node","sqlite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"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/me9rez.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}},"created_at":"2025-03-09T09:00:08.000Z","updated_at":"2025-03-09T09:01:36.000Z","dependencies_parsed_at":"2025-03-09T09:37:48.772Z","dependency_job_id":null,"html_url":"https://github.com/me9rez/node-mbtiles","commit_stats":null,"previous_names":["me9rez/node-mbtiles"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/me9rez%2Fnode-mbtiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/me9rez%2Fnode-mbtiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/me9rez%2Fnode-mbtiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/me9rez%2Fnode-mbtiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/me9rez","download_url":"https://codeload.github.com/me9rez/node-mbtiles/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242855823,"owners_count":20196357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["mapbox","mbtiles","node","sqlite"],"created_at":"2025-03-10T12:54:45.494Z","updated_at":"2026-05-02T11:39:51.377Z","avatar_url":"https://github.com/me9rez.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @deepgis/node-mbtiles\n\n[![npm version](https://img.shields.io/npm/v/@deepgis/node-mbtiles?color=red)](https://npmjs.com/package/@deepgis/node-mbtiles)\n[![npm downloads](https://img.shields.io/npm/dm/@deepgis/node-mbtiles?color=yellow)](https://npm.chart.dev/@deepgis/node-mbtiles)\n\n一个用于读写MBTiles格式地图瓦片数据库的Node.js库，支持TMS瓦片坐标系，基于Node.js内置的`node:sqlite`模块实现。\n\n## 🚀 功能特性\n\n- 支持读取和写入MBTiles文件\n- 提供完整的瓦片操作接口\n- 支持元数据的读取和写入\n- 使用`node:sqlite`访问数据库（要求Node.js版本 \u003e= 22.5）\n- 支持TMS瓦片坐标系\n- 提供辅助工具函数计算瓦片面积\n- 完全用TypeScript实现，提供类型定义\n\n## 📦 安装\n\n使用pnpm安装：\n\n```bash\npnpm add @deepgis/node-mbtiles\n```\n\n使用npm安装：\n\n```bash\nnpm install @deepgis/node-mbtiles\n```\n\n## 📚 核心API文档\n\n### MBTiles类\n\n#### 构造函数\n```ts\nnew MBTiles(location: string, options?: DatabaseSyncOptions)\n```\n- `location`: MBTiles文件路径\n- `options`: 可选的数据库配置选项\n\n#### getInfo()\n```ts\ngetInfo(): Record\u003cstring, any\u003e\n```\n获取MBTiles文件的元数据信息。\n\n返回值：包含元数据的对象，其中会自动添加`scheme: 'tms'`字段。\n\n#### putInfo(data: Record\u003cstring, any\u003e)\n```ts\nputInfo(data: Record\u003cstring, any\u003e): void\n```\n写入元数据信息到MBTiles文件。\n\n- `data`: 包含元数据的对象\n\n#### getTile(z: number, x: number, y: number)\n```ts\ngetTile(z: number, x: number, y: number): Buffer\n```\n获取指定坐标的瓦片数据。\n\n- `z`: 瓦片层级\n- `x`: 瓦片X坐标\n- `y`: 瓦片Y坐标（TMS坐标系）\n\n返回值：瓦片数据的Buffer\n\n#### putTile(z: number, x: number, y: number, data: Buffer | string)\n```ts\nputTile(z: number, x: number, y: number, data: Buffer | string): Promise\u003c[any, any]\u003e\n```\n写入瓦片数据到MBTiles文件。\n\n- `z`: 瓦片层级\n- `x`: 瓦片X坐标\n- `y`: 瓦片Y坐标（TMS坐标系）\n- `data`: 瓦片数据，可以是Buffer或文件路径字符串\n\n返回值：包含两个数据库操作结果的数组\n\n#### close()\n```ts\nclose(): void\n```\n关闭数据库连接。\n\n### 工具函数\n\n#### calculateTileArea(zoom: number, tileX: number, tileY: number)\n```ts\ncalculateTileArea(zoom: number, tileX: number, tileY: number): number\n```\n计算指定瓦片的面积（平方千米）。\n\n- `zoom`: 瓦片层级\n- `tileX`: 瓦片X坐标\n- `tileY`: 瓦片Y坐标\n\n返回值：瓦片面积（平方千米）\n\n## 🗺️ 瓦片坐标系说明\n\n本库使用TMS（Tile Map Service）瓦片坐标系，与常见的XYZ坐标系的区别在于：\n\n- 在TMS坐标系中，Y轴从南向北递增\n- 在XYZ坐标系中，Y轴从北向南递增\n\n本库会自动处理TMS坐标转换，无需手动转换。\n\n## 💻 使用示例\n\n```ts\nimport { MBTiles, calculateTileArea } from '@deepgis/node-mbtiles';\n\n// 打开MBTiles文件\nconst mbtiles = new MBTiles('path/to/database.mbtiles');\n\n// 获取元数据\nconst info = mbtiles.getInfo();\nconsole.log('元数据:', info);\n\n// 设置元数据\nmbtiles.putInfo({\n  name: 'My Tile Set',\n  description: 'A sample tile set',\n  version: '1.0.0',\n  bounds: '-180,-90,180,90',\n  center: '0,0,0'\n});\n\n// 获取瓦片\ntry {\n  const tile = mbtiles.getTile(1, 1, 1);\n  console.log('瓦片数据长度:', tile.length);\n} catch (error) {\n  console.error('获取瓦片失败:', error);\n}\n\n// 写入瓦片\nconst tileData = Buffer.from([...]); // 瓦片数据\nawait mbtiles.putTile(1, 1, 1, tileData);\n\n// 计算瓦片面积\nconst area = calculateTileArea(10, 512, 512);\nconsole.log('瓦片面积(平方千米):', area);\n\n// 关闭数据库\nmbtiles.close();\n```\n\n## ⚠️ 错误处理\n\n在使用过程中，建议使用try/catch捕获可能的错误，特别是在获取不存在的瓦片或写入数据时。\n\n## 👨‍💻 开发\n\n1. 克隆仓库\n\n```bash\ngit clone https://github.com/me9rez/node-mbtiles.git\n```\n\n2. 安装依赖\n\n```bash\npnpm install\n```\n\n3. 运行测试\n\n```bash\npnpm test\n``` \n\n## 🛠️ 技术栈\n\n- TypeScript\n- SQLite (node:sqlite)\n- Vitest\n\n## 🔄 兼容性\n\n- 要求Node.js版本 \u003e= 22.5，因为使用了`node:sqlite`模块\n- 支持Windows、macOS和Linux系统\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fme9rez%2Fnode-mbtiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fme9rez%2Fnode-mbtiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fme9rez%2Fnode-mbtiles/lists"}