@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.11

package/plugins/FloorplanPlugin/typing.d.ts

@@ -0,0 +1,156 @@
+import type * as THREE from 'three/webgpu';
+import type { BasePlugin } from '../BasePlugin';
+import type { FloorplanData, FloorplanServerData, FloorplanRoomItem, FloorplanItem } from './typings';
+export * from './typings';
+/** 户型图在垂直方向上吸附的高度基准 */
+export declare const enum FLOOR_PLAN_ATTACHED_TO {
+    /** 吸附到楼层地面 */
+    FLOOR = 1,
+    /** 吸附到楼层天花板 */
+    CEILING = 2,
+    /** 吸附到模型整体包围盒中心高度 */
+    BOUNDING_CENTER = 3
+}
+export declare const enum FloorplanErrorType {
+    UnknownError = "UnknownError",
+    DataNotLoaded = "DataNotLoaded",
+    UpdateSizeError = "UpdateSizeError",
+    BreakOffByHide = "BreakOffByHide",
+    BreakOffByDisable = "BreakOffByDisable",
+    ModelNotLoaded = "ModelNotLoaded",
+    ChangeModeError = "ChangeModeError",
+    UpdateCameraError = "UpdateCameraError"
+}
+export type PluginData = FloorplanData;
+export type PluginServerData = FloorplanServerData | {
+    version: number;
+    data: FloorplanServerData;
+};
+export type ShowMode = 'Topview' | 'Mapview' | 'Floorplan';
+/** 展示户型图时，需要 five 处于的相机状态 */
+export interface ShowState {
+    latitude: number;
+    longitude: number;
+    fov?: number;
+    mode: ShowMode;
+    offset?: THREE.Vector3;
+    distance?: number;
+}
+export interface MissingFloorConfig {
+    imageURL: string;
+    imageWidth: number;
+    imageHeight: number;
+    text: string;
+    textFontSize: number;
+}
+export interface Config {
+    /** 指北针文字 */
+    northDesc: string;
+    /** 展示户型图时，模型/全景画面的透明度 */
+    modelOpacity: number;
+    /** 是否展示相机（点位）图标 */
+    cameraEnable: boolean;
+    /** 是否允许房间高亮 */
+    highlightEnable: boolean;
+    /** 鼠标 hover 房间时是否高亮 */
+    hoverEnable: boolean;
+    /** 是否展示指北针 */
+    compassEnable: boolean;
+    /** 相机静止一段时间后是否自动展示户型图 */
+    autoShowEnable: boolean;
+    /** 是否展示外墙标尺 */
+    ruleLabelsEnable: boolean;
+    /** 是否展示房间标签（名称/面积/尺寸的总开关） */
+    roomLabelsEnable: boolean;
+    /** 是否展示房间面积 */
+    roomAreaEnable: boolean;
+    /** 是否展示房间名称 */
+    roomNameEnable: boolean;
+    /** 其它类型房间是否展示名称 */
+    roomNameOtherTypeEnable: boolean;
+    /** 是否展示房间尺寸标注 */
+    roomDimensionEnable: boolean;
+    /** 相机（点位）图标使用的图片地址 */
+    cameraImageUrl: string;
+    /** 户型图在垂直方向上的吸附基准 */
+    attachedTo: FLOOR_PLAN_ATTACHED_TO;
+    /** 自定义房间标签渲染，返回值将替代默认的名称/面积/尺寸 DOM */
+    getLabelElement?: (room: FloorplanRoomItem) => HTMLElement | undefined;
+    /** 房间标签是否根据房间大小自适应显隐 */
+    adaptiveRoomLabelVisibleEnable: boolean;
+    /** 无楼层数据时的占位配置 */
+    missingFloorConfig: Partial<MissingFloorConfig>;
+    /** 国际化转换函数 */
+    i18n: (key: string) => string;
+    /** 面积文案格式化 */
+    getRoomAreaText: (size: number) => string;
+    /** 尺寸文案格式化 */
+    getRoomDimensionText: (width: number, height: number) => string;
+    /** 标尺距离文案格式化 */
+    getRuleDistanceText: (distance: number) => string;
+}
+/** 插件初始化参数 */
+export interface Params {
+    config?: Partial<Config>;
+    initialState?: Partial<State>;
+    /** 展示户型图时期望 five 处于的相机状态，可通过 updateShowState 更新 */
+    showState?: Partial<ShowState>;
+}
+export interface State extends BasePlugin.State {
+    enabled: boolean;
+    visible: boolean;
+    config: Config;
+}
+export interface ShowOptions {
+    /** 展示的楼层 */
+    floorIndex: number;
+    /** 展示户型图时，模型 / 全景画面的透明度 */
+    modelOpacity: number;
+    /** 是否立即展示（不做渐显动画） */
+    immediately: boolean;
+    /** 是否是自动展示（惯性停止后触发），内部使用 */
+    isAutoShow: boolean;
+    /** 是否是用户行为 */
+    userAction: boolean;
+}
+export interface HideOptions {
+    userAction: boolean;
+    /** 是否是自动隐藏（相机大幅转动触发），内部使用 */
+    isAutoHide: boolean;
+}
+/** 高亮数据，key 为 `${floorIndex}_${roomId}` */
+export type HighlightData = Record<string, {
+    fill?: string;
+    opacity?: number;
+    disabled?: boolean;
+} | undefined>;
+export interface EventMap extends BasePlugin.EventMap<State, PluginData> {
+    /** enabled 从 false 到 true 的回调 */
+    enable: (event: {
+        userAction: boolean;
+    }) => void;
+    /** enabled 从 true 到 false 的回调 */
+    disable: (event: {
+        userAction: boolean;
+    }) => void;
+    /** 插件 dispose */
+    dispose: () => void;
+    /** 开始展示户型图 */
+    show: (event: {
+        userAction: boolean;
+        auto: boolean;
+    }) => void;
+    /** 户型图展示动画结束 */
+    showAnimationEnded: (event: {
+        userAction: boolean;
+        auto: boolean;
+    }) => void;
+    /** 隐藏户型图 */
+    hide: (event: {
+        auto: boolean;
+        userAction: boolean;
+    }) => void;
+    /** 点击房间，返回 false 可阻止默认的分间跳转行为 */
+    click: (room: FloorplanRoomItem | null) => void | false;
+}
+export type { FloorplanRoomItem, FloorplanItem };

