@realsee/dnalogel 3.77.3 → 3.78.0-alpha.1

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,201 @@
+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 图
+     */
+    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;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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
+ * 实现颜色匹配和高亮渲染逻辑
+ * 参考 MosaicPlugin 的边缘检测实现
+ */
+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\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";

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;
@@ -166,6 +166,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 };

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

@@ -33,6 +33,15 @@ export type TagClickParams = {
 } | {
     target: 'TagPopoverContent';
     tag: TagInstance;
+} | {
+    target: 'TagBoxModel';
+    tag: TagInstance;
+} | {
+    target: 'TagPolygonModel';
+    tag: TagInstance;
+} | {
+    target: 'TagMaskModel';
+    tag: TagInstance;
 });
 export interface PluginEventMap extends BasePlugin.EventMap<State> {
     loaded: () => void;
@@ -79,6 +88,7 @@ export type TagEvents<C extends TagContentType = TagContentType> = {
     }) => void;
     showPopover: () => void;
     hidePopover: () => void;
+    positionChanged: (position: TagInstance<C>['position']) => void;
 };
 export interface TagCacheInterface {
     visible?: boolean;

package/dist/PanoTagPlugin/typings/tag/Tag.d.ts

@@ -1,7 +1,7 @@
 import type { State as FiveState } from '@realsee/five';
 import type { TagConfig } from './TagConfig';
 import type { ContentTypeMap, TagContentType } from './TagData';
-import type { Position, TagId, StickType, TagStyle, ElementRenderer, TagConfigByKey, ContentTypeConfigKey } from './Utils';
+import type { Position, TagId, StickType, TagStyle, ElementRenderer, TagConfigByKey, ContentTypeConfigKey, BoxPosition, PolygonPosition, MaskPosition } from './Utils';
 import type { DeprecatedTagProperty } from '../../Archive/deprecated';
 import type { LiteralUnion } from 'type-fest';
 export interface Tags {
@@ -33,7 +33,7 @@ export type Tag<C extends TagContentType = TagContentType, S extends StickType =
      */
     contentType: LiteralUnion<C, string>;
     /** 点 */
-    position: S extends 'Plane' ? [Position, Position, Position, Position] : S extends '2DPoint' | '3DPoint' | 'Model' ? Position : Position | [Position, Position, Position, Position];
+    position: S extends 'Plane' ? [Position, Position, Position, Position] : S extends '2DPoint' | '3DPoint' | 'Model' ? Position : S extends '3DBox' ? BoxPosition : S extends 'Polygon' ? PolygonPosition : S extends 'Mask' ? MaskPosition : Position | [Position, Position, Position, Position];
     /** 法向量 */
     normal?: Position;
     /** 自定义标签内容 */
@@ -52,8 +52,13 @@ export type Tag<C extends TagContentType = TagContentType, S extends StickType =
     hoverEnabled?: boolean;
 } & (S extends '3DPoint' ? {
     normal: Position;
-} : unknown) & (S extends 'Model' ? {
+} : unknown) & // 三维标签需要法向量
+(S extends 'Model' ? {
     matrix: number[];
+} : unknown) & // 模型标签需要模型
+(S extends 'Mask' ? {
+    mask: string | HTMLCanvasElement;
+    color: [number, number, number] | number | string;
 } : unknown) & {
     [key: string]: any;
 };

package/dist/PanoTagPlugin/typings/tag/Utils.d.ts

@@ -15,7 +15,34 @@ export interface MinMax {
     min?: number;
     max?: number;
 }
-export type StickType = '2DPoint' | '3DPoint' | 'Plane' | 'Model';
+export type StickType = '2DPoint' | '3DPoint' | 'Plane' | 'Model' | '3DBox' | 'Polygon' | 'Mask';
+/**
+ * 3DBox 位置定义
+ */
+export interface BoxPosition {
+    /** 起始点坐标 [x, y, z] */
+    start: ArrayPosition;
+    /** 结束点坐标 [x, y, z] */
+    end: ArrayPosition;
+    /** 旋转角度 [x, y, z]（欧拉角） */
+    rotation: ArrayPosition;
+}
+/** 3DBox 标签 */
+export type BoxTag<C extends TagContentType = TagContentType> = TagInstance<C, '3DBox'>;
+/**
+ * Polygon 位置定义
+ * 多边形由多个点组成，至少需要 3 个点
+ */
+export type PolygonPosition = ArrayPosition[];
+/** Polygon 标签 */
+export type PolygonTag<C extends TagContentType = TagContentType> = TagInstance<C, 'Polygon'>;
+/**
+ * Mask 位置定义
+ * Mask 标签的 position 由 mask 图和 color 计算得出，类型为普通的 Position
+ */
+export type MaskPosition = Position;
+/** Mask 标签 */
+export type MaskTag<C extends TagContentType = TagContentType> = TagInstance<C, 'Mask'>;
 /**
  * @description 标签 icon 动画配置
  */
@@ -67,6 +94,28 @@ export interface TagStyle {
          */
         size?: 'S' | 'M' | 'L' | 'XL' | number;
     } & TagIconUrl;
+    /** 3D Box 和Polygon样式 */
+    boxOrpolygon?: {
+        /** 填充颜色（十六进制） */
+        color?: number;
+        /** 填充透明度 0-1 */
+        opacity?: number;
+        /** 线条颜色（十六进制） */
+        lineColor?: number;
+        /** 线条宽度 */
+        lineWidth?: number;
+    };
+    /** Mask 标签样式 */
+    mask?: {
+        /** 高亮颜色（支持 RGB 数组、十六进制数字、#FFFFFF 格式字符串） */
+        color?: [number, number, number] | number | string;
+        /** 透明度 0-1，用于填充区域；描边区域始终完全不透明 */
+        opacity?: number;
+        /** 颜色匹配容差（归一化值 0-1，默认 0.001） */
+        tolerance?: number;
+        /** @deprecated 使用 color 代替 */
+        highlightColor?: [number, number, number] | number;
+    };
 }
 export type TagGLTFObject = GLTFObject & {
     customID: number | string;

package/dist/PanoTagPlugin/utils/sculptDataToBoxPosition.d.ts

@@ -0,0 +1,6 @@
+import * as THREE from 'three';
+import type { BoxPosition } from '../typings';
+/**
+ * 将 Sculpt 数据转换为 BoxPosition
+ */
+export declare function sculptDataToBoxPosition(bottomPoints: THREE.Vector3[], heightPoint: THREE.Vector3): BoxPosition;

package/dist/PanoTagPlugin/utils/tag/tagCheck.d.ts

@@ -1,9 +1,15 @@
 import type { TagContentType, TagInstance } from '../../typings';
 import type { ModelTagInterface } from '../../controller/Tag/ModelTag';
 import type { PlaneTagInterface } from '../../controller/Tag/PlaneTag';
+import type { PolygonTagInterface } from '../../controller/Tag/PolygonTag';
+import type { BoxTagInterface } from '../../controller/Tag/BoxTag';
+import type { MaskTagInterface } from '../../controller/Tag/MaskTag';
 export declare function isPlaneTag<T extends TagContentType>(tag: TagInstance<T>): tag is PlaneTagInterface<T>;
 export declare function isPoint3DTag<T extends TagContentType>(tag: TagInstance<T>): tag is TagInstance<T, '3DPoint'>;
 export declare function is3DTag<T extends TagContentType>(tag: TagInstance): tag is TagInstance<T, '3DPoint'> | TagInstance<T, 'Plane'>;
 export declare function isMediaModelTag(tag: TagInstance): tag is ModelTagInterface<'MediaModel'>;
 export declare function isModelTag(tag: TagInstance): tag is ModelTagInterface<'Model'>;
 export declare function isMediaPlaneTag(tag: TagInstance): tag is PlaneTagInterface<'MediaModel'>;
+export declare function isPolygonTag(tag: TagInstance): tag is PolygonTagInterface;
+export declare function is3DBoxTag(tag: TagInstance): tag is BoxTagInterface;
+export declare function isMaskTag(tag: TagInstance): tag is MaskTagInterface;