@realsee/dnalogel 3.77.4 → 3.77.6

package/dist/DigitalPerformancePlugin/typings/index.d.ts

@@ -0,0 +1,79 @@
+import * as THREE from 'three';
+import type { DigitalChapter } from '../core/DigitalStateMachine';
+export type { DigitalScript, DigitalChapter, DigitalModelPlayer, DigitalSubTitlePlayer, DigitalCameraPlayer, DigitalModelKeyframe, DigitalSubTitleKeyframe, DigitalCameraKeyframe, DigitalModelState, DigitalSubTitleState, DigitalCameraState, DigitalModelPlayerItem, DigitalModelPlayerEffect, DigitalEffectKeyframe, DigitalDataState, DigitalDataPlayer, KeyframeType, StateType, } from '../core/DigitalStateMachine';
+export interface DigitalPerformancePluginConfig {
+    autoPlay?: boolean;
+    loop?: boolean;
+    debug?: boolean;
+}
+export interface GlobalProgress {
+    currentTime: number;
+    totalTime: number;
+    percentage: number;
+    currentChapterIndex: number;
+    currentChapterTime: number;
+    currentChapter?: DigitalChapter;
+}
+export interface ChapterTimeInfo {
+    chapterIndex: number;
+    chapterName: string;
+    startTime: number;
+    duration: number;
+    endTime: number;
+    chapter: DigitalChapter;
+}
+export interface ChapterLocation {
+    chapterIndex: number;
+    chapterTime: number;
+    chapter: DigitalChapter;
+}
+export type ProgressListener = (progress: GlobalProgress) => void;
+export interface ProgressBarEvents {
+    'progress-changed': ProgressListener;
+    'chapter-changed': (chapterIndex: number, chapter: DigitalChapter) => void;
+    'seek-started': (targetTime: number) => void;
+    'seek-completed': (actualTime: number) => void;
+    'playback-started': (startTime: number) => void;
+    'playback-completed': () => void;
+}
+export interface ExtendedAnimationConfig {
+    url: string;
+    repeat: boolean;
+    switchDuration?: number;
+    isOver?: boolean;
+}
+export interface DigitalItemKeyframe {
+    visible: boolean;
+    timeStamp: number;
+    position?: number[];
+    quaternion?: number[];
+    scale?: number[];
+}
+export interface DigitalItemState {
+    visible: boolean;
+    translation?: THREE.Vector3;
+    quaternion?: THREE.Quaternion;
+    scale?: THREE.Vector3;
+    keyframeIndex: number;
+    isFinal: boolean;
+}
+export interface DigitalEffectState {
+    visible: boolean;
+    image?: string;
+    intensity?: number;
+    color?: THREE.Color;
+    scale?: THREE.Vector3;
+    keyframeIndex: number;
+    isFinal: boolean;
+}
+export interface TracePoint {
+    position: THREE.Vector3;
+    timestamp: number;
+}
+export interface TraceManager {
+    tracePoints: THREE.Vector3[];
+    maxPoints: number;
+    addPoint(point: THREE.Vector3): void;
+    clear(): void;
+    getPoints(): THREE.Vector3[];
+}

package/dist/PanoTagPlugin/controller/Tag/BaseTag.d.ts

@@ -12,7 +12,9 @@ import type { PartialObjectDeep } from '../../../typings/typings';
 import type { LiteralUnion } from 'type-fest';
 import type { CSS3DObjectPlus } from '../../../shared-utils/CSS3DRender/CSS3DObject';
 import type { Rectangle } from '../../../Sculpt/Objects/Rectangle';