package/plugins/FloorplanPlugin/typings/floorplanData.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 户型图内部使用数据（camelCase），由 formatData 从 FloorplanServerData 转换而来
+ */
+import type * as THREE from 'three/webgpu';
+export interface FloorplanPosition {
+    x: number;
+    y: number;
+}
+export interface FloorplanImagePosition {
+    x: number;
+    y: number;
+}
+export interface FloorplanOutlineItem {
+    url: string;
+    index: number;
+    svgUrl?: string;
+    /** svg_url 拉取到的文本内容，存在时优先使用 svg 渲染线框 */
+    svgContent?: string;
+}
+export interface FloorplanEntrance {
+    positionInImage: FloorplanImagePosition;
+    northRad: number;
+    roomId: string;
+    floorIndex: number;
+}
+export interface FloorplanBounding {
+    max: FloorplanPosition;
+    min: FloorplanPosition;
+    origin: FloorplanPosition;
+}
+export interface FloorplanRoomLabelItem {
+    position: FloorplanPosition;
+    positionInImage: FloorplanImagePosition;
+}
+export interface FloorplanDimension {
+    width: number;
+    height: number;
+    /** 垂直方向标注箭头定位点 */
+    vertical?: FloorplanPosition[];
+    /** 水平方向标注箭头定位点 */
+    horizontal?: FloorplanPosition[];
+}
+export interface FloorplanRoomItem {
+    id: string;
+    /** 面积，单位 mm² */
+    size: number;
+    name: string;
+    /** 用户自定义分间别名 */
+    customizedName?: string;
+    /** 房间轮廓多边形点（户型图坐标系，原点在中心） */
+    path: FloorplanPosition[];
+    roomType: string;
+    /** 地板材质类型：0 纯色 / 1 瓷砖 / 2 木地板 */
+    floorType: number;
+    roomLabel: FloorplanRoomLabelItem;
+    observerIndexs: number[];
+    dimension?: FloorplanDimension;
+}
+export interface FloorplanRuleLabels {
+    top: FloorplanPosition[][];
+    right: FloorplanPosition[][];
+    bottom: FloorplanPosition[][];
+    left: FloorplanPosition[][];
+}
+export interface FloorplanFloorData {
+    floorName: string;
+    floorIndex: number;
+    rooms: FloorplanRoomItem[];
+    rules: FloorplanRuleLabels;
+    /** 无房间数据时，是否仍有墙线（决定是否展示缺省占位图） */
+    is_has_wall: boolean;
+    /** 家具数据，通过 loadItems 填充 */
+    items?: FloorplanItem[];
+}
+export interface FloorplanObserver {
+    floorIndex: number;
+    positionInImage: FloorplanImagePosition;
+}
+export interface FloorplanData {
+    outlines: FloorplanOutlineItem[];
+    floorDatas: FloorplanFloorData[];
+    entrance: FloorplanEntrance | null;
+    bounding: FloorplanBounding;
+    observers: FloorplanObserver[];
+}
+/** 家具 icon（loadItems 填充到 floorDatas[i].items） */
+export interface FloorplanItem {
+    id: string;
+    positionInImage: FloorplanImagePosition;
+    /** 宽度，占户型图整体宽度的比例 [0,1] */
+    width: number;
+    /** 高度，占户型图整体高度的比例 [0,1] */
+    height: number;
+    src: string;
+    notes: string;
+    rotateX: number;
+    rotateY: number;
+    rotateZ: number;
+}
+/** 挂载到雷达图上的三维物体（3D 世界坐标） */
+export interface FloorplanExtraObject3D {
+    id: string;
+    position: THREE.Vector3;
+    icon?: string;
+}
+/** 转换为户型图 2D 坐标后的三维挂件 */
+export interface FloorplanExtraObject {
+    id: string;
+    floorIndex: number;
+    positionInImage: FloorplanImagePosition;
+    icon: string;
+}

