pure-frontend-tile-cutter

纯浏览器端全景图切图工具：将等距柱状（Equirectangular）全景图转换为 krpano 可用的 multires 立方体瓦片，并生成 XML / multires 配置。

仅支持浏览器环境（WebGL / Canvas / ImageBitmap），不能在 Node.js 中直接运行。

安装

将 package.json 中的包名设为 @你的用户名/pure-frontend-tile-cutter 后发布，然后：

pnpm add @krpano-xl/pure-frontend-tile-cutter

或使用 pnpm / yarn：

pnpm add @krpano-xl/pure-frontend-tile-cutter

快速开始

import PureFrontendTileCutter from "@krpano-xl/pure-frontend-tile-cutter";

const cutter = new PureFrontendTileCutter({
  tileSize: 512,
  maxCubeSize: 2048,
  sceneId: "my-scene-id",
  onProgress: (percent, completed, total) => {
    console.log(`切图进度 ${percent}% (${completed}/${total})`);
  },
  onLog: (msg) => console.log(msg),
});

// file 为 <input type="file"> 选中的 File 对象
const result = await cutter.makeTiles(file);

console.log(result.code.multires); // krpano multires 字符串
console.log(result.content.length); // 瓦片数量

配置项

| 选项 | 类型 | 默认值 | 说明 | | ----------------- | ---------- | ------ | ------------------------------------- | | tileSize | number | 512 | 瓦片边长（krpano 推荐 512 或 1024） | | maxCubeSize | number | 2048 | 立方体面最大边长，限制最高层级瓦片数 | | jpegQuality | number | 0.82 | 最高层级 JPEG 质量（低层级自动降低） | | previewFaceSize | number | 256 | cube 条带预览每面尺寸 | | previewQuality | number | 0.72 | 预览图 JPEG 质量 | | thumbWidth | number | 480 | 缩略图宽度 | | thumbHeight | number | 240 | 缩略图高度 | | thumbQuality | number | 0.7 | 缩略图 JPEG 质量 | | sceneId | string | '' | 场景 ID，用于生成 OSS / 路径前缀 | | onProgress | function | — | (percent, completed, total) => void | | onLog | function | — | (message) => void |

返回值 makeTiles(file)

| 字段 | 类型 | 说明 | | --------------------- | -------- | ----------------------------------------------------------------- | | dirName | string | 文件名（不含扩展名） | | content | Array | 瓦片列表，每项含 blob、name、face、levelNum、row、col | | preview | Blob | cube 条带预览图（3×2，供 krpano <preview>） | | thumb | Blob | 等距柱状缩略图 | | code.scene | string | 完整 krpano scene XML | | code.tileImage | string | 带 <level> 的 image XML | | code.shortTileImage | string | 短语法 cube XML | | code.multires | string | multires 短语法 + URL 模板 | | levels | number | 分辨率层级数 | | tiles | number | 瓦片总数 | | width / height | number | 原图尺寸 | | duration | string | 耗时，如 "12.34s" |

瓦片路径约定

{sceneId}/{face}/l{level}/{row}/l{level}_{face}_{row}_{col}.jpg

示例：abc123/f/l2/1/l2_f_1_1.jpg

multires 示例

512,512,1024,2048#%s/l%l/%v/l%l_%s_%v_%h.jpg

浏览器要求

• Chrome / Edge / Firefox / Safari 现代版本
• 支持：WebGL（可选，无则降级 CPU）、createImageBitmap、OffscreenCanvas（可选）
• 需在 HTTPS 或 localhost 下使用（部分 API 限制）

感谢支持

详情请联系维护者：[李赛广] (微信: 18815675644)

感谢支持：

License

MIT © 李赛广