-import { Line } from '@realsee/five/line';
+import type { Line } from '@realsee/five/line';
+import type { Box } from '../../../Sculpt/Objects/Box';
+import type { Polygon } from '../../../Sculpt/typings';
 /**
  * @description 标签实例
  * @property `id` 标签id
@@ -88,6 +90,8 @@ export declare abstract class BaseTag<C extends TagContentType = TagContentType,
         dispose: () => void;
     };
     rectanglePlane?: Rectangle;
+    boxShape?: Box;
+    polygonShape?: Polygon;
     dom?: HTMLDivElement;
     contentDom?: HTMLDivElement;
     initialConfig: TagData['config'];

package/dist/PanoTagPlugin/controller/Tag/BoxTag.d.ts

@@ -0,0 +1,119 @@
+import type PanoTagPluginController from '..';
+import type { TagContentType, Tag as TagData, TagInstance, ArrayPosition, TagClickParams } from '../..';
+import { BaseTag } from './BaseTag';
+import * as THREE from 'three';
+import type { PartialObjectDeep } from '../../../typings/typings';
+import type { Tag } from '../..';
+import { Box } from '../../../Sculpt/Objects/Box';
+export type BoxTagInterface<C extends TagContentType = TagContentType> = TagInstance<C, '3DBox'>;
+/**
+ * 3DBox 类型的标签
+ * 使用 Sculpt Box 进行渲染，避免复杂的坐标转换
+ */
+export declare class BoxTag<C extends TagContentType = TagContentType> extends BaseTag<C, '3DBox'> {
+    boxShape?: Box;
+    private tagStyle?;
+    private clickEventDispose?;
+    private domClickDispose?;
+    screenPosition: {
+        leftPx: number;
+        topPx: number;
+        scale: number;
+    } | null;
+    constructor(plugin: PanoTagPluginController, tagData: TagData);
+    /**
+     * 获取 Box 样式配置（合并用户配置和默认值）
+     */
+    private getBoxStyle;
+    /**
+     * 更新 Box 样式
+     */
+    private updateBoxStyle;
+    /**
+     * 更新标签数据
+     */
+    set(tag: PartialObjectDeep<Tag<C, '3DBox'>>, deepMerge?: boolean): void;
+    /**
+     * 设置标签数据
+     */
+    setData(...data: Parameters<InstanceType<typeof BaseTag<C, '3DBox'>>['setData']>): void;
+    /**
+     * 获取盒子的中心点
+     */
+    getCenter(): ArrayPosition;
+    /**
+     * 获取盒子的8个角点坐标
+     */
+    getCorners(): THREE.Vector3[];
+    /**
+     * 计算盒子的法向量
+     */
+    computeNormal(): THREE.Vector3;
+    /**
+     * 初始化 Sculpt Box
+     */
+    private initializeSculptBox;
+    /**
+     * 设置点击事件
+     */
+    private setupClickEvents;
+    /**
+     * 清理点击事件
+     */
+    private cleanupClickEvents;
+    /**
+     * 更新 Sculpt Box 的数据
+     */
+    private updateSculptBox;
+    /**
+     * 启用编辑器
+     * 用于编辑已存在的 Box
+     */
+    editorEnable(): Promise<void>;
+    /**
+     * 禁用编辑器
+     */
+    editorDisable(): void;
+    /**
+     * 从 Sculpt Box 同步 position 到 BoxTag
+     */
+    private syncBoxPositionFromSculpt;
+    /**
+     * 将 BoxPosition 转换为 Sculpt 需要的数据格式
+     */
+    private boxPositionToSculptData;
+    /**
+     * @description 点击事件处理
+     */
+    onClick(params: Pick<TagClickParams, 'target'>): void;
+    /**
+     * @description 展开自己，收起其他标签
+     */
+    unfoldAndFoldOthers(): void;
+    /**
+     * 展开标签详情
+     */
+    unfold(): void;
+    /**
+     * 折叠标签详情
+     */
+    fold(): void;
+    /**
+     * 设置展开/折叠状态
+     */
+    setUnfold(unfolded: boolean): void;
+    /**
+     * 更新屏幕位置（用于在 2D UI 中显示内容）
+     * 显示在 Box 最右侧的顶点位置
+     */
+    updateScreenPosition(): void;
+    get centerPosition(): THREE.Vector3;
+    /**
+     * 应用可见性变化
+     */
+    applyVisible(): void;
+    /**
+     * 销毁标签
+     */
+    dispose(): void;
+}

package/dist/PanoTagPlugin/controller/Tag/MaskTag.d.ts