package/plugins/FloorplanPlugin/typings/floorplanJson.d.ts

@@ -0,0 +1,167 @@
+/**
+ * doctorstrange 户型图编辑器导出的原始 json 数据结构
+ * @description formatFloorplanJson 以此为输入，转换成 FloorplanServerData（snake_case）
+ */
+export interface FloorplanJsonVrData {
+    origin: {
+        left: number;
+        top: number;
+    };
+}
+export interface FloorplanJsonItem {
+    id: string;
+    x: number;
+    y: number;
+    area: string;
+    type: number;
+    width: number;
+    height: number;
+    locked: boolean;
+    rotateZ: number;
+    rotateX: boolean;
+    rotateY: boolean;
+    displayName: string;
+}
+export interface FloorplanJsonPoint {
+    id: string;
+    x: number;
+    y: number;
+    rules: string;
+    lines: string[];
+    locked: boolean;
+    displayName: string;
+}
+export interface FloorplanJsonAreaAttachmentArea {
+    id: string;
+    type: number;
+    roomType: string;
+    direction: string;
+    towardsRad: number;
+    directionCode: string;
+    sharedLines: string[];
+    sharedLineItems: string[];
+}
+export interface FloorplanJsonLine {
+    align: number;
+    curve: number;
+    displayName: string;
+    edgeComputed: boolean;
+    id: string;
+    isLoadBearing: boolean;
+    items: string[];
+    offsetComputed: number;
+    points: string[];
+    thickness: null;
+    thicknessComputed: number;
+    type: number;
+}
+export interface FloorplanJsonLineItem {
+    displayName: string;
+    endPointAt: {
+        x: number;
+        y: number;
+    };
+    entrance: number;
+    id: string;
+    is: 'window' | 'door' | 'other';
+    length: number;
+    line: string;
+    noAnalysis: boolean;
+    offsetY?: number;
+    height?: number;
+    rotateX: boolean;
+    rotateY: boolean;
+    start: number;
+    startIndex: number;
+    startPointAt: {
+        x: number;
+        y: number;
+    };
+    type: number;
+}
+export interface FloorplanJsonArea {
+    attachments: {
+        areas: FloorplanJsonAreaAttachmentArea[];
+        lineItems: {
+            direction: string;
+            directionCode: string;
+            edge: boolean;
+            id: string;
+            is: string;
+            length: number;
+            towardsRad: number;
+        }[];
+    };
+    points: string[];
+    roomName: string;
+    roomType: string;
+    roomTypeName: number;
+    typeName: string;
+    type: number;
+    id: string;
+    empty: boolean;
+    roomTypeLabelMod: boolean;
+    labelX: number;
+    labelY: number;
+    hideName: boolean;
+    size: number;
+    customizedName: string;
+    displayName: string;
+    floorType: number;
+    hideSize: boolean;
+    nameIndex: string;
+    simpleLabelMod: boolean;
+    sizeWithoutLine: number;
+    subLabelX: number;
+    subLabelY: number;
+    subType: number;
+}
+export interface FloorplanJsonFloorplan {
+    name: string;
+    items: FloorplanJsonItem[];
+    points: FloorplanJsonPoint[];
+    floorIndex: string;
+    lineItems: FloorplanJsonLineItem[];
+    areas: FloorplanJsonArea[];
+    lines: FloorplanJsonLine[];
+    templates: {
+        areaLabelName: string;
+    };
+    info: {
+        description: string;
+        height: number;
+        ruleType: number;
+        subheight: number;
+        tags: unknown[];
+    };
+}
+export interface FloorplanJsonCheckMessage {
+    desc: string;
+    tag: string;
+    text: string;
+}
+/** doctorstrange 编辑器导出的原始户型图 json（IFloorplanJson，命名与后端服务保持一致，便于对照） */
+export interface IFloorplanJson {
+    nonce: string;
+    version: string;
+    vrData: FloorplanJsonVrData;
+    structure: string;
+    floorplans: FloorplanJsonFloorplan[];
+    checkMessages: FloorplanJsonCheckMessage[];
+    canvasSize: {
+        height: number;
+        width: number;
+    };
+    property: {
+        isAreaNameCustomized: boolean;
+        scanSize: number;
+        sourceType: number;
+    };
+}
+/** 观察点（point 位）传入格式，用于计算每个点位所在房间 */
+export interface FloorplanJsonObserver {
+    index: number;
+    floor_index: number;
+    /** [x, y, z]，米单位，与 five work.observers 的 standingPosition 对应 */
+    position: [number, number, number];
+}

