@realsee/dnalogel 3.77.2 → 3.78.0-alpha.0

package/CHANGELOG.md

@@ -1,4 +1,7 @@
 # CHANGELOG
+## 3.77.3
+
+- feat(CruisePlugin): 导览新增语音播放功能
 ## 3.77.2
 
 - fix(Sculpt): 修复 hitFilter 配置为可选，避免未配置时报错

package/dist/CruisePlugin/Work.d.ts

@@ -20,6 +20,8 @@ export default class WalkController extends CruiseController<PluginData, Config>
         moveToFirstPanoEffect?: MoveEffect;
         moveToFirstPanoDuration?: number;
         modeChanging?: boolean;
+        audio?: HTMLAudioElement;
+        audioCache?: Map<string, HTMLAudioElement>;
     };
     constructor(five: Five, config?: Config);
     /**
@@ -117,4 +119,6 @@ export default class WalkController extends CruiseController<PluginData, Config>
      * @description Change five mode
      */
     private changeMode;
+    private loadAudio;
+    private playAudio;
 }

package/dist/CruisePlugin/typing.d.ts

@@ -18,6 +18,13 @@ export type CruiseData = {
      * @description 旋转速度 rad/ms
      */
     rotateSpeed?: number;
+    /**
+     * @description move effect独有，音频播放相关参数
+     */
+    audio?: {
+        url: string;
+        duration: number;
+    };
 } & FivePoseAndState;
 export interface CruiseKeyframe {
     id: string;

package/dist/CruisePlugin/utils/coordinatesAngle.d.ts

@@ -1,6 +1,6 @@
 /**
- * @description: 获取coordinates间的夹角
- * @return {number} 夹角角度
+ * @description: 获取coordinates间的夹角（两个方向向量之间的最小夹角）
+ * @return {number} 夹角角度（0 到 π）
  */
 declare function coordinatesAngle(coordinates1: {
     longitude: number;
@@ -9,4 +9,20 @@ declare function coordinatesAngle(coordinates1: {
     longitude: number;
     latitude: number;
 }): number;
-export { coordinatesAngle };
+/**
+ * @description: 获取coordinates间的实际旋转角度（基于 longitude/latitude 差值）
+ * @param coordinates1 起始坐标
+ * @param coordinates2 目标坐标
+ * @param signed 是否返回有符号角度（默认 false）
+ *   - true: 返回有符号角度（以主要旋转方向的符号为准）
+ *   - false: 返回无符号角度（绝对值）
+ * @return {number} 旋转角度（弧度），可以超过 π
+ */
+declare function coordinatesRotation(coordinates1: {
+    longitude: number;
+    latitude: number;
+}, coordinates2: {
+    longitude: number;
+    latitude: number;
+}, signed?: boolean): number;
+export { coordinatesAngle, coordinatesRotation };

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,118 @@
+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;
+    /**
+     * 应用可见性变化
+     */
+    applyVisible(): void;
+    /**
+     * 销毁标签
+     */
+    dispose(): void;
+}

package/dist/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/dist/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";

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: {
+                url: 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;
+    color: [number, number, number] | number;
 } : 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 数组或十六进制数字） */
+        color?: [number, number, number] | number;
+        /** 透明度 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;