@@ -0,0 +1,257 @@
+import type PanoTagPluginController from '..';
+import type { TagContentType, Tag as TagData, TagInstance, TagClickParams } from '../..';
+import { BaseTag } from './BaseTag';
+import * as THREE from 'three';
+import type { PartialObjectDeep } from '../../../typings/typings';
+import type { Tag } from '../..';
+import type { State as FiveState } from '@realsee/five';
+import type { AnimeParams } from 'animejs';
+export type MaskTagInterface<C extends TagContentType = TagContentType> = TagInstance<C, 'Mask'>;
+/**
+ * Mask 类型的标签
+ * 基于全景图 mask 和颜色区域进行物体标记
+ */
+export declare class MaskTag<C extends TagContentType = TagContentType> extends BaseTag<C, 'Mask'> {
+    /**
+     * Mask 纹理缓存（静态，所有 MaskTag 实例共享）
+     * key: mask URL 或 canvas 的 symbol, value: { texture: THREE.Texture, refCount: number, abortController?: AbortController }
+     */
+    private static maskTextureCache;
+    /**
+     * Canvas 到 Symbol 的映射（用于缓存 canvas 纹理）
+     */
+    private static canvasSymbolMap;
+    /** 同点位共用 mesh：key = meshKey(panoIndex + maskKey), value = 共享数据 */
+    private static sharedMeshRegistry;
+    /**
+     * mask 图片 URL 或 Canvas 元素（2:1 全景图格式）
+     */
+    maskUrl: string | HTMLCanvasElement;
+    /**
+     * 目标颜色（RGB 格式）
+     */
+    targetColor: [number, number, number];
+    /**
+     * mask 渲染的 mesh 对象（使用 Sphere）
+     */
+    maskMesh?: THREE.Mesh;
+    /**
+     * mask 纹理对象
+     */
+    private maskTexture?;
+    /**
+     * 是否正在加载 mask
+     */
+    private loadingMask;
+    /**
+     * 资源是否已释放
+     */
+    private _disposed;
+    /**
+     * 标签样式配置
+     */
+    private tagStyle?;
+    /**
+     * 点击事件清理函数
+     */
+    private clickEventDispose?;
+    /** 当前 tag 在共享 style 纹理中的下标（color 即 id） */
+    private sharedStyleIndex;
+    /** 共享 mesh 的 registry key，用于 updateMaskStyle / dispose 查找 entry */
+    private _sharedMeshKey;
+    constructor(plugin: PanoTagPluginController, tagData: TagData);
+    private getColorKey;
+    /** 同点位共用一个 mesh，key 仅用 panoIndex（string/canvas 切换时不会因 key 不同而重复创建） */
+    private static getMeshKey;
+    /**
+     * 初始化/挂载到同点位共享 mesh，用 appendStyleToMaterial 注册本 tag 的 style（color 即 id）
+     */
+    private initializeMaskMesh;
+    /** 构建用于 mergedTexture 的 style 对象（color 作 id），tolerance 0–255 */
+    private buildStyleForMaterial;
+    private static createSharedMesh;
+    /** 仅更新材质中某一 slot 的 style（用于 enable/disable/updateMaskStyle） */
+    private updateStyleSlotInMaterial;
+    private setupSharedMeshRaycast;
+    /**
+     * 计算法向量
+     * Mask 标签返回向上的法向量（因为是贴在 cube 面上）
+     */
+    computeNormal(): THREE.Vector3;
+    /**
+     * 不把共享 mesh 作为 blink 目标，闪烁通过本 tag 的 style opacity 动画实现
+     */
+    protected getAdditionalBlinkTargets(): any | any[] | null;
+    /**
+     * 闪烁仅针对本 tag：通过改变本 tag 在 merged texture 中的 opacity 实现
+     */
+    blink(animeConfig?: Partial<AnimeParams>): Promise<void>;
+    /**
+     * 更新标签数据
+     */
+    set(tag: PartialObjectDeep<Tag<C, 'Mask'>>, deepMerge?: boolean): void;
+    /** 供 rebuildEntryMaterial 使用：返回当前 tag 的 style 对象 */
+    getStyleForMaterial(): {
+        color: number[];
+        tolerance: number;
+        highlightColor: number[];
+        opacity: number;
+    };
+    /**
+     * 重写 getVisible 方法
+     * Mask 标签仅在当前点位可见
+     */
+    getVisible(fiveState?: Partial<FiveState>): boolean;
+    /**
+     * 重写 computeVisible 方法
+     * 增加 Mask 特有的可见性检查逻辑，用于 whyHide 功能
+     */
+    protected computeVisible(_fiveState?: Partial<FiveState>): {
+        value: boolean;
+        reason?: any;
+    };
+    /**
+     * 点击事件处理
+     */
+    onClick(params: Pick<TagClickParams, 'target'>): void;
+    /**
+     * 展开自己，收起其他标签
+     */
+    unfoldAndFoldOthers(): void;
+    /**
+     * 展开标签详情
+     */
+    unfold(): void;
+    /**
+     * 折叠标签详情
+     */
+    fold(): void;
+    /**
+     * 设置展开/折叠状态
+     */
+    setUnfold(unfolded: boolean): void;
+    /**
+     * 更新屏幕位置
+     */
+    updateScreenPosition(): void;
+    /**
+     * 应用可见性变化（通过 style opacity 控制展示，共享 mesh 保持 visible）
+     */
+    applyVisible(): void;
+    /**
+     * 更新 mesh 的位置和旋转（跟随观察者）
+     * 参考 itemMask 实现
+     */
+    private updateMeshTransform;
+    /**
+     * 步骤1：从材质中解析出 styleList
+     * @param {THREE.ShaderMaterial} material - 目标材质
+     * @returns {Array} 解析后的 styleList
+     */
+    private parseStyleListFromMaterial;
+    /**
+     * 步骤2：更新材质的样式纹理（追加新元素后）
+     * @param {THREE.ShaderMaterial} material - 目标材质
+     * @param {Array} newStyle - 要追加的新样式对象
+     */
+    private appendStyleToMaterial;
+    /**
+     * 获取 Mask 样式配置（合并用户配置和默认值）
+     */
+    private getMaskStyle;
+    /**
+     * 设置点击事件（仅当 raycast 命中本 tag 的 color 时触发）
+     */
+    private setupClickEvents;
+    /**
+     * 清理点击事件
+     */
+    private cleanupClickEvents;
+    /**
+     * 重新加载 mask 图：从旧点位 mesh 注销，再按新 maskUrl 初始化
+     */
+    private reloadMask;
+    /**
+     * changeTagById 改 mask 时：只更新共享 mesh 的 texture，不 unregister
+     * 有 entry 则换图；无 entry 则走完整初始化
+     */
+    private updateSharedMeshTexture;
+    /**
+     * 更新当前 tag 在共享材质中的 style slot（color/style 控制展示）
+     */
+    updateMaskStyle(): void;
+    /**
+     * 更新 Canvas 纹理（仅当 maskUrl 为 Canvas 时有效）
+     * 当 canvas 内容发生变化时，调用此方法更新渲染
+     */
+    updateCanvasTexture(): void;
+    /**
+     * 清理当前标签：从共享材质中删除本 tag 的样式槽，并更新材质；
+     * 若该点位已无其他 tag 则销毁 mesh 并释放纹理。
+     */
+    private disposeMaskResources;
+    /**
+     * 清理 MaskTag 特有的资源（公开方法）
+     */
+    dispose(): void;
+    /**
+     * 禁用标签（通过 style opacity=0 隐藏，不拆 mesh）
+     */
+    disable(): void;
+    /**
+     * 启用标签（恢复 style 展示）
+     */
+    enable(): void;
+    /**
+     * 销毁标签（重写父类方法）
+     */
+    destroy(): void;
+    /**
+     * 清除所有点位共享 mesh（重新 load 数据前调用）
+     */
+    static clearSharedMeshRegistry(): void;
+    /**
+     * 将 style 列表写入材质（用于重建材质）
+     */
+    private static writeStyleListToMaterial;
+    /**
+     * destroy 后重建该点位材质，更新剩余 tag 的 styleIndex
+     */
+    private static rebuildEntryMaterial;
+    /**
+     * 获取 mask 的缓存 key
+     * @param maskSource mask URL 或 Canvas
+     * @returns 缓存 key
+     */
+    private static getMaskCacheKey;
+    /**
+     * 加载 Mask 纹理（静态方法，支持缓存和引用计数）
+     * @param maskSource mask 图片 URL 或 Canvas 元素
+     * @returns Promise<THREE.Texture>
+     */
+    private static loadMaskTexture;
+    /**
+     * 释放 Mask 纹理（静态方法）
+     * @param maskSource mask 图片 URL 或 Canvas 元素
+     */
+    private static releaseMaskTexture;
+    /**
+     * 获取当前缓存的纹理统计信息（用于性能监控和调试）
+     * @returns 缓存统计信息
+     */
+    static getCacheStats(): {
+        totalCached: number;
+        totalRefCount: number;
+        estimatedMemoryMB: number;
+        cacheEntries: Array<{
+            source: string;
+            refCount: number;
+            sizeMB: number;
+        }>;
+    };
+    /**
+     * 强制清理所有缓存的纹理（用于内存管理，谨慎使用）
+     * 注意：这会释放所有纹理，即使它们仍在使用中
+     */
+    static clearAllCache(): void;
+}