package/plugins/FloorplanPlugin/typings/floorplanServerData.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 户型图服务端原始数据（snake_case），与 formatData 配合转换成内部使用的 FloorplanData（camelCase）
+ */
+export interface FloorplanServerPosition {
+    x: number;
+    y: number;
+}
+export interface FloorplanServerImagePosition {
+    x: number;
+    y: number;
+}
+export interface FloorplanServerOutlineItem {
+    url: string;
+    index: number;
+    svg_url?: string;
+}
+export interface FloorplanServerEntrance {
+    position_in_image: FloorplanServerImagePosition;
+    north_rad: number;
+    room_id: string;
+    floor_index: number;
+}
+export interface FloorplanServerBounding {
+    max: FloorplanServerPosition;
+    min: FloorplanServerPosition;
+    origin: FloorplanServerPosition;
+}
+export interface FloorplanServerRoomLabelItem {
+    position: FloorplanServerPosition;
+    position_in_image: FloorplanServerImagePosition;
+}
+export interface FloorplanServerDimension {
+    width: number;
+    height: number;
+    /** 垂直方向标注箭头定位点（一般为 2 个点：下端点、上端点） */
+    vertical?: FloorplanServerPosition[];
+    /** 水平方向标注箭头定位点（一般为 2 个点：左端点、右端点） */
+    horizontal?: FloorplanServerPosition[];
+}
+export interface FloorplanServerRoomItem {
+    id: string;
+    size: number;
+    name: string;
+    customized_name?: string;
+    path: FloorplanServerPosition[];
+    room_type: string;
+    floor_type: number;
+    room_label: FloorplanServerRoomLabelItem;
+    observer_indexs: number[];
+    dimension?: FloorplanServerDimension;
+}
+export interface FloorplanServerRuleLabels {
+    top: FloorplanServerPosition[][];
+    right: FloorplanServerPosition[][];
+    bottom: FloorplanServerPosition[][];
+    left: FloorplanServerPosition[][];
+}
+export interface FloorplanServerFloorData {
+    floor_name: string;
+    floor_index: number;
+    rooms: FloorplanServerRoomItem[];
+    rules: FloorplanServerRuleLabels;
+    is_has_wall: boolean;
+}
+export interface FloorplanServerObserver {
+    floor_index: number;
+    position_in_image: FloorplanServerImagePosition;
+}
+export interface FloorplanServerComputedData {
+    floor_datas: FloorplanServerFloorData[];
+    entrance: FloorplanServerEntrance | null;
+    bounding: FloorplanServerBounding;
+    observers: FloorplanServerObserver[];
+}
+export interface FloorplanServerData {
+    outlines: FloorplanServerOutlineItem[];
+    computed_data: FloorplanServerComputedData;
+}

package/plugins/FloorplanPlugin/typings/index.d.ts

@@ -0,0 +1,3 @@
+export * from './floorplanData';
+export * from './floorplanServerData';
+export * from './floorplanJson';

package/plugins/FloorplanPlugin/utils/changeMode.d.ts

@@ -0,0 +1,5 @@
+import type { Five } from '@realsee/five-webgpu';
+/**
+ * 等待 five.changeMode 真正的动画结束（changeMode 返回的 Promise 只代表切换请求被接受，不代表动画播放完毕）
+ */
+export declare function changeMode(five: Five, changeModeParams: Parameters<Five['changeMode']>): Promise<void>;