@realsee/dnalogel 3.78.0-alpha.0 → 3.78.0-alpha.2

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

@@ -9,5 +9,8 @@ export declare const maskVertexShader = "\nvarying vec2 vUv;\nvoid main() {\n  v
 /**
  * Fragment Shader
  * 实现颜色匹配和高亮渲染逻辑
+ * 参考 MosaicPlugin 的边缘检测实现
  */
-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";
+export declare const maskFragmentShader = "\n#define RESOLUTION 2048.0\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\n// \u5224\u65AD\u50CF\u7D20\u662F\u5426\u5339\u914D\u76EE\u6807\u989C\u8272\nbool isMatchingColor(vec3 pixelColor) {\n  // \u6392\u9664\u9ED1\u8272\u50CF\u7D20\n  if (pixelColor.r == 0.0 && pixelColor.g == 0.0 && pixelColor.b == 0.0) {\n    return false;\n  }\n  return colorGap(pixelColor, color.rgb) < tolerance;\n}\n\n// \u8FB9\u7F18\u68C0\u6D4B\u51FD\u6570\uFF1A\u53C2\u8003 MosaicPlugin \u5B9E\u73B0\nfloat detectEdge(sampler2D map, vec2 uv) {\n  vec4 centerColor = texture2D(map, uv);\n  \n  // \u5F53\u524D\u50CF\u7D20\u5FC5\u987B\u5339\u914D\u76EE\u6807\u989C\u8272\n  if (!isMatchingColor(centerColor.rgb)) {\n    return 0.0;\n  }\n  \n  float step = 1.0 / RESOLUTION;\n  \n  // \u68C0\u67E54\u4E2A\u4E3B\u8981\u65B9\u5411\u7684\u90BB\u5C45\u50CF\u7D20\n  vec4 upColor = texture2D(map, uv + vec2(0.0, -step));\n  vec4 leftColor = texture2D(map, uv + vec2(-step, 0.0));\n  vec4 rightColor = texture2D(map, uv + vec2(step, 0.0));\n  vec4 downColor = texture2D(map, uv + vec2(0.0, step));\n  \n  // \u53EA\u6709\u5F53\u524D\u50CF\u7D20\u5339\u914D\u989C\u8272\uFF0C\u4E14\u81F3\u5C11\u6709\u4E00\u4E2A\u90BB\u5C45\u4E0D\u5339\u914D\u65F6\uFF0C\u624D\u662F\u8FB9\u7F18\n  bool hasNonMatchingNeighbor = \n    !isMatchingColor(upColor.rgb) || \n    !isMatchingColor(leftColor.rgb) || \n    !isMatchingColor(rightColor.rgb) || \n    !isMatchingColor(downColor.rgb);\n  \n  return hasNonMatchingNeighbor ? 1.0 : 0.0;\n}\n\nvoid main() {\n  vec4 image = texture2D(map, vUv);\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  // \u8BA1\u7B97\u5F53\u524D\u50CF\u7D20\u4E0E\u76EE\u6807\u989C\u8272\u7684\u5DEE\u5F02\n  float gap = colorGap(image.rgb, color.rgb);\n  \n  // \u4F7F\u7528\u56FA\u5B9A\u5E73\u6ED1\u8303\u56F4\u5B9E\u73B0\u989C\u8272\u5339\u914D\u8FB9\u754C\n  float smoothRange = 0.01;\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    // \u4F7F\u7528\u65B0\u7684\u8FB9\u7F18\u68C0\u6D4B\u65B9\u6CD5\n    float isEdge = detectEdge(map, vUv);\n    \n    // \u8FB9\u7F18\u4F7F\u7528\u5B8C\u5168\u4E0D\u900F\u660E\uFF0C\u5185\u90E8\u4F7F\u7528\u8BBE\u5B9A\u7684\u900F\u660E\u5EA6\n    float alpha = mix(opacity, 1.0, isEdge);\n    \n    // \u5E94\u7528\u5339\u914D\u56E0\u5B50\u5B9E\u73B0\u8FB9\u754C\u5E73\u6ED1\uFF0C\u4F46\u4FDD\u7559\u6700\u5C0F 0.9 \u7684\u900F\u660E\u5EA6\n    // \u8FD9\u6837\u5373\u4F7F\u5728\u8FB9\u754C\u5904\u4E5F\u4E0D\u4F1A\u5B8C\u5168\u900F\u660E\uFF0C\u540C\u65F6\u5B8C\u5168\u5339\u914D\u533A\u57DF\u4FDD\u6301\u8BBE\u5B9A\u7684\u900F\u660E\u5EA6\n    alpha *= max(matchFactor, 0.9);\n    \n    gl_FragColor = vec4(highlightColor, alpha);\n  } else {\n    discard;\n  }\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/libs/PanoTagPlugin/controller/Tag/MaskTag.shaders.js