package/dist/PanoTagPlugin/controller/Tag/MaskTag.shaders.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mask 标签的 Shader 代码
+ * 参考 itemMask 插件实现
+ */
+/**
+ * Vertex Shader
+ */
+export declare const maskVertexShader = "\nvarying vec2 vUv;\nvoid main() {\n  vUv = uv;\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}\n";
+/** 多 style：mergedTexture 中每组 3 像素为 color(id)/tolerance+highlight/opacity，用 color 作 id 匹配 */
+export declare const maskFragmentShaderMulti = "\n#define RESOLUTION 2048.0\n#define MAX_GROUPS 64\n#define STRICT_MATCH 0.5/255.0\n\nvarying vec2 vUv;\nuniform sampler2D map;\nuniform sampler2D mergedTexture;\nuniform float groupCount;\nuniform float textureWidth;\nuniform float pixelsPerGroup;\n\nfloat colorGap(vec3 a, vec3 b) {\n  return abs(a.r - b.r) + abs(a.g - b.g) + abs(a.b - b.b);\n}\n\nvec4 readStyleColor(float groupIndex) {\n  float px = groupIndex * pixelsPerGroup;\n  float texX = (px + 0.5) / textureWidth;\n  return texture2D(mergedTexture, vec2(texX, 0.5));\n}\n\nvec4 readStyleToleranceHighlight(float groupIndex) {\n  float px = groupIndex * pixelsPerGroup + 1.0;\n  float texX = (px + 0.5) / textureWidth;\n  return texture2D(mergedTexture, vec2(texX, 0.5));\n}\n\nfloat readStyleOpacity(float groupIndex) {\n  float px = groupIndex * pixelsPerGroup + 2.0;\n  float texX = (px + 0.5) / textureWidth;\n  return texture2D(mergedTexture, vec2(texX, 0.5)).r;\n}\n\nfloat detectEdge(sampler2D map, vec2 uv, vec3 matchColor, float tolerance) {\n  vec4 centerColor = texture2D(map, uv);\n  if (colorGap(centerColor.rgb, matchColor) >= tolerance) return 0.0;\n  float step = 1.0 / RESOLUTION;\n  vec4 u = texture2D(map, uv + vec2(0.0, -step));\n  vec4 l = texture2D(map, uv + vec2(-step, 0.0));\n  vec4 r = texture2D(map, uv + vec2(step, 0.0));\n  vec4 d = texture2D(map, uv + vec2(0.0, step));\n  bool edge = colorGap(u.rgb, matchColor) >= tolerance || colorGap(l.rgb, matchColor) >= tolerance\n    || colorGap(r.rgb, matchColor) >= tolerance || colorGap(d.rgb, matchColor) >= tolerance;\n  return edge ? 1.0 : 0.0;\n}\n\nvoid main() {\n  vec4 image = texture2D(map, vUv);\n  if (image.r == 0.0 && image.g == 0.0 && image.b == 0.0) discard;\n\n  // WebGL 1.0 \u8981\u6C42\u5FAA\u73AF\u7EC8\u6B62\u6761\u4EF6\u5FC5\u987B\u662F\u7F16\u8BD1\u65F6\u5E38\u91CF\uFF0C\u6240\u4EE5\u7528 MAX_GROUPS\uFF0C\u5FAA\u73AF\u5185\u68C0\u67E5 groupCount\n  for (float i = 0.0; i < float(MAX_GROUPS); i += 1.0) {\n    if (i < groupCount) {\n      vec4 styleColor = readStyleColor(i);\n      vec3 colorRgb = styleColor.rgb;\n      float tol = readStyleToleranceHighlight(i).r * 3.0;\n      vec3 highlight = readStyleToleranceHighlight(i).gba;\n      float opacity = readStyleOpacity(i);\n      \n      if (opacity > 0.0) {\n        float gap = colorGap(image.rgb, colorRgb);\n        if (gap > STRICT_MATCH) continue;\n        float smoothRange = 0.01;\n        float matchFactor = 1.0 - smoothstep(tol - smoothRange, tol + smoothRange, gap);\n        if (matchFactor > 0.0) {\n          float isEdge = detectEdge(map, vUv, colorRgb, tol);\n          float alpha = mix(opacity, 1.0, isEdge);\n          alpha *= max(matchFactor, 0.9);\n          gl_FragColor = vec4(highlight, alpha);\n          return;\n        }\n      }\n    }\n  }\n  discard;\n}\n";

