# ESCustomPrimitive（ES自定义图元）

> 分类：**单点对象** | 引擎：Cesium/UE | 基类：否
> 继承链：`Destroyable -> ESSceneObject -> ESVisualObject -> ESObjectWithLocation -> ESCustomPrimitive`

ESCustomPrimitive 是用于在场景中创建自定义渲染图元的对象，支持自定义着色器（顶点/片元）、顶点属性、包围盒和渲染状态。

## JSON 示例

```json
{
            "type": "ESCustomPrimitive",
            "position": [116.39, 39.9, 0],
            "primitiveType": "TRIANGLES"
        }
```

## 属性

| 属性 | 类型 | 默认值 | 说明 | 来源 |
| --- | --- | --- | --- | --- |
| `allowPicking` | boolean | false | 是否允许拾取 默认false | ESVisualObject |
| `boundingVolume` | BoundingVolumeJsonType \| undefined | undefined | 包围体（bounding volume），用于视锥体裁剪和渲染排序。 | ESCustomPrimitive |
| `castShadows` | boolean \| undefined | undefined | 是否投射阴影，控制图元是否向场景中投射阴影。 | ESCustomPrimitive |
| `collision` | boolean | true | 是否开启碰撞监测 默认true ,主要是UE使用 | ESVisualObject |
| `count` | number \| undefined | undefined | 顶点计数（count），指定绘制时的顶点数量。 | ESCustomPrimitive |
| `cull` | boolean \| undefined | undefined | 是否进行拣选（cull），控制是否对图元进行视锥体裁剪。 | ESCustomPrimitive |
| `debugOverlappingFrustums` | number \| undefined | undefined | 调试时显示重叠视锥数量，辅助调试视锥体裁剪。 | ESCustomPrimitive |
| `debugShowBoundingVolume` | boolean \| undefined | undefined | 调试时显示包围盒，辅助调试包围体是否准确。 | ESCustomPrimitive |
| `depthForTranslucentClassification` | boolean \| undefined | undefined | 半透明分类深度（depth for translucent classification），控制半透明物体的深度写入行为。 | ESCustomPrimitive |
| `devTags` | string[] \| undefined | undefined | 对象类型名称相关的开发标签数组，使用 reactArrayWithUndefined 进行响应式处理，默认为 undefined。 | ESSceneObject |
| `execOnceFuncStr` | string \| undefined | undefined | 一次性执行函数的字符串表示，默认为 undefined。 | ESSceneObject |
| `executeInClosestFrustum` | boolean \| undefined | undefined | 是否在最近视锥中执行绘制，用于多视锥场景下的优化。 | ESCustomPrimitive |
| `extras` | JsonValue | undefined | 扩展属性 JSON，必须整体赋值，使用 reactJson 进行响应式处理，默认为 undefined。 | ESSceneObject |
| `flyInParam` | ESJFlyInParam \| undefined | undefined | 飞入参数 | ESVisualObject |
| `flyToParam` | ESJFlyToParam \| undefined | undefined | 飞向参数 | ESVisualObject |
| `fragmentShaderSource` | string \| undefined | undefined | 片元着色器源代码，自定义像素着色逻辑。 | ESCustomPrimitive |
| `instanceCount` | number \| undefined | undefined | 实例计数（instanceCount），指定实例化绘制的实例数量。 | ESCustomPrimitive |
| `localModelMatrix` | ESJNativeNumber16 \| undefined \| undefined | undefined | 本地模型矩阵，直接设置图元的局部变换矩阵（覆盖 position/rotation/scale）。 | ESCustomPrimitive |
| `localPosition` | [number, number, number] \| undefined \| undefined | undefined | 本地偏移位置，相对于图元所在位置的局部坐标偏移。 | ESCustomPrimitive |
| `localRotation` | [number, number, number] \| undefined \| undefined | undefined | 本地旋转（姿态），定义图元的局部旋转欧拉角。 | ESCustomPrimitive |
| `localScale` | [number, number, number] \| undefined \| undefined | undefined | 本地缩放，定义图元在三个轴向上的局部缩放值。 | ESCustomPrimitive |
| `maximumScale` | number \| undefined | undefined | 最大缩放值（屏幕像素模式下有效），用于限制图元在屏幕上的最大像素尺寸。 | ESCustomPrimitive |
| `maxVisibleDistance` | number | 0 | 最大可视距离 | ESObjectWithLocation |
| `minimumScale` | number \| undefined | undefined | 最小缩放值（屏幕像素模式下有效），用于限制图元在屏幕上的最小像素尺寸。 | ESCustomPrimitive |
| `minVisibleDistance` | number | 0 | 最小可视距离 | ESObjectWithLocation |
| `modelMatrix` | ESJNativeNumber16 \| undefined \| undefined | undefined | 模型矩阵，用于对图元施加自定义的模型变换。 | ESCustomPrimitive |
| `name` | string | "未命名场景对象" | 对象名称，默认为 '未命名场景对象'。 | ESSceneObject |
| `occlude` | boolean \| undefined | undefined | 是否进行遮挡剔除（occlude），控制图元是否被其它物体遮挡时剔除。 | ESCustomPrimitive |
| `offset` | number \| undefined | undefined | 顶点偏移（offset），指定绘制时从第几个顶点开始。 | ESCustomPrimitive |
| `pass` | CzmPassType \| undefined | undefined | 渲染顺序（pass），控制图元在场景中的渲染阶段，如 OPAQUE、TRANSLUCENT 等。 | ESCustomPrimitive |
| `pickOnly` | boolean \| undefined | undefined | 仅用于拾取（pickOnly），开启后图元只参与拾取而不渲染。 | ESCustomPrimitive |
| `pixelSize` | number \| undefined | undefined | 屏幕像素大小，设置图元在屏幕上显示的像素尺寸。 | ESCustomPrimitive |
| `pointed` | boolean | false | 点样式是否启用，默认false | ESObjectWithLocation |
| `pointStyle` | ESJPointStyle | {             size: 1,             sizeType: 'screen',             color: [1, 1, 1, 1],             material: '',             materialParams: {},             outlineColor: [1, 0, 0, 1],             outlineWidth: 2,         } | 点样式 | ESObjectWithLocation |
| `position` | ESJVector3D | [0, 0, 0] | 位置点 [经,纬,高] | ESObjectWithLocation |
| `positionOffset` | ESJVector3D | [0, 0, 0] | 偏移属性 [x,y,z] | ESObjectWithLocation |
| `primitiveType` | CzmPrimitiveType \| undefined | undefined | 图元类型，如 TRIANGLES、LINES、POINTS 等。 | ESCustomPrimitive |
| `receiveShadows` | boolean \| undefined | undefined | 是否接收阴影，控制图元是否接收来自其它物体的阴影。 | ESCustomPrimitive |
| `ref` | string \| undefined | undefined | 对象引用，设置后可通过对象管理器 objm.$refs.xxx 快速获取到对象，默认为 undefined。 | ESSceneObject |
| `renderState` | JsonValue \| undefined | undefined | 渲染状态，包括深度测试、混合模式、面剔除等渲染管线状态。 | ESCustomPrimitive |
| `rotation` | ESJVector3D | [0, 0, 0] | 姿态 [h,p,r] | ESObjectWithLocation |
| `scale` | ESJVector3D | [1, 1, 1] | 缩放 [x,y,z] | ESObjectWithLocation |
| `show` | boolean | true | 是否显示 默认true | ESVisualObject |
| `showSceneScale` | boolean \| undefined | undefined | 是否显示场景缩放值，控制是否按照场景距离缩放图元。 | ESCustomPrimitive |
| `toDestroyFuncStr` | string \| undefined | undefined | 销毁函数的字符串表示，默认为 undefined。 | ESSceneObject |
| `uniformMap` | CzmCustomPrimitiveUniformMapType \| undefined | undefined | 一致性变量（uniform）映射表，向着色器传递 uniform 数据。 | ESCustomPrimitive |
| `updateFuncStr` | string \| undefined | undefined | 更新函数的字符串表示，默认为 undefined。 | ESSceneObject |
| `vertexShaderSource` | string \| undefined | undefined | 顶点着色器源代码，自定义顶点处理逻辑。 | ESCustomPrimitive |
| `viewDistanceDebug` | boolean | false | 是否开启可视距离调试，辅助调试可视距离的裁剪效果。 | ESCustomPrimitive |
| `viewDistanceRange` | [number, number, number, number] \| undefined | undefined | 可视距离范围 [近裁剪距离, 近过渡距离, 远过渡距离, 远裁剪距离]，控制图元在远近处的淡入淡出。 | ESCustomPrimitive |

