---
outline: [2, 3]
---

# CubePanel

- 源文件：`packages/sdk/src/mesh/CubePanel.ts`
- 文档位置：`packages/docs/api/mesh/CubePanel.md`

## 枚举：`LabelPosition`

- 作用：标签位置枚举

| 枚举项 | 值 | 说明 |
| --- | --- | --- |
| `TOP` | `'top'` | 枚举值 `TOP`。 |
| `BOTTOM` | `'bottom'` | 枚举值 `BOTTOM`。 |
| `LEFT` | `'left'` | 枚举值 `LEFT`。 |
| `RIGHT` | `'right'` | 枚举值 `RIGHT`。 |

## 接口：`ISmallTextConfig`

- 作用：小字配置接口

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `text` | `string` | 是 | 文字内容 |
| `cubeIndex` | `number` | 是 | 目标正方体索引（0-4），-1 表示全部 |
| `rotation` | `number` | 否 | 旋转角度（度） |
| `fontSize` | `number` | 否 | 字体大小（像素） |
| `color` | `string` | 否 | 字体颜色 |
| `fontWeight` | `string` | 否 | 字体权重 |
| `offset` | `number` | 否 | 与面板边缘的距离（3D单位） |

## 接口：`ICubeData`

- 作用：小正方体数据接口

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `color` | `THREE.Color` | 是 | 颜色 |
| `text` | `string` | 是 | 文字 |

## 接口：`ISinglePanelOptions`

- 作用：单个面板配置选项

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 面板名称 |
| `size` | `number` | 否 | 面板大小,three 的单位 |
| `cubeSize` | `number` | 否 | 小正方体大小 |
| `cubeGap` | `number` | 否 | 小正方体间距 |
| `position` | `THREE.Vector3` | 否 | 面板位置 |
| `rotation` | `THREE.Euler` | 否 | 面板旋转 |
| `initialData` | `ICubeData[][]` | 否 | 初始数据 |
| `titleConfig` | `{ text: string; position: LabelPosition; rotation?: number; fontSize?: number; color?: string; offset?: number; }` | 否 | 标题配置 |
| `smallTextConfig` | `{ position: LabelPosition; smallText1?: ISmallTextConfig[]; smallText2?: ISmallTextConfig[]; rotation?: number; }` | 否 | 小字乐配置 |
| `visibleColumns` | `number[]` | 否 | 可见列索引数组，只有这些列会显示，其他列显示为白色 |

## 类：`CubePanel`

- 作用：单个面板类 表示一个由5*5个小正方体构成的面板

### 构造函数

#### `new CubePanel(options: ISinglePanelOptions)`

- 作用：创建单个面板

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `options` | `ISinglePanelOptions` | 是 | - 配置选项 |

- 出参：`CubePanel`
- 返回说明：返回当前类实例。

### 属性

| 属性名 | 可见性 | 类型 | 作用 |
| --- | --- | --- | --- |
| `name` | `public` | `string` | 面板名称 |
| `group` | `public` | `THREE.Group` | 面板组对象 |
| `cubeData` | `public` | `Map<string, ICubeData>` | 小正方体数据映射 |
| `panelMesh` | `public` | `THREE.Mesh \| null` | 面板网格 |
| `options` | `public` | `Required<ISinglePanelOptions>` | 配置选项 |
| `titleObject` | `public` | `THREE.Mesh \| null` | 标题对象 |
| `titleConfig` | `public` | `{ text: string; position: LabelPosition; rotation: number; fontSize: number; color: string; offset?: number } \| null` | 标题配置 |
| `fontLoader` | `public` | `FontLoader` | 字体加载器 |
| `font` | `public` | `any` | 加载的字体 |
| `smallTextObjects` | `public` | `THREE.Mesh[]` | 小字对象数组 |
| `smallTextPlanes` | `public` | `THREE.Mesh[]` | 小字平面几何体数组 |
| `smallTextCanvas` | `public` | `HTMLCanvasElement \| null` | 小字生成的 canvas |
| `visibleColumns` | `public` | `Set<number>` | 可见列索引集合 |

### 方法

#### `getModelSize(targetModel: THREE.Object3D): THREE.Vector3 | null`

- 作用：静态方法：获取场景中指定名称的模型并计算其包围盒大小

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `targetModel` | `THREE.Object3D` | 是 | 参数 `targetModel`，类型为 `THREE.Object3D`。 |

- 出参：`THREE.Vector3 \| null`
- 返回说明：模型的包围盒大小，如果未找到模型则返回 null

#### `getModelFaceCenters(targetModel: THREE.Object3D): { [key: string]: THREE.Vector3; } | null`

- 作用：静态方法：获取场景中指定名称的模型并计算其包围盒六个面的中心点位置

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `targetModel` | `THREE.Object3D` | 是 | 参数 `targetModel`，类型为 `THREE.Object3D`。 |

- 出参：`{ [key: string]: THREE.Vector3; } \| null`
- 返回说明：模型的包围盒六个面的中心点位置，如果未找到模型则返回 null

#### `createPanel(): void`

- 作用：创建面板

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `initDefaultData(): void`