package/dist/PanoTagPlugin/controller/Tag/PolygonTag.d.ts

@@ -0,0 +1,112 @@
+import type PanoTagPluginController from '..';
+import type { TagContentType, Tag as TagData, TagInstance, ArrayPosition, TagClickParams } from '../..';
+import { BaseTag } from './BaseTag';
+import * as THREE from 'three';
+import type { PartialObjectDeep } from '../../../typings/typings';
+import type { Tag } from '../..';
+import { Polygon } from '../../../Sculpt/Objects/Polygon';
+export type PolygonTagInterface<C extends TagContentType = TagContentType> = TagInstance<C, 'Polygon'>;
+/**
+ * Polygon 类型的标签
+ * 使用 Sculpt Polygon 进行渲染
+ */
+export declare class PolygonTag<C extends TagContentType = TagContentType> extends BaseTag<C, 'Polygon'> {
+    polygonShape?: Polygon;
+    private tagStyle?;
+    private clickEventDispose?;
+    private domClickDispose?;
+    screenPosition: {
+        leftPx: number;
+        topPx: number;
+        scale: number;
+    } | null;
+    constructor(plugin: PanoTagPluginController, tagData: TagData);
+    /**
+     * 获取 Polygon 样式配置（合并用户配置和默认值）
+     */
+    private getPolygonStyle;
+    /**
+     * 更新 Polygon 样式
+     */
+    private updatePolygonStyle;
+    /**
+     * 更新标签数据
+     */
+    set(tag: PartialObjectDeep<Tag<C, 'Polygon'>>, deepMerge?: boolean): void;
+    /**
+     * 获取多边形的所有角点（世界坐标）
+     */
+    getCorners(): THREE.Vector3[];
+    getCenter(): ArrayPosition;
+    /**
+     * 计算多边形的法向量
+     * 使用前三个点来计算平面的法向量
+     */
+    computeNormal(): THREE.Vector3 | undefined;
+    /**
+     * 初始化 Sculpt Polygon
+     */
+    private initializeSculptPolygon;
+    /**
+     * 设置点击事件
+     */
+    private setupClickEvents;
+    /**
+     * 清理点击事件
+     */
+    private cleanupClickEvents;
+    /**
+     * 更新 Sculpt Polygon 的数据
+     */
+    private updateSculptPolygon;
+    /**
+     * 启用编辑器
+     * 用于编辑已存在的 Polygon
+     */
+    editorEnable(): Promise<void>;
+    /**
+     * 禁用编辑器
+     */
+    editorDisable(): void;
+    /**
+     * 同步 Sculpt Polygon 的数据到 PolygonPosition
+     */
+    private syncPolygonPositionFromSculpt;
+    /**
+     * @description 点击事件处理
+     */
+    onClick(params: Pick<TagClickParams, 'target'>): void;
+    /**
+     * @description 展开自己，收起其他标签
+     */
+    unfoldAndFoldOthers(): void;
+    /**
+     * 展开标签详情
+     */
+    unfold(): void;
+    /**
+     * 折叠标签详情
+     */
+    fold(): void;
+    /**
+     * 设置展开/折叠状态
+     */
+    setUnfold(unfolded: boolean): void;
+    /**
+     * 获取多边形的中心点
+     */
+    private getPolygonCenter;
+    /**
+     * 更新屏幕位置（用于在 2D UI 中显示内容）
+     * 显示在 Polygon 最右侧的顶点位置
+     */
+    updateScreenPosition(): void;
+    /**
+     * 应用可见性变化
+     */
+    applyVisible(): void;
+    /**
+     * 销毁标签
+     */
+    dispose(): void;
+}

package/dist/PanoTagPlugin/controller/TagRender.d.ts

@@ -1,6 +1,6 @@
 import type { TagObjectGroup, TagGLTFObjectGroup, ImagePlaneGroup, TagContentType, ElementRenderer, TagRendererMap, TagContentTypeMapping } from '../typings';
 import type { TemporaryState } from '../typings';
-import TagContainerSvelte from '../Components/TagContainer.svelte';
+import type TagContainerSvelte from '../Components/TagContainer.svelte';
 import type { Five } from '@realsee/five';
 import { TagUtil } from './TagUtil';
 export declare abstract class TagRender extends TagUtil {

package/dist/PanoTagPlugin/controller/index.d.ts

@@ -1,7 +1,7 @@
 import type { Tag, TagId, Tags, State, ContentTypeConfigKey } from '../typings';
 import type { TagClickParams, TagConfigByKey, TagContentType } from '..';
 import type { ArrayPosition } from '../typings';
-import { type Five } from '@realsee/five';
+import type { Five } from '@realsee/five';
 import { TagRender } from './TagRender';
 import type { PartialObjectDeep } from '../../typings/typings';
 export declare const pluginFlag: (name: string) => string;
@@ -28,8 +28,13 @@ declare class PanoTagPluginController extends TagRender {
     load(data: Tags): Promise<void>;
     /**
      * @description 添加标签
+     * @param tag 标签或标签数组
+     * @param options 可选配置
+     * @param options.updateMaskUrl 是否更新 mask。若为 true 且该 panoIndex 已有 Mask 标签，仅更新其 maskUrl（不变 color、style），并添加新标签
      */
-    addTag(tag: Tag | Tag[]): Promise<void>;
+    addTag(tag: Tag | Tag[], options?: {
+        updateMaskUrl?: boolean;
+    }): Promise<void>;
     /**
      * @description 改变配置
      */
@@ -103,6 +108,19 @@ declare class PanoTagPluginController extends TagRender {
      * @description 改变tag任意属性
      */
     changeTagById<C extends TagContentType = TagContentType>(id: TagId, tag: PartialObjectDeep<Tag<C>>, deepMerge?: boolean): void;
+    /**
+     * @description 批量更新指定点位的 Mask 图
+     * @param maskUpdates 包含点位索引和对应 mask 的数组
+     * @example
+     * changeMask([
+     *   { index: 0, mask: 'https://example.com/mask1.png' },
+     *   { index: 1, mask: canvasElement }
+     * ])
+     */
+    changeMask(maskUpdates: Array<{
+        index: number;
+        mask: string | HTMLCanvasElement;
+    }>): void;
     /**
      * @description 销毁tag
      */
@@ -166,6 +184,41 @@ declare class PanoTagPluginController extends TagRender {
      * @returns 是否为有效的 ArrayPosition
      */
     private isValidArrayPosition;
+    /**
+     * 更新当前点位的 Mask 标签
+     * Mask 标签仅在当前点位可见
+     */
+    private updateMaskTagsForCurrentPano;
+    /**
+     * 获取所有 Mask 类型的标签
+     */
+    get filterMaskTag(): (import("./Tag/BaseTag").BaseTag<"Panorama" | "Model" | "Custom" | "Audio" | "Text" | "ImageText" | "Image" | "Video" | "Link" | "Sticker" | "VRLink" | "PanoLink" | "Marketing" | "MediaPlane" | "MediaModel" | "Unknown", import("..").StickType> & {
+        [key: string]: any;
+    })[];
+    /**
+     * 获取 MaskTag 性能统计信息（用于性能监控和调试）
+     * @returns 性能统计信息
+     */
+    getMaskTagPerformanceStats(): {
+        totalMaskTags: number;
+        visibleMaskTags: number;
+        textureCache: {
+            totalCached: number;
+            totalRefCount: number;
+            estimatedMemoryMB: number;
+            cacheEntries: {
+                source: string;
+                refCount: number;
+                sizeMB: number;
+            }[];
+        };
+        currentPanoIndex: number;
+    };
+    /**
+     * 清理所有 MaskTag 纹理缓存（用于内存管理）
+     * 注意：这会释放所有纹理缓存，谨慎使用
+     */
+    clearMaskTagCache(): void;
 }
 export default PanoTagPluginController;
 export { PanoTagPluginController };