## 方法

| 方法 | 参数 | 返回 | 说明 | 来源 |
| --- | --- | --- | --- | --- |
| `addToViewer(viewer: ESViewer)` | viewer: ESViewer | - | 将对象添加到指定视口中。<br>**参数**：viewer - 要添加对象的视口。 | ESSceneObject |
| `automaticLanding()` | - | - | 自动落地。 先禁用碰撞检测，一段时间后触发自动落地事件并恢复碰撞检测状态。 | ESObjectWithLocation |
| `calcFlyInParam()` | - | - | 触发计算飞入参数事件 | ESVisualObject |
| `calcFlyToParam()` | - | - | 触发计算飞向参数事件 | ESVisualObject |
| `computeLocalAxisedBoundingBoxFromAttribute(attributeName: string = 'a_position')` | attributeName: string = 'a_position' | - | 从指定顶点属性的位置数据自动计算局部轴对齐包围盒（LocalAxisedBoundingBox）的最小/最大坐标。 属性数据必须是 Float32Array 类型且每个顶点包含 3 个分量（x, y, z）。 计算失败时返回 undefined 并输出警告。<br>**参数**：attributeName - 顶点属性名称，默认为 'a_position'。<br>**返回**：包含 min 和 max 的包围盒对象，若计算失败则返回 undefined。 | ESCustomPrimitive |
| `createAttachedObject(createViewerPropSceneObject: (viewer: ESViewer) => Destroyable | undefined)` | createViewerPropSceneObject: (viewer: ESViewer) => Destroyable \| undefined | - | 创建与视口关联的对象，并返回一个销毁函数，用于手动销毁关联对象。<br>**参数**：createViewerPropSceneObject - 一个函数，用于创建与视口关联的对象。<br>**返回**：一个销毁函数，调用该函数可以销毁所有关联对象。 | ESSceneObject |
| `emptyFlyInParam()` | - | - | 清空飞入参数 | ESVisualObject |
| `emptyFlyToParam()` | - | - | 清空飞向参数 | ESVisualObject |
| `flush()` | - | - | 刷新对象，触发刷新事件。 | ESSceneObject |
| `flyIn(duration: number = 1)` | duration: number = 1 | - | 触发飞入事件<br>**参数**：duration - 飞入持续时间，默认为 1 | ESVisualObject |
| `flyTo(duration: number = 1)` | duration: number = 1 | - | 触发飞向事件<br>**参数**：duration - 飞向持续时间，默认为 1 | ESVisualObject |
| `getBoundSphere(viewer: ESViewer)` | viewer: ESViewer | - | 获取对象的边界球<br>**参数**：viewer - 视图器对象<br>**返回**：包含边界球信息的 Promise | ESVisualObject |
| `getESProperties()` | - | - | 获取该图元的属性列表，包含通用属性、屏幕像素控制、图元属性（着色器、渲染状态等）、 本地变换以及调试等各分组属性。<br>**返回**：包含分组后的属性列表对象。 | ESCustomPrimitive |
| `registerAttachedObject(createViewerPropSceneObject: (viewer: ESViewer) => Destroyable | undefined)` | createViewerPropSceneObject: (viewer: ESViewer) => Destroyable \| undefined | - | 注册与视口关联的对象，当对象被添加到视口或从视口移除时，会自动创建或销毁关联对象。<br>**参数**：createViewerPropSceneObject - 一个函数，用于创建与视口关联的对象。 | ESSceneObject |
| `registerAttachedObjectForContainer(createContainerPropSceneObject: (viewer: ESViewer, container: HTMLDivElement) => Destroyable | undefined)` | createContainerPropSceneObject: (viewer: ESViewer, container: HTMLDivElement) => Destroyable \| undefined | - | 注册与视口容器关联的对象，当对象被添加到视口或从视口移除时，会自动创建或销毁关联对象。<br>**参数**：createContainerPropSceneObject - 一个函数，用于创建与视口容器关联的对象。 | ESSceneObject |
| `reload()` | - | - | - | ESSceneObject |
| `removefromViewer(viewer: ESViewer)` | viewer: ESViewer | - | 将对象从指定视口中移除。<br>**参数**：viewer - 要移除对象的视口。 | ESSceneObject |
| `setLocalAxisedBoundingBox(min: [number, number, number], max: [number, number, number])` | min: [number, number, number], max: [number, number, number] | - | 设置局部轴对齐包围盒（LocalAxisedBoundingBox）作为该图元的包围体。 用于视锥体裁剪和渲染排序优化。所有坐标值必须为有限数，否则操作被忽略并输出警告。<br>**参数**：min - 包围盒最小顶点坐标，即三个轴向上的最小值 [xMin, yMin, zMin]。；max - 包围盒最大顶点坐标，即三个轴向上的最大值 [xMax, yMax, zMax]。 | ESCustomPrimitive |
| `setLocalBoundingSphere(radius: number, center: [number, number, number] = [0, 0, 0])` | radius: number, center: [number, number, number] = [0, 0, 0] | - | 设置局部包围球（LocalBoundingSphere）作为该图元的包围体。 用于视锥体裁剪和渲染排序优化。半径必须为正有限数，否则操作被忽略并输出警告。<br>**参数**：radius - 包围球的半径，必须为正有限数（> 0）。；center - 包围球的球心坐标，默认为 [0, 0, 0]。 | ESCustomPrimitive |
| `setUniformMap(value: CzmCustomPrimitiveUniformMapType)` | value: CzmCustomPrimitiveUniformMapType | - | 设置 uniform 映射表，合并到当前 uniformMap 中。 注意：如果 value 中存在值为 null 的条目，则整个操作被忽略，不会执行合并。<br>**参数**：value - 要合并的 uniform 映射表，键为 uniform 名称，值为对应的 uniform 对象。 | ESCustomPrimitive |
| `smoothMove(Destination: ESJVector3D, Time: number)` | Destination: ESJVector3D, Time: number | - | 平滑移动到指定位置。<br>**参数**：Destination - 目标位置，格式为[经度, 纬度, 高度]；Time - 平滑移动所需的时间，单位为秒 | ESObjectWithLocation |
| `smoothMoveKeepPitch(Destination: ESJVector3D, Time: number)` | Destination: ESJVector3D, Time: number | - | 保持俯仰角平滑移动到指定位置。<br>**参数**：Destination - 目标位置，格式为[经度, 纬度, 高度]；Time - 平滑移动所需的时间，单位为秒 | ESObjectWithLocation |
| `smoothMoveOnGround(Lon: number, Lat: number, Time: number, Ground: string)` | Lon: number, Lat: number, Time: number, Ground: string | - | 贴地平滑移动。<br>**参数**：Lon - 目标位置的经度；Lat - 目标位置的纬度；Time - 平滑移动所需的时间，单位为秒；Ground - 地面类型，UE特有属性 | ESObjectWithLocation |
| `smoothMoveRelatively(RelativePosition: ESJVector3D, Time: number)` | RelativePosition: ESJVector3D, Time: number | - | 相对平滑移动。<br>**参数**：RelativePosition - 相对位置，格式为[经度, 纬度, 高度]；Time - 平滑移动所需的时间，单位为秒 | ESObjectWithLocation |
| `smoothMoveRelativelyWithRotation(RelativePosition: ESJVector3D, NewRotation: ESJVector3D, Time: number)` | RelativePosition: ESJVector3D, NewRotation: ESJVector3D, Time: number | - | 相对平滑偏移到指定位置和姿态。<br>**参数**：RelativePosition - 相对位置，格式为[经度, 纬度, 高度]；NewRotation - 目标姿态，格式为[偏航角, 俯仰角, 翻转角]；Time - 平滑移动所需的时间，单位为秒 | ESObjectWithLocation |
| `smoothMoveWithRotation(Destination: ESJVector3D, NewRotation: ESJVector3D, Time: number)` | Destination: ESJVector3D, NewRotation: ESJVector3D, Time: number | - | 平滑偏移到指定位置和姿态。<br>**参数**：Destination - 目标位置，格式为[经度, 纬度, 高度]；NewRotation - 目标姿态，格式为[偏航角, 俯仰角, 翻转角]；Time - 平滑移动所需的时间，单位为秒 | ESObjectWithLocation |
| `smoothMoveWithRotationOnGround(NewRotation: ESJVector3D, Lon: number, Lat: number, Time: number, Ground: string)` | NewRotation: ESJVector3D, Lon: number, Lat: number, Time: number, Ground: string | - | 贴地平滑偏移到指定位置和姿态。<br>**参数**：NewRotation - 目标姿态，格式为[偏航角, 俯仰角, 翻转角]；Lon - 目标位置的经度；Lat - 目标位置的纬度；Time - 平滑移动所需的时间，单位为秒；Ground - 地面类型，ue特有属性 | ESObjectWithLocation |
| `supportEditingModes()` | - | - | 获取当前对象支持的编辑模式<br>**返回**：支持的编辑模式数组 | ESVisualObject |
| `updateEditing()` | - | - | 更新编辑状态的方法，具体实现由子类完成 | ESVisualObject |