@@ -1,4 +1,4 @@
-const o = (
+const e = (
   /* glsl */
   `
 varying vec2 vUv;
@@ -7,10 +7,10 @@ void main() {
   gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
 }
 `
-), e = (
+), o = (
   /* glsl */
   `
-#extension GL_OES_standard_derivatives : enable
+#define RESOLUTION 2048.0
 
 varying vec2 vUv;
 uniform sampler2D map;
@@ -24,57 +24,69 @@ float colorGap(vec3 color1, vec3 color2) {
   return gap;
 }
 
+// 判断像素是否匹配目标颜色
+bool isMatchingColor(vec3 pixelColor) {
+  // 排除黑色像素
+  if (pixelColor.r == 0.0 && pixelColor.g == 0.0 && pixelColor.b == 0.0) {
+    return false;
+  }
+  return colorGap(pixelColor, color.rgb) < tolerance;
+}
+
+// 边缘检测函数：参考 MosaicPlugin 实现
+float detectEdge(sampler2D map, vec2 uv) {
+  vec4 centerColor = texture2D(map, uv);
+  
+  // 当前像素必须匹配目标颜色
+  if (!isMatchingColor(centerColor.rgb)) {
+    return 0.0;
+  }
+  
+  float step = 1.0 / RESOLUTION;
+  
+  // 检查4个主要方向的邻居像素
+  vec4 upColor = texture2D(map, uv + vec2(0.0, -step));
+  vec4 leftColor = texture2D(map, uv + vec2(-step, 0.0));
+  vec4 rightColor = texture2D(map, uv + vec2(step, 0.0));
+  vec4 downColor = texture2D(map, uv + vec2(0.0, step));
+  
+  // 只有当前像素匹配颜色，且至少有一个邻居不匹配时，才是边缘
+  bool hasNonMatchingNeighbor = 
+    !isMatchingColor(upColor.rgb) || 
+    !isMatchingColor(leftColor.rgb) || 
+    !isMatchingColor(rightColor.rgb) || 
+    !isMatchingColor(downColor.rgb);
+  
+  return hasNonMatchingNeighbor ? 1.0 : 0.0;
+}
+
 void main() {
   vec4 image = texture2D(map, vUv);
   
-  // 计算当前像素与目标颜色的差异
-  float gap = colorGap(image.rgb, color.rgb);
-  
   // 排除黑色像素
   if (image.r == 0.0 && image.g == 0.0 && image.b == 0.0) {
     discard;
   }
   
-  // 使用 fwidth 计算梯度，实现平滑的颜色匹配边界
-  #ifdef GL_OES_standard_derivatives
-    float smoothRange = fwidth(gap) * 3.0;
-  #else
-    float smoothRange = 0.01;
-  #endif
+  // 计算当前像素与目标颜色的差异
+  float gap = colorGap(image.rgb, color.rgb);
+  
+  // 使用固定平滑范围实现颜色匹配边界
+  float smoothRange = 0.01;
   
   // 平滑的颜色匹配因子（0-1）
   float matchFactor = 1.0 - smoothstep(tolerance - smoothRange, tolerance + smoothRange, gap);
   
   if (matchFactor > 0.0) {
-    // 检测边缘：采样周围像素
-    float edgeWidth = 0.004;
-    
-    vec4 colorLeft = texture2D(map, vUv + vec2(-edgeWidth, 0.0));
-    vec4 colorRight = texture2D(map, vUv + vec2(edgeWidth, 0.0));
-    vec4 colorUp = texture2D(map, vUv + vec2(0.0, -edgeWidth));
-    vec4 colorDown = texture2D(map, vUv + vec2(0.0, edgeWidth));
-    
-    // 计算边缘强度
-    float edgeStrength = 0.0;
-    
-    if (colorGap(colorLeft.rgb, color.rgb) >= tolerance || (colorLeft.r == 0.0 && colorLeft.g == 0.0 && colorLeft.b == 0.0)) {
-      edgeStrength += 0.25;
-    }
-    if (colorGap(colorRight.rgb, color.rgb) >= tolerance || (colorRight.r == 0.0 && colorRight.g == 0.0 && colorRight.b == 0.0)) {
-      edgeStrength += 0.25;
-    }
-    if (colorGap(colorUp.rgb, color.rgb) >= tolerance || (colorUp.r == 0.0 && colorUp.g == 0.0 && colorUp.b == 0.0)) {
-      edgeStrength += 0.25;
-    }
-    if (colorGap(colorDown.rgb, color.rgb) >= tolerance || (colorDown.r == 0.0 && colorDown.g == 0.0 && colorDown.b == 0.0)) {
-      edgeStrength += 0.25;
-    }
+    // 使用新的边缘检测方法
+    float isEdge = detectEdge(map, vUv);
     
-    // 边缘平滑过渡：edgeStrength 越大越接近边缘
-    float alpha = mix(opacity, 1.0, smoothstep(0.0, 0.3, edgeStrength));
+    // 边缘使用完全不透明，内部使用设定的透明度
+    float alpha = mix(opacity, 1.0, isEdge);
     
-    // 应用匹配因子（平滑颜色边界）
-    alpha *= matchFactor;
+    // 应用匹配因子实现边界平滑，但保留最小 0.9 的透明度
+    // 这样即使在边界处也不会完全透明，同时完全匹配区域保持设定的透明度
+    alpha *= max(matchFactor, 0.9);
     
     gl_FragColor = vec4(highlightColor, alpha);
   } else {
@@ -82,8 +94,89 @@ void main() {
   }
 }
 `
+), r = (
+  /* glsl */
+  `
+#define RESOLUTION 2048.0
+#define MAX_GROUPS 64
+#define STRICT_MATCH 0.5/255.0
+
+varying vec2 vUv;
+uniform sampler2D map;
+uniform sampler2D mergedTexture;
+uniform float groupCount;
+uniform float textureWidth;
+uniform float pixelsPerGroup;
+
+float colorGap(vec3 a, vec3 b) {
+  return abs(a.r - b.r) + abs(a.g - b.g) + abs(a.b - b.b);
+}
+
+vec4 readStyleColor(float groupIndex) {
+  float px = groupIndex * pixelsPerGroup;
+  float texX = (px + 0.5) / textureWidth;
+  return texture2D(mergedTexture, vec2(texX, 0.5));
+}
+
+vec4 readStyleToleranceHighlight(float groupIndex) {
+  float px = groupIndex * pixelsPerGroup + 1.0;
+  float texX = (px + 0.5) / textureWidth;
+  return texture2D(mergedTexture, vec2(texX, 0.5));
+}
+
+float readStyleOpacity(float groupIndex) {
+  float px = groupIndex * pixelsPerGroup + 2.0;
+  float texX = (px + 0.5) / textureWidth;
+  return texture2D(mergedTexture, vec2(texX, 0.5)).r;
+}
+
+float detectEdge(sampler2D map, vec2 uv, vec3 matchColor, float tolerance) {
+  vec4 centerColor = texture2D(map, uv);
+  if (colorGap(centerColor.rgb, matchColor) >= tolerance) return 0.0;
+  float step = 1.0 / RESOLUTION;
+  vec4 u = texture2D(map, uv + vec2(0.0, -step));
+  vec4 l = texture2D(map, uv + vec2(-step, 0.0));
+  vec4 r = texture2D(map, uv + vec2(step, 0.0));
+  vec4 d = texture2D(map, uv + vec2(0.0, step));
+  bool edge = colorGap(u.rgb, matchColor) >= tolerance || colorGap(l.rgb, matchColor) >= tolerance
+    || colorGap(r.rgb, matchColor) >= tolerance || colorGap(d.rgb, matchColor) >= tolerance;
+  return edge ? 1.0 : 0.0;
+}
+
+void main() {
+  vec4 image = texture2D(map, vUv);
+  if (image.r == 0.0 && image.g == 0.0 && image.b == 0.0) discard;
+
+  // WebGL 1.0 要求循环终止条件必须是编译时常量，所以用 MAX_GROUPS，循环内检查 groupCount
+  for (float i = 0.0; i < float(MAX_GROUPS); i += 1.0) {
+    if (i < groupCount) {
+      vec4 styleColor = readStyleColor(i);
+      vec3 colorRgb = styleColor.rgb;
+      float tol = readStyleToleranceHighlight(i).r * 3.0;
+      vec3 highlight = readStyleToleranceHighlight(i).gba;
+      float opacity = readStyleOpacity(i);
+      
+      if (opacity > 0.0) {
+        float gap = colorGap(image.rgb, colorRgb);
+        if (gap > STRICT_MATCH) continue;
+        float smoothRange = 0.01;
+        float matchFactor = 1.0 - smoothstep(tol - smoothRange, tol + smoothRange, gap);
+        if (matchFactor > 0.0) {
+          float isEdge = detectEdge(map, vUv, colorRgb, tol);
+          float alpha = mix(opacity, 1.0, isEdge);
+          alpha *= max(matchFactor, 0.9);
+          gl_FragColor = vec4(highlight, alpha);
+          return;
+        }
+      }
+    }
+  }
+  discard;
+}
+`
 );
 export {
-  e as maskFragmentShader,
-  o as maskVertexShader
+  o as maskFragmentShader,
+  r as maskFragmentShaderMulti,
+  e as maskVertexShader
 };

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

@@ -0,0 +1,202 @@
+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 或 canvas 的 symbol, value: { texture: THREE.Texture, refCount: number, abortController?: AbortController }
+     */
+    private static maskTextureCache;
+    /**
+     * Canvas 到 Symbol 的映射（用于缓存 canvas 纹理）
+     */
+    private static canvasSymbolMap;
+    /**
+     * 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?;
+    constructor(plugin: PanoTagPluginController, tagData: TagData);
+    /**
+     * 计算法向量
+     * Mask 标签返回向上的法向量（因为是贴在 cube 面上）
+     */
+    computeNormal(): THREE.Vector3;
+    /**
+     * 获取额外的闪烁目标
+     * 返回 maskMesh 用于 blink 动画
+     */
+    protected getAdditionalBlinkTargets(): any | any[] | null;
+    /**
+     * 更新标签数据
+     */
+    set(tag: PartialObjectDeep<Tag<C, 'Mask'>>, deepMerge?: boolean): void;
+    /**
+     * 重写 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;
+    /**
+     * 应用可见性变化
+     */
+    applyVisible(): void;
+    /**
+     * 更新 mesh 的位置和旋转（跟随观察者）
+     * 参考 itemMask 实现
+     */
+    private updateMeshTransform;
+    /**
+     * 初始化 Mask Mesh（使用 Sphere）
+     */
+    private initializeMaskMesh;
+    /**
+     * 创建 Sphere mesh（参考 itemMask 实现）
+     */
+    private createSphereMesh;
+    /**
+     * 获取 Mask 样式配置（合并用户配置和默认值）
+     */
+    private getMaskStyle;
+    /**
+     * 设置点击事件
+     */
+    private setupClickEvents;
+    /**
+     * 清理点击事件
+     */
+    private cleanupClickEvents;
+    /**
+     * 重新加载 mask 图
+     * @param oldMaskUrl 旧的 mask 源，用于正确释放纹理缓存（调用 set 时已更新 this.maskUrl，需传入旧值）
+     */
+    private reloadMask;
+    /**
+     * 更新 mask 样式
+     */
+    private updateMaskStyle;
+    /**
+     * 更新 Canvas 纹理（仅当 maskUrl 为 Canvas 时有效）
+     * 当 canvas 内容发生变化时，调用此方法更新渲染
+     */
+    updateCanvasTexture(): void;
+    /**
+     * 清理 MaskTag 特有的资源（内部方法，避免重复调用）
+     */
+    private disposeMaskResources;
+    /**
+     * 清理 MaskTag 特有的资源（公开方法）
+     */
+    dispose(): void;
+    /**
+     * 禁用标签（重写父类方法）
+     */
+    disable(): void;
+    /**
+     * 销毁标签（重写父类方法）
+     */
+    destroy(): void;
+    /**
+     * 获取 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;
+}