- 作用：初始化默认数据

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `generatePanelHTML(): string`

- 作用：生成面板的 HTML

- 入参：无

- 出参：`string`
- 返回说明：HTML 字符串

#### `updatePanelTexture(): Promise<void>`

- 作用：将 HTML 转换为纹理并更新面板

- 入参：无

- 出参：`Promise<void>`
- 返回说明：返回 Promise，解析结果类型为 `void`。

#### `setCubeData(row: number, col: number, data: ICubeData): void`

- 作用：设置小正方体数据

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `row` | `number` | 是 | - 行索引 |
| `col` | `number` | 是 | - 列索引 |
| `data` | `ICubeData` | 是 | - 小正方体数据 |

- 出参：`void`
- 返回说明：无返回值。

#### `getCubeData(row: number, col: number): ICubeData | undefined`

- 作用：获取小正方体数据

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `row` | `number` | 是 | - 行索引 |
| `col` | `number` | 是 | - 列索引 |

- 出参：`ICubeData \| undefined`
- 返回说明：小正方体数据

#### `setPanelData(data: ICubeData[][]): void`

- 作用：批量设置面板数据

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `ICubeData[][]` | 是 | - 面板数据 |

- 出参：`void`
- 返回说明：无返回值。

#### `setTitle(titleConfig: ISinglePanelOptions['titleConfig']): void`

- 作用：设置面板标题

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `titleConfig` | `ISinglePanelOptions['titleConfig']` | 是 | - 标题配置 |

- 出参：`void`
- 返回说明：无返回值。

#### `loadFontAndCreateTitle(): void`

- 作用：加载字体并创建标题

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `createTitleObject(): void`

- 作用：创建标题对象

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `setSmallText(smallTextConfig: ISinglePanelOptions['smallTextConfig']): Promise<void>`

- 作用：设置小字

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `smallTextConfig` | `ISinglePanelOptions['smallTextConfig']` | 是 | - 小字配置 |

- 出参：`Promise<void>`
- 返回说明：返回 Promise，解析结果类型为 `void`。

#### `createSmallTextHTML(smallTextConfig: ISinglePanelOptions['smallTextConfig']): Promise<void>`

- 作用：使用 HTML 实现小字，在一个大的 div 中创建所有小字，然后转为 canvas 到一个新的平面几何体

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `smallTextConfig` | `ISinglePanelOptions['smallTextConfig']` | 是 | - 小字配置 |

- 出参：`Promise<void>`
- 返回说明：返回 Promise，解析结果类型为 `void`。

#### `clearSmallText(): void`

- 作用：清理小字

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `clearTitle(): void`

- 作用：清理标题对象

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `addDebugSpheres(): void`

- 作用：添加调试小球，在小字和mountGroup的原点添加不同颜色的小球

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `clearDebugSpheres(): void`

- 作用：清理调试小球

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `dispose(): void`

- 作用：销毁面板

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `setVisibleColumns(columns: number[]): void`

- 作用：设置可见列

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `columns` | `number[]` | 是 | - 可见列索引数组 |

- 出参：`void`
- 返回说明：无返回值。

#### `toggleColumnVisibility(column: number): void`

- 作用：切换列的可见性

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `column` | `number` | 是 | - 列索引 |

- 出参：`void`
- 返回说明：无返回值。

## 构造示例

- 来源：`packages/demo/src/panels/TunnelScene/LoadSurface.vue`

```ts
        text: config.title,
        position: LabelPosition.TOP,
        rotation: 0,
        fontSize: 1,
        color: '#000000',
        offset: 1
      },
      smallTextConfig: config.smallTextConfig,
      // ZD 面只显示第2列（索引为2）
      visibleColumns: key === 'ZD' ? [2] : undefined
    };

    const panel = new CubePanel(panelOptions);
    panel.group.visible = false; // 初始隐藏
    viewer.scene.add(panel.group);
    panels.set(key, panel);
  });
```

## 函数示例

### `CubePanel.getModelFaceCenters`

- 来源：`packages/demo/src/panels/TunnelScene/LoadSurface.vue`

```ts
  if (!viewer) return;
  // 使用 CubePanel 的静态方法获取模型包围盒六个面的中心点位置
  // const faceCenters = CubePanel.getModelFaceCenters(bus.getRockSample());
  const faceCenters = {
    "YF": {
      "x": 0,
      "y": 0,
      "z": 2.5
    },
    "BEI": {
      "x": 0,
      "y": 0,
      "z": -2.5
    },
    "ZUO": {
      "x": -2.5,
      "y": 0,
      "z": 0
    },
    "YOU": {
      "x": 2.5,
```

## Demo 参考

### `LabelPosition`

以下示例文件中可以看到该 API 的实际调用方式：

- `packages/demo/src/panels/TunnelScene/LoadSurface.vue`

### `ISinglePanelOptions`

以下示例文件中可以看到该 API 的实际调用方式：

- `packages/demo/src/panels/TunnelScene/LoadSurface.vue`

### `CubePanel`

以下示例文件中可以看到该 API 的实际调用方式：

- `packages/demo/src/panels/TunnelScene/LoadSurface.vue`