## 事件

| 事件 | 说明 | 来源 |
| --- | --- | --- |
| `activeViewerChanged` | - | ESSceneObject |
| `attributesChanged` | - | ESCustomPrimitive |
| `attributesJsonChanged` | - | ESCustomPrimitive |
| `automaticLandingEvent` | 获取自动落地事件的监听器。 | ESObjectWithLocation |
| `calcFlyInParamEvent` | 获取计算飞入参数事件 | ESVisualObject |
| `calcFlyToParamEvent` | 获取计算飞向参数事件 | ESVisualObject |
| `createdEvent` | 获取对象创建事件。 | ESSceneObject |
| `editingChanged` | 获取编辑状态改变事件 | ESVisualObject |
| `flushEvent` | 获取刷新对象事件。 | ESSceneObject |
| `flyInEvent` | 获取飞入事件 | ESVisualObject |
| `flyOverEvent` | 获取飞行结束事件 | ESVisualObject |
| `flyToDistanceChanged` | 获取飞向距离改变事件 | ESVisualObject |
| `flyToEvent` | 获取飞向事件 | ESVisualObject |
| `flyToFlyDurationChanged` | 获取飞向持续时间改变事件 | ESVisualObject |
| `flyToHDeltaChanged` | 获取飞向水平偏移量改变事件 | ESVisualObject |
| `flyToHeadingChanged` | 获取飞向航向改变事件 | ESVisualObject |
| `flyToPDeltaChanged` | 获取飞向垂直偏移量改变事件 | ESVisualObject |
| `flyToPitchChanged` | 获取飞向俯仰角改变事件 | ESVisualObject |
| `indexTypedArrayChanged` | - | ESCustomPrimitive |
| `indexTypedArrayJsonChanged` | - | ESCustomPrimitive |
| `pickedEvent` | 获取拾取事件 | ESVisualObject |
| `pointColorChanged` | 获取点颜色变化的事件 | ESObjectWithLocation |
| `pointMaterialChanged` | 获取点材质变化的事件 | ESObjectWithLocation |
| `pointMaterialParamsChanged` | 获取点材质参数变化的事件 | ESObjectWithLocation |
| `pointSizeChanged` | 获取点大小变化的事件 | ESObjectWithLocation |
| `pointSizeTypeChanged` | 获取点大小类型变化的事件 | ESObjectWithLocation |
| `readyEvent` | - | ESSceneObject |
| `reloadEvent` | - | ESSceneObject |
| `smoothMoveEvent` | 获取平滑移动事件。 | ESObjectWithLocation |
| `smoothMoveKeepPitchEvent` | 获取保持俯仰角平滑移动事件。 | ESObjectWithLocation |
| `smoothMoveOnGroundEvent` | 获取贴地平滑移动事件。 | ESObjectWithLocation |
| `smoothMoveRelativelyEvent` | 获取相对平滑移动事件。 | ESObjectWithLocation |
| `smoothMoveRelativelyWithRotationEvent` | 获取相对平滑偏移到指定位置和姿态的事件。 | ESObjectWithLocation |
| `smoothMoveWithRotationEvent` | 获取平滑偏移到指定位置和姿态的事件。 | ESObjectWithLocation |
| `smoothMoveWithRotationOnGroundEvent` | 获取贴地平滑偏移到指定位置和姿态的事件。 | ESObjectWithLocation |
| `statusDisChanged` | 获取对象禁用状态改变的事件监听器。 | ESObjectWithLocation |
| `toDestroyFuncChanged` | 获取销毁函数改变事件。 | ESSceneObject |
| `updateFuncChanged` | 获取更新函数改变事件。 | ESSceneObject |

---
> 本文由 `generate-docs.mjs` 从源码自动生成，请勿手改。修改对象属性/方法后重跑脚本刷新。