@realsee/dnalogel 3.77.3 → 3.78.0-alpha.0

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

@@ -0,0 +1,157 @@
+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';
+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, value: { texture: THREE.Texture, refCount: number, abortController?: AbortController }
+     */
+    private static maskTextureCache;
+    /**
+     * mask 图片 URL（2:1 全景图格式）
+     */
+    maskUrl: string;
+    /**
+     * 目标颜色（RGB 格式）
+     */
+    targetColor: [number, number, number];
+    /**
+     * mask 渲染的 mesh 对象（使用 Sphere）
+     */
+    maskMesh?: THREE.Mesh;
+    /**
+     * mask 纹理对象
+     */
+    private maskTexture?;
+    /**
+     * 是否正在加载 mask
+     */
+    private loadingMask;
+    /**
+     * 标签样式配置
+     */
+    private tagStyle?;
+    /**
+     * 点击事件清理函数
+     */
+    private clickEventDispose?;
+    constructor(plugin: PanoTagPluginController, tagData: TagData);
+    /**
+     * 计算法向量
+     * Mask 标签返回向上的法向量（因为是贴在 cube 面上）
+     */
+    computeNormal(): THREE.Vector3;
+    /**
+     * 更新标签数据
+     */
+    set(tag: PartialObjectDeep<Tag<C, 'Mask'>>, deepMerge?: boolean): void;
+    /**
+     * 重写 getVisible 方法
+     * Mask 标签仅在当前点位可见
+     */
+    getVisible(fiveState?: Partial<FiveState>): boolean;
+    /**
+     * 点击事件处理
+     */
+    onClick(params: Pick<TagClickParams, 'target'>): void;
+    /**
+     * 展开自己，收起其他标签
+     */
+    unfoldAndFoldOthers(): void;
+    /**
+     * 展开标签详情
+     */
+    unfold(): void;
+    /**
+     * 折叠标签详情
+     */
+    fold(): void;
+    /**
+     * 设置展开/折叠状态
+     */
+    setUnfold(unfolded: boolean): void;
+    /**
+     * 更新屏幕位置
+     */
+    updateScreenPosition(): void;
+    /**
+     * 应用可见性变化
+     */
+    applyVisible(): void;
+    /**
+     * 更新 mesh 的位置和旋转（跟随观察者）
+     * 参考 itemMask 实现
+     */
+    private updateMeshTransform;
+    /**
+     * 初始化 Mask Mesh（使用 Sphere）
+     */
+    private initializeMaskMesh;
+    /**
+     * 创建 Sphere mesh（参考 itemMask 实现）
+     */
+    private createSphereMesh;
+    /**
+     * 获取 Mask 样式配置（合并用户配置和默认值）
+     */
+    private getMaskStyle;
+    /**
+     * 设置点击事件
+     */
+    private setupClickEvents;
+    /**
+     * 清理点击事件
+     */
+    private cleanupClickEvents;
+    /**
+     * 重新加载 mask 图
+     */
+    private reloadMask;
+    /**
+     * 更新 mask 样式
+     */
+    private updateMaskStyle;
+    /**
+     * 销毁标签
+     */
+    dispose(): void;
+    /**
+     * 加载 Mask 纹理（静态方法，支持缓存和引用计数）
+     * @param maskUrl mask 图片 URL
+     * @returns Promise<THREE.Texture>
+     */
+    private static loadMaskTexture;
+    /**
+     * 释放 Mask 纹理（静态方法）
+     * @param maskUrl mask 图片 URL
+     */
+    private static releaseMaskTexture;
+    /**
+     * 获取当前缓存的纹理统计信息（用于性能监控和调试）
+     * @returns 缓存统计信息
+     */
+    static getCacheStats(): {
+        totalCached: number;
+        totalRefCount: number;
+        estimatedMemoryMB: number;
+        cacheEntries: Array<{
+            url: string;
+            refCount: number;
+            sizeMB: number;
+        }>;
+    };
+    /**
+     * 强制清理所有缓存的纹理（用于内存管理，谨慎使用）
+     * 注意：这会释放所有纹理，即使它们仍在使用中
+     */
+    static clearAllCache(): void;
+}

package/libs/PanoTagPlugin/controller/Tag/MaskTag.js

@@ -0,0 +1,492 @@
+var E = Object.defineProperty;
+var w = Object.getOwnPropertySymbols;
+var F = Object.prototype.hasOwnProperty, A = Object.prototype.propertyIsEnumerable;
+var T = (p, o, t) => o in p ? E(p, o, { enumerable: !0, configurable: !0, writable: !0, value: t }) : p[o] = t, M = (p, o) => {
+  for (var t in o || (o = {}))
+    F.call(o, t) && T(p, t, o[t]);
+  if (w)
+    for (var t of w(o))
+      A.call(o, t) && T(p, t, o[t]);
+  return p;
+};
+var u = (p, o, t) => (T(p, typeof o != "symbol" ? o + "" : o, t), t);
+var C = (p, o, t) => new Promise((e, i) => {
+  var s = (a) => {
+    try {
+      r(t.next(a));
+    } catch (c) {
+      i(c);
+    }
+  }, h = (a) => {
+    try {
+      r(t.throw(a));
+    } catch (c) {
+      i(c);
+    }
+  }, r = (a) => a.done ? e(a.value) : Promise.resolve(a.value).then(s, h);
+  r((t = t.apply(p, o)).next());
+});
+import { BaseTag as P } from "./BaseTag.js";
+import * as n from "three";
+import { maskVertexShader as V, maskFragmentShader as z } from "./MaskTag.shaders.js";
+import "../../../shared-utils/Subscribe.js";
+import "../../utils/tag/calculateTagConfig.js";
+import "../../../vendor/object-assign-deep/objectAssignDeep.js";
+import "../../../shared-utils/typescript/entries.js";
+import "../../utils/tag/adaptConfig.js";
+import "../../typings/tag/TagConfig.js";
+import "@realsee/five";
+import "../../../shared-utils/tag.js";
+import "../../../shared-utils/positionToVector3.js";
+import "../../../shared-utils/five/vector3ToScreen.js";
+import "../../../shared-utils/five/getFiveModel.js";
+import "../../../shared-utils/Utils/FiveUtil.js";
+import "../../../shared-utils/Utils/BaseUtil.js";
+import "../../../shared-utils/Utils/WorkUtil.js";
+import "../../../shared-utils/five/transformPosition.js";
+import "../../../shared-utils/three/temp.js";
+import "../../../shared-utils/three/core/Raycaster.js";
+import "../../../shared-utils/dom/resizeObserver.js";
+import "../../../shared-utils/five/fiveEveryReadyListener.js";
+import "../../../shared-utils/throttle.js";
+import "../../../vendor/hammerjs/hammer.js";
+import "../../../shared-utils/three/PointSelector/index.js";
+import "../../../shared-utils/three/PointSelector/utils/PointSelectorHelper.js";
+import "../../../shared-utils/three/Magnifier.js";
+import "../../../shared-utils/three/PointSelector/utils/PointHelper.js";
+import "../../../shared-utils/three/Assets/index.js";
+import "../../../CSS3DRenderPlugin/utils/three/CSS3DObject.js";
+import "../../../shared-utils/even.js";
+import "../../../shared-utils/CSS3DRender/OpacityMesh.js";
+import "../../../shared-utils/three/centerPoint.js";
+import "../../../shared-utils/three/getObjectVisible.js";
+import "../../../shared-utils/three/CSS3DRenderer/index.js";
+import "../../../CSS3DRenderPlugin/utils/generateBehindFiveElement.js";
+import "@realsee/five/line";
+import "../../../shared-utils/isNil.js";
+import "../../../shared-utils/three/core/Five_LineMaterial2.js";
+import "../../../shared-utils/three/core/Sphere.js";
+import "../../../shared-utils/three/blink.js";
+import "../../../vendor/animejs/lib/anime.es.js";
+import "../../../shared-utils/util.js";
+import "../../../vendor/@tweenjs/tween/dist/tween.esm.js.js";
+import "../../../CSS3DRenderPlugin/utils/three/CSS3DRender.js";
+import "../../../shared-utils/CSS3DRender/CSS3DRenderer.js";
+import "../../../shared-utils/createResizeObserver.js";
+import "../../../CSS3DRenderPlugin/utils/three/CSS3DScene.js";
+import "../../../CSS3DRenderPlugin/utils/getAllCSS3DObject.js";
+import "../../../CSS3DRenderPlugin/utils/three/CSS3DGroup.js";
+import "../../../shared-utils/three/PointSelector/utils/html.js";
+import "../../../shared-utils/CSS3DRender/index.js";
+import "../../../shared-utils/five/fiveModelLoad.js";
+import "../../../shared-utils/three/PointSelector/utils/PointHelper2.js";
+import "../../../Sculpt/Meshes/Line.js";
+import "../../../Sculpt/typings/style.js";
+import "../../../shared-utils/three/IObject3D.js";
+import "../../../Sculpt/utils/Meshes/getLengthHTML.js";
+import "../../../shared-utils/three/applyObjectMatrixWorld.js";
+import "../../../shared-utils/three/core/LineGeometry.js";
+import "../../../shared-utils/three/core/LineMaterial.js";
+import "../../../shared-utils/three/core/Line2.js";
+import "../../../shared-utils/three/core/LineMaterial2.js";
+import "../../../Sculpt/utils/unit.js";
+import "../../../Sculpt/utils/renderDom.js";
+import "../../../vendor/earcut/src/earcut.js";
+import "../../../shared-utils/five/FivePuppet.js";
+import "../../../CSS3DRenderPlugin/utils/three/CSS3DSprite.js";
+import "../../../shared-utils/isTouchDevice.js";
+import "../../../shared-utils/five/getPosition.js";
+import "../../../shared-utils/five/getRaycasterByNdcPosition.js";
+import "../../../shared-utils/three/PointSelector/utils/contents.js";
+import "../../../Sculpt/utils/three/rayOnLine.js";
+import "../../../shared-utils/five/mode.js";
+import "../../utils/tag/format.js";
+import "../../../shared-utils/url/defaultUrls.js";
+import "../../../shared-utils/vectorToCoordinate.js";
+import "../../../shared-utils/formatRad.js";
+import "../../../shared-utils/five/lookPoint.js";
+import "../../../shared-utils/uuid.js";
+import "../../utils/tagPosition.js";
+import "../../utils/tag/tagCheck.js";
+import "../../utils/checkRange.js";
+import "../../../shared-utils/url/getUrl.js";
+import "../../../shared-utils/five/getFloorIndex.js";
+import "../../../shared-utils/safeObj.js";
+import "../../utils/Cache.js";
+import "../../../shared-utils/promise/withResolvers.js";
+const l = class extends P {
+  constructor(t, e) {
+    super(t, e);
+    /**
+     * mask 图片 URL（2:1 全景图格式）
+     */
+    u(this, "maskUrl");
+    /**
+     * 目标颜色（RGB 格式）
+     */
+    u(this, "targetColor");
+    /**
+     * mask 渲染的 mesh 对象（使用 Sphere）
+     */
+    u(this, "maskMesh");
+    /**
+     * mask 纹理对象
+     */
+    u(this, "maskTexture");
+    /**
+     * 是否正在加载 mask
+     */
+    u(this, "loadingMask", !1);
+    /**
+     * 标签样式配置
+     */
+    u(this, "tagStyle");
+    /**
+     * 点击事件清理函数
+     */
+    u(this, "clickEventDispose");
+    this.maskUrl = e.mask || "";
+    const i = e.color;
+    Array.isArray(i) ? this.targetColor = i : typeof i == "number" ? this.targetColor = [i >> 16 & 255, i >> 8 & 255, i & 255] : this.targetColor = [0, 0, 0], this.tagStyle = e.style, this.updateVisible(), this.currentVisible && this.initializeMaskMesh();
+  }
+  /**
+   * 计算法向量
+   * Mask 标签返回向上的法向量（因为是贴在 cube 面上）
+   */
+  computeNormal() {
+    return new n.Vector3(0, 1, 0);
+  }
+  /**
+   * 更新标签数据
+   */
+  set(t, e = !0) {
+    if (super.set(t, e), t.style && (this.tagStyle = M(M({}, this.tagStyle), t.style)), t.mask && (this.maskUrl = t.mask, this.reloadMask()), t.color) {
+      const i = t.color;
+      Array.isArray(i) ? this.targetColor = i : typeof i == "number" && (this.targetColor = [i >> 16 & 255, i >> 8 & 255, i & 255]), this.updateMaskStyle();
+    }
+  }
+  /**
+   * 重写 getVisible 方法
+   * Mask 标签仅在当前点位可见
+   */
+  getVisible(t) {
+    var s;
+    if (!this.enabled || !this.plugin.state.enabled || !this.fiveUtil.model)
+      return !1;
+    const e = M(M({}, this.five.getCurrentState()), t), { panoIndex: i } = e;
+    return i !== ((s = this.fiveState) == null ? void 0 : s.panoIndex) ? !1 : super.getVisible(e);
+  }
+  /**
+   * 点击事件处理
+   */
+  onClick(t) {
+    t.target === "TagMaskModel" && this.unfoldAndFoldOthers();
+  }
+  /**
+   * 展开自己，收起其他标签
+   */
+  unfoldAndFoldOthers() {
+    if (this.isPopoverConfigEnabled())
+      return;
+    const t = this.can("fold"), e = this.can("unfold");
+    t && e && (this.state.unfolded = !this.state.unfolded, this.manuallyOperated = !0, this.plugin.addRenderQueue({ type: "TagContainerSvelte", keys: ["tags"] }), this.state.unfolded && this.plugin.tags.forEach((i) => {
+      i.id !== this.id && i.fold();
+    }));
+  }
+  /**
+   * 展开标签详情
+   */
+  unfold() {
+    this.isPopoverConfigEnabled() || this.setUnfold(!0);
+  }
+  /**
+   * 折叠标签详情
+   */
+  fold() {
+    this.isPopoverConfigEnabled() || this.setUnfold(!1);
+  }
+  /**
+   * 设置展开/折叠状态
+   */
+  setUnfold(t) {
+    if (this.isPopoverConfigEnabled())
+      return;
+    const e = this.can("fold"), i = this.can("unfold");
+    e && i && (this.state.unfolded = t, this.hooks.emit(t ? "unfolded" : "folded"), this.plugin.addRenderQueue({ type: "TagContainerSvelte", keys: ["tags"] }));
+  }
+  /**
+   * 更新屏幕位置
+   */
+  updateScreenPosition() {
+    if (!this.currentVisible || !this.position || !Array.isArray(this.position)) {
+      this.screenPosition = null, this.plugin.addRenderQueue({ type: "TagContainerSvelte", keys: ["tags"] });
+      return;
+    }
+    const e = new n.Vector3(...this.position).clone().project(this.five.camera);
+    if (this.five.renderer) {
+      const i = this.five.renderer.getSize(new n.Vector2());
+      this.screenPosition = {
+        leftPx: (e.x + 1) / 2 * i.x,
+        topPx: (-e.y + 1) / 2 * i.y,
+        scale: 1
+      };
+    }
+    this.plugin.addRenderQueue({ type: "TagContainerSvelte", keys: ["tags"] });
+  }
+  /**
+   * 应用可见性变化
+   */
+  applyVisible() {
+    this.visible && !this.maskMesh && !this.loadingMask && this.initializeMaskMesh(), this.maskMesh && (this.maskMesh.visible = this.visible, this.updateMeshTransform()), this.updateScreenPosition();
+  }
+  /**
+   * 更新 mesh 的位置和旋转（跟随观察者）
+   * 参考 itemMask 实现
+   */
+  updateMeshTransform() {
+    var i;
+    if (!this.maskMesh)
+      return;
+    const t = (i = this.fiveState) == null ? void 0 : i.panoIndex;
+    if (t === void 0)
+      return;
+    const e = this.workUtil.getObserver(t);
+    e && (this.maskMesh.position.copy(e.position), this.maskMesh.quaternion.copy(e.quaternion), this.five.needsRender = !0);
+  }
+  /**
+   * 初始化 Mask Mesh（使用 Sphere）
+   */
+  initializeMaskMesh() {
+    return C(this, null, function* () {
+      if (this.maskMesh || this.loadingMask || !this.maskUrl)
+        return;
+      this.loadingMask = !0;
+      const t = performance.now();
+      try {
+        this.maskTexture = yield l.loadMaskTexture(this.maskUrl), this.maskMesh = this.createSphereMesh(this.maskTexture), this.plugin.imagePlaneGroup.add(this.maskMesh), this.applyVisible(), this.five.needsRender = !0, this.setupClickEvents(), this.updateScreenPosition();
+        const e = performance.now() - t;
+        console.log(`[MaskTag Performance] Mesh initialized in ${e.toFixed(2)}ms for tag ${this.id}`);
+      } catch (e) {
+        console.error("[MaskTag] Failed to initialize mask mesh:", e);
+      } finally {
+        this.loadingMask = !1;
+      }
+    });
+  }
+  /**
+   * 创建 Sphere mesh（参考 itemMask 实现）
+   */
+  createSphereMesh(t) {
+    const e = this.getMaskStyle(), i = new n.Vector4(this.targetColor[0] / 255, this.targetColor[1] / 255, this.targetColor[2] / 255, 1), s = new n.ShaderMaterial({
+      vertexShader: V,
+      fragmentShader: z,
+      uniforms: {
+        map: { value: t },
+        color: { value: i },
+        tolerance: { value: e.tolerance / 255 },
+        // 归一化容差
+        highlightColor: {
+          value: new n.Vector3(e.highlightColor[0] / 255, e.highlightColor[1] / 255, e.highlightColor[2] / 255)
+        },
+        opacity: { value: e.opacity }
+      },
+      depthWrite: !1,
+      depthTest: !1,
+      transparent: !0
+    }), h = new n.SphereGeometry(1, 60, 40);
+    h.rotateY(-Math.PI / 2), h.scale(-1, 1, 1);
+    const r = new n.Mesh(h, s);
+    r.renderOrder = -1e3;
+    let a = null;
+    const c = () => {
+      if (a)
+        return a;
+      if (!t.image)
+        return null;
+      try {
+        const m = document.createElement("canvas"), k = m.getContext("2d");
+        if (!k)
+          return null;
+        const d = t.image;
+        return m.width = d.width, m.height = d.height, k.drawImage(d, 0, 0), a = k.getImageData(0, 0, d.width, d.height), a;
+      } catch (m) {
+        return console.error("[MaskTag] Failed to get image data:", m), null;
+      }
+    }, g = r.raycast.bind(r);
+    return r.raycast = (m, k) => {
+      const d = [];
+      if (g(m, d), d.length > 0) {
+        const y = d[0];
+        if (y.uv && t.image) {
+          const f = c();
+          if (f) {
+            const S = Math.floor(y.uv.x * f.width), v = (Math.floor((1 - y.uv.y) * f.height) * f.width + S) * 4, x = [f.data[v], f.data[v + 1], f.data[v + 2]];
+            Math.abs(x[0] / 255 - this.targetColor[0] / 255) + Math.abs(x[1] / 255 - this.targetColor[1] / 255) + Math.abs(x[2] / 255 - this.targetColor[2] / 255) < e.tolerance && k.push(y);
+          }
+        }
+      }
+    }, r.__maskTag = this.id, r.__maskMesh = !0, r;
+  }
+  /**
+   * 获取 Mask 样式配置（合并用户配置和默认值）
+   */
+  getMaskStyle() {
+    var i, s, h;
+    const t = ((i = this.tagStyle) == null ? void 0 : i.mask) || {};
+    let e = [86, 134, 253];
+    return t.color ? Array.isArray(t.color) ? e = t.color : typeof t.color == "number" && (e = [t.color >> 16 & 255, t.color >> 8 & 255, t.color & 255]) : t.highlightColor && (Array.isArray(t.highlightColor) ? e = t.highlightColor : typeof t.highlightColor == "number" && (e = [t.highlightColor >> 16 & 255, t.highlightColor >> 8 & 255, t.highlightColor & 255])), {
+      tolerance: (s = t.tolerance) != null ? s : 1e-3,
+      // 参考 itemMask 默认 0.001（归一化后的值）
+      highlightColor: e,
+      opacity: (h = t.opacity) != null ? h : 0.6
+      // 默认 0.6（用于填充区域）
+    };
+  }
+  /**
+   * 设置点击事件
+   */
+  setupClickEvents() {
+    if (!this.maskMesh || this.config.clickable === !1)
+      return;
+    this.cleanupClickEvents();
+    const t = (e) => {
+      this.plugin.hooks.emit("click", { event: e, target: "TagMaskModel", tag: this });
+    };
+    requestAnimationFrame(() => {
+      !this.maskMesh || !this.plugin.domEvents || (this.clickEventDispose = this.addObjectClickHandler(this, this.maskMesh, t));
+    });
+  }
+  /**
+   * 清理点击事件
+   */
+  cleanupClickEvents() {
+    this.clickEventDispose && (this.clickEventDispose(), this.clickEventDispose = void 0);
+  }
+  /**
+   * 重新加载 mask 图
+   */
+  reloadMask() {
+    return C(this, null, function* () {
+      this.maskMesh && (this.maskMesh.parent && this.maskMesh.parent.remove(this.maskMesh), this.maskMesh.geometry.dispose(), this.maskMesh.material && (Array.isArray(this.maskMesh.material) ? this.maskMesh.material.forEach((t) => t.dispose()) : this.maskMesh.material.dispose()), this.maskMesh = void 0), this.maskTexture && this.maskUrl && (l.releaseMaskTexture(this.maskUrl), this.maskTexture = void 0), yield this.initializeMaskMesh();
+    });
+  }
+  /**
+   * 更新 mask 样式
+   */
+  updateMaskStyle() {
+    if (!this.maskMesh)
+      return;
+    const t = this.getMaskStyle(), e = this.maskMesh.material;
+    e.uniforms && (e.uniforms.color.value.set(this.targetColor[0] / 255, this.targetColor[1] / 255, this.targetColor[2] / 255, 1), e.uniforms.tolerance.value = t.tolerance / 255, e.uniforms.highlightColor.value.set(
+      t.highlightColor[0] / 255,
+      t.highlightColor[1] / 255,
+      t.highlightColor[2] / 255
+    ), e.uniforms.opacity.value = t.opacity), this.five.needsRender = !0;
+  }
+  /**
+   * 销毁标签
+   */
+  dispose() {
+    this.cleanupClickEvents(), this.maskMesh && (this.maskMesh.parent && this.maskMesh.parent.remove(this.maskMesh), this.maskMesh.geometry.dispose(), this.maskMesh.material && (Array.isArray(this.maskMesh.material) ? this.maskMesh.material.forEach((t) => t.dispose()) : this.maskMesh.material.dispose()), this.maskMesh = void 0), this.maskTexture && this.maskUrl && (l.releaseMaskTexture(this.maskUrl), this.maskTexture = void 0);
+  }
+  /**
+   * 加载 Mask 纹理（静态方法，支持缓存和引用计数）
+   * @param maskUrl mask 图片 URL
+   * @returns Promise<THREE.Texture>
+   */
+  static loadMaskTexture(t) {
+    return C(this, null, function* () {
+      const e = l.maskTextureCache.get(t);
+      if (e)
+        return e.refCount++, e.texture;
+      const i = performance.now(), s = new AbortController(), h = new n.TextureLoader();
+      try {
+        const r = yield new Promise((c, g) => {
+          if (s.signal.aborted) {
+            g(new Error("Load aborted"));
+            return;
+          }
+          h.load(
+            t,
+            (m) => {
+              s.signal.aborted ? (m.dispose(), g(new Error("Load aborted"))) : c(m);
+            },
+            void 0,
+            (m) => {
+              g(m);
+            }
+          ), s.signal.addEventListener("abort", () => {
+            g(new Error("Load aborted"));
+          });
+        });
+        r.wrapS = n.ClampToEdgeWrapping, r.wrapT = n.ClampToEdgeWrapping, r.minFilter = n.LinearFilter, r.magFilter = n.LinearFilter, r.anisotropy = 4, l.maskTextureCache.set(t, {
+          texture: r,
+          refCount: 1,
+          abortController: s
+        });
+        const a = performance.now() - i;
+        if (console.log(`[MaskTag Performance] Texture loaded in ${a.toFixed(2)}ms, URL: ${t.substring(0, 50)}...`), r.image) {
+          const c = (r.image.width * r.image.height * 4 / 1048576).toFixed(2);
+          console.log(`[MaskTag Memory] Texture size: ${r.image.width}x${r.image.height}, estimated memory: ${c}MB`);
+        }
+        return r;
+      } catch (r) {
+        throw console.error("[MaskTag] Failed to load mask texture:", t, r), r;
+      }
+    });
+  }
+  /**
+   * 释放 Mask 纹理（静态方法）
+   * @param maskUrl mask 图片 URL
+   */
+  static releaseMaskTexture(t) {
+    var i;
+    const e = l.maskTextureCache.get(t);
+    e && (e.refCount--, e.refCount <= 0 && (console.log(`[MaskTag Memory] Releasing texture (refCount=0): ${t.substring(0, 50)}...`), (i = e.abortController) == null || i.abort(), e.texture.dispose(), l.maskTextureCache.delete(t)));
+  }
+  /**
+   * 获取当前缓存的纹理统计信息（用于性能监控和调试）
+   * @returns 缓存统计信息
+   */
+  static getCacheStats() {
+    let t = 0, e = 0;
+    const i = [];
+    return l.maskTextureCache.forEach((s, h) => {
+      t += s.refCount;
+      let r = 0;
+      if (s.texture.image) {
+        const a = s.texture.image.width || 0, c = s.texture.image.height || 0;
+        r = a * c * 4 / (1024 * 1024), e += r;
+      }
+      i.push({
+        url: h.substring(0, 80),
+        refCount: s.refCount,
+        sizeMB: parseFloat(r.toFixed(2))
+      });
+    }), {
+      totalCached: l.maskTextureCache.size,
+      totalRefCount: t,
+      estimatedMemoryMB: parseFloat(e.toFixed(2)),
+      cacheEntries: i
+    };
+  }
+  /**
+   * 强制清理所有缓存的纹理（用于内存管理，谨慎使用）
+   * 注意：这会释放所有纹理，即使它们仍在使用中
+   */
+  static clearAllCache() {
+    console.warn("[MaskTag] Clearing all texture cache"), l.maskTextureCache.forEach((t) => {
+      var e;
+      (e = t.abortController) == null || e.abort(), t.texture.dispose();
+    }), l.maskTextureCache.clear();
+  }
+};
+let b = l;
+/**
+ * Mask 纹理缓存（静态，所有 MaskTag 实例共享）
+ * key: mask URL, value: { texture: THREE.Texture, refCount: number, abortController?: AbortController }
+ */
+u(b, "maskTextureCache", /* @__PURE__ */ new Map());
+export {
+  b as MaskTag
+};

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

@@ -0,0 +1,13 @@
+/**
+ * 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";
+/**
+ * Fragment Shader
+ * 实现颜色匹配和高亮渲染逻辑
+ */
+export declare const maskFragmentShader = "\n#extension GL_OES_standard_derivatives : enable\n\nvarying vec2 vUv;\nuniform sampler2D map;\nuniform vec4 color;\nuniform float tolerance;\nuniform vec3 highlightColor;\nuniform float opacity;\n\nfloat colorGap(vec3 color1, vec3 color2) {\n  float gap = abs(color1.r - color2.r) + abs(color1.g - color2.g) + abs(color1.b - color2.b);\n  return gap;\n}\n\nvoid main() {\n  vec4 image = texture2D(map, vUv);\n  \n  // \u8BA1\u7B97\u5F53\u524D\u50CF\u7D20\u4E0E\u76EE\u6807\u989C\u8272\u7684\u5DEE\u5F02\n  float gap = colorGap(image.rgb, color.rgb);\n  \n  // \u6392\u9664\u9ED1\u8272\u50CF\u7D20\n  if (image.r == 0.0 && image.g == 0.0 && image.b == 0.0) {\n    discard;\n  }\n  \n  // \u4F7F\u7528 fwidth \u8BA1\u7B97\u68AF\u5EA6\uFF0C\u5B9E\u73B0\u5E73\u6ED1\u7684\u989C\u8272\u5339\u914D\u8FB9\u754C\n  #ifdef GL_OES_standard_derivatives\n    float smoothRange = fwidth(gap) * 3.0;\n  #else\n    float smoothRange = 0.01;\n  #endif\n  \n  // \u5E73\u6ED1\u7684\u989C\u8272\u5339\u914D\u56E0\u5B50\uFF080-1\uFF09\n  float matchFactor = 1.0 - smoothstep(tolerance - smoothRange, tolerance + smoothRange, gap);\n  \n  if (matchFactor > 0.0) {\n    // \u68C0\u6D4B\u8FB9\u7F18\uFF1A\u91C7\u6837\u5468\u56F4\u50CF\u7D20\n    float edgeWidth = 0.004;\n    \n    vec4 colorLeft = texture2D(map, vUv + vec2(-edgeWidth, 0.0));\n    vec4 colorRight = texture2D(map, vUv + vec2(edgeWidth, 0.0));\n    vec4 colorUp = texture2D(map, vUv + vec2(0.0, -edgeWidth));\n    vec4 colorDown = texture2D(map, vUv + vec2(0.0, edgeWidth));\n    \n    // \u8BA1\u7B97\u8FB9\u7F18\u5F3A\u5EA6\n    float edgeStrength = 0.0;\n    \n    if (colorGap(colorLeft.rgb, color.rgb) >= tolerance || (colorLeft.r == 0.0 && colorLeft.g == 0.0 && colorLeft.b == 0.0)) {\n      edgeStrength += 0.25;\n    }\n    if (colorGap(colorRight.rgb, color.rgb) >= tolerance || (colorRight.r == 0.0 && colorRight.g == 0.0 && colorRight.b == 0.0)) {\n      edgeStrength += 0.25;\n    }\n    if (colorGap(colorUp.rgb, color.rgb) >= tolerance || (colorUp.r == 0.0 && colorUp.g == 0.0 && colorUp.b == 0.0)) {\n      edgeStrength += 0.25;\n    }\n    if (colorGap(colorDown.rgb, color.rgb) >= tolerance || (colorDown.r == 0.0 && colorDown.g == 0.0 && colorDown.b == 0.0)) {\n      edgeStrength += 0.25;\n    }\n    \n    // \u8FB9\u7F18\u5E73\u6ED1\u8FC7\u6E21\uFF1AedgeStrength \u8D8A\u5927\u8D8A\u63A5\u8FD1\u8FB9\u7F18\n    float alpha = mix(opacity, 1.0, smoothstep(0.0, 0.3, edgeStrength));\n    \n    // \u5E94\u7528\u5339\u914D\u56E0\u5B50\uFF08\u5E73\u6ED1\u989C\u8272\u8FB9\u754C\uFF09\n    alpha *= matchFactor;\n    \n    gl_FragColor = vec4(highlightColor, alpha);\n  } else {\n    discard;\n  }\n}\n";