@ericchen1990/pano-view 3.1.3 → 3.2.0

package/README.md

@@ -1791,3 +1791,66 @@ import "@ericchen1990/pano-view/styles.css";
 ```
 
 See [Stylesheet (HTML chrome)](#stylesheet-html-chrome).
+
+## Spherical multiresolution tiles
+
+`SphereTile` renders full 2:1 equirectangular pyramids without assembling a full-resolution texture:
+
+```tsx
+import { PanoViewer, SphereTile } from "@ericchen1990/pano-view";
+
+<PanoViewer>
+  <SphereTile
+    baseUrl="/panoramas/legacy"
+    multires="512,257x129,513x257,1025x513,2050x1025,4100x2050"
+    urlTemplate="tiles/%l/%h_%v.webp"
+    previewUrl="previews/400.webp"
+    indexBase={0}
+  />
+</PanoViewer>;
+```
+
+This layout matches Sharp Deep Zoom with `size: 512`, `depth: "onetile"`,
+`layout: "dz"`, and no overlap. Set `indexBase={0}` for that raw Sharp output, including partial edge tiles.
+The default `indexBase={1}` matches existing krpano sphere resources whose
+level, column and row all start at **1**. Logical addresses passed to callbacks
+and `resolveTileUrl` always start at 0; `indexBase` only affects URL templates.
+`multires` accepts the string above or `{ tileSize, levels: [{ width, height }] }`.
+Copy actual dimensions rather than deriving each level by multiplying by two:
+odd dimensions round independently. Each level must describe a full 2:1 image
+(with up to two pixels of rounding tolerance).
+
+Relative paths resolve under `baseUrl`; absolute paths/URLs remain absolute.
+`resolveTileUrl(address)` overrides the template. Templates support `%l`,
+horizontal `%h`/`%x`/`%u`/`%c`, vertical `%v`/`%y`/`%w`/`%r`, and padding such as
+`%00h`. `yawOffset` rotates the source; the source image center faces yaw 0,
+right is positive yaw, and top is positive pitch.
+
+`maxTextureMemoryMb` (128), `maxConcurrentLoads` (4), and `retryCount` (1)
+configure the per-component tile cache. The preview uses separate memory. If the
+visible detail and its fallback levels exceed the tile budget, the viewer uses a
+coarser level; the preview stays underneath. `loadMode` is `full` (default),
+`base`, or `preview`. `visible={false}` preloads without drawing.
+`onReady` fires once per source when a preview or tile becomes paintable, even
+if the preview failed. `onPreviewError`, `onTileError`, `onLoadProgress`, and
+`onLevelChange` expose failures/progress; levels in callbacks start at 0.
+Unmounting disposes owned textures and ignores late results.
+
+Use `SphereTile` directly as a `PanoViewer` child; `Scenes` currently accepts
+`sphere` and cube `tile` definitions only.
+
+## Accessibility matrices and tooltip typography
+
+`PanoFilter` also accepts `colorMatrix`, a readonly row-major 4×5 RGBA matrix
+(20 finite numbers, matching SVG `feColorMatrix`). The matrix is applied in
+display/sRGB space after the panorama preset. `intensity` mixes each effect
+with the original; `enabled={false}` disables both. Set
+`colorMatrixScope="all"` to include hotspot textures; the default `"panorama"`
+keeps existing behavior. Artistic presets always affect only the panorama.
+HTML tooltips, iframes and other DOM chrome remain host-styled.
+
+Hotspot `tooltipAppearance` now accepts `fontFamily`, `lineHeight`, and
+`letterSpacing`, in addition to `fontSize` and existing paint options.
+`lineHeight` numbers are unitless; numeric `letterSpacing` values are CSS pixels.
+
+Regression checks: `pnpm --filter @ericchen1990/pano-view test` (Node 22+).

package/README.zh-CN.md

@@ -1493,3 +1493,56 @@ import "@ericchen1990/pano-view/styles.css";
 ```
 
 见 [样式表（HTML 叠加层）](#样式表html-叠加层)。
+
+## 球面多分辨率瓦片
+
+`SphereTile` 直接渲染完整的 2:1 等距柱状全景瓦片，不拼接高分辨率整图：
+
+```tsx
+import { PanoViewer, SphereTile } from "@ericchen1990/pano-view";
+
+<PanoViewer>
+  <SphereTile
+    baseUrl="/panoramas/legacy"
+    multires="512,257x129,513x257,1025x513,2050x1025,4100x2050"
+    urlTemplate="tiles/%l/%h_%v.webp"
+    previewUrl="previews/400.webp"
+    indexBase={0}
+  />
+</PanoViewer>;
+```
+
+格式对应 Sharp Deep Zoom 的 `size: 512`、`depth: "onetile"`、`layout: "dz"`、
+无重叠瓦片。Sharp 原始输出使用 `indexBase={0}`，支持不足一块的边缘瓦片。
+默认的 `indexBase={1}` 兼容层级、列、行都从 **1** 开始的存量 krpano 球面资源。
+回调与 `resolveTileUrl` 接收的逻辑地址始终从 0 开始，`indexBase` 只作用于 URL 模板。`multires` 也可传 `{ tileSize, levels: [{ width, height }] }`。
+应使用资源的真实层级尺寸，奇数尺寸逐级取整，不能简单乘二推导。每级应为完整的
+2:1 全景，允许最多两像素的取整误差。
+
+相对路径基于 `baseUrl`，绝对路径与 URL 保持原样。`resolveTileUrl(address)` 优先于
+模板。模板支持 `%l`、横向 `%h`/`%x`/`%u`/`%c`、纵向 `%v`/`%y`/`%w`/`%r`，
+以及 `%00h` 等补零。`yawOffset` 旋转图像；图像中心为 yaw 0，向右为正 yaw，向上为正 pitch。
+
+`maxTextureMemoryMb`（默认 128）、`maxConcurrentLoads`（4）、`retryCount`（1）
+控制单个组件的瓦片缓存。预览图内存单独计算。当可见细节与回退层级超出预算时，
+采用较粗层级，预览始终作为底图。`loadMode` 支持 `full`（默认）、`base` 和 `preview`；
+`visible={false}` 仅预加载。`onReady` 在一个源的首个可绘制预览或瓦片就绪时触发一次，
+预览失败时仍可通过瓦片就绪。错误与进度通过 `onPreviewError`、`onTileError`、
+`onLoadProgress`、`onLevelChange` 提供；回调中的层级同样从 0 开始。
+卸载时释放组件纹理，丢弃迟到的加载结果。
+
+将 `SphereTile` 直接放在 `PanoViewer` 下；当前 `Scenes` 仍只接受 `sphere` 和立方体
+`tile` 场景定义。
+
+## 无障碍颜色矩阵与标签排版
+
+`PanoFilter.colorMatrix` 接收只读的行优先 4×5 RGBA 矩阵（20 个有限数值，与 SVG
+`feColorMatrix` 一致），在预设滤镜之后、显示/sRGB 颜色空间中应用。`intensity`
+控制效果混合比例，`enabled={false}` 关闭预设和矩阵。`colorMatrixScope="all"`
+将矩阵同时应用于热点纹理；默认 `"panorama"` 保持原有行为。艺术预设始终仅作用于
+全景。HTML 标签、iframe 和其他 DOM 界面仍由宿主设置样式。
+
+热点的 `tooltipAppearance` 新增 `fontFamily`、`lineHeight`、`letterSpacing`，
+配合原有的 `fontSize` 使用。数字 `lineHeight` 为无单位倍数，数字 `letterSpacing` 为 CSS 像素。
+
+回归验证：`pnpm --filter @ericchen1990/pano-view test`（Node 22+）。