CIMCubeSDK v3.56.0

Class: USDLayer

Glodon.CIMCube.Layer. USDLayer

USD 图层：通过 USDProvider 加载 .usda / .usdc / .usd / .usdz， 在场景中显示为 Cesium Model，并管理场景变换、渲染与交互。

new USDLayer(opts)

USD 图层构造函数
Parameters:
Name Type Description
opts Object 图层配置参数
Properties
Name Type Argument Default Description
url String USD 资源地址（.usda / .usdc / .usd / .usdz）
origin Array.<Number> 图层原点 [经度, 纬度, 高度]，例：[106.689936, 29.559434, 500.0]
shadowMode String <optional>
 "disabled" 阴影模式
offset Array.<Number> <optional>
 [0, 0, 0] 偏移量 [东, 北, 天]，单位米
rotation Array.<Number> <optional>
 [0, 0, 0] 旋转参数（右手坐标系，绕 X/Y/Z 轴）；默认绕模型包围中心旋转
scale Number <optional>
 1 缩放比例
canSelected Boolean <optional>
 true 是否可选
phongLighting Boolean <optional>
 false 是否使用冯氏光照
bfLighting Boolean <optional>
 false 是否启用 BF 光照
cLighting Boolean <optional>
 false 是否启用 C 光照
bfReflectEffect Boolean <optional>
 false 是否启用 BF 反射效果
isBim Boolean <optional>
 false 是否按 BIM 模型渲染
useDefaultMetallicRoughness Boolean <optional>
 true 是否使用默认金属度粗糙度
alpha Number <optional>
 1.0 透明度
luminanceAtZenith Number <optional>
 0.2 图层光源亮度
hue Number <optional>
 0.0 色相，值范围：-PI~PI
saturation Number <optional>
 1.0 饱和度，值范围：0~2
brightness Number <optional>
 1.0 明度，值范围：0~2
contrast Number <optional>
 1.0 对比度
gamma Number <optional>
 1.0 伽马值
metallicRoughnessFactor Array.<Number> <optional>
 金属度与粗糙度，例：[0.5, 0.5]
doubleSided Boolean <optional>
 是否使用双面材质
usedAnimations Boolean <optional>
 true 是否自动播放骨骼动画

Extends

Members

<protected> _rotation :Array.<Number>

旋转参数（内部 HPR 顺序，供变换矩阵计算使用）
Type:
  • Array.<Number>

alpha :Number

图层透明度，取值范围 0.0~1.0
Type:
  • Number
Overrides:

brightness :Number

明度调整，取值范围 0~2
Type:
  • Number

cacheable :Boolean

是否可缓存
Type:
  • Boolean
Inherited From:
Overrides:

canHighlight :Boolean

可否高亮
Type:
  • Boolean
Inherited From:
Overrides:

canSelected :Boolean

可否被选中
Type:
  • Boolean
Inherited From:
Overrides:

colorMode :String

色彩模式，与场景 ColorCorrect 联动
Type:
  • String

contrast :Number

对比度调整
Type:
  • Number

doubleSided :Boolean|undefined

是否使用双面材质
Type:
  • Boolean | undefined

dragCenter :Cesium.Cartesian3|undefined

拖拽 Gizmo 中心点（世界坐标）
Type:
  • Cesium.Cartesian3 | undefined

enableMouseMove :Boolean

是否可以触发鼠标移动事件
Type:
  • Boolean
Inherited From:
Overrides:
Default Value:
  • true

enableRealisticRendering :Boolean

是否开启真实渲染
Type:
  • Boolean

gamma :Number

伽马值调整
Type:
  • Number

glowColor :String

发光颜色
Type:
  • String
Inherited From:
Overrides:

glowTimeInterval :number

闪烁的时间间隔
Type:
  • number
Inherited From:
Overrides:

hiddenInLayerTree :Boolean

是否对图层树接口隐藏
Type:
  • Boolean
Inherited From:
Overrides:

hue :Number

色相调整，取值范围 -PI~PI
Type:
  • Number

<readonly> id :String

id
Type:
  • String
Inherited From:
Overrides:

isPipeline :Boolean

数据是否是管线类型
Type:
  • Boolean
Inherited From:
Overrides:

<readonly> isUSDLayer :Boolean

标识当前图层为 USD 图层
Type:
  • Boolean

luminanceAtZenith :Number

图层光源亮度
Type:
  • Number

matrix :Object

图层偏移
Type:
  • Object
Inherited From:
Overrides:

metallicRoughnessFactor :Array.<Number>|undefined

金属度与粗糙度，例：[0.5, 0.5]，取值范围 0~1
Type:
  • Array.<Number> | undefined

name :String

图层名称
Type:
  • String
Inherited From:
Overrides:

offset :Array.<Number>

偏移量 [东, 北, 天]，单位米，例：[1000.0, 500.0, 100.0]
Type:
  • Array.<Number>

offsetRotation :Array.<Number>

指定旋转点后的变换偏移 [东, 北, 天]，单位米；由 offset 与 rotationPointOffset 推导
Type:
  • Array.<Number>

origin :Array.<Number>

图层原点在地球上的位置，用经纬度表示，例：[106.689936, 29.559434, 500.0]
Type:
  • Array.<Number>

pickable :Boolean

pickable
Type:
  • Boolean
Inherited From:
Overrides:

<readonly> ready :Boolean

图层及内部 Model 是否已完成初始化
Type:
  • Boolean
Overrides:

rotation :Array.<Number>

旋转参数（右手坐标系，第一个元素绕 X 轴、第二个绕 Y 轴、第三个绕 Z 轴，单位：度）；默认绕模型包围中心旋转
Type:
  • Array.<Number>

rotationPointOffset :Cesium.Cartesian3

图层指定的旋转点，模型坐标系下基于原点的 ENU 偏移，默认为包围盒中心
Type:
  • Cesium.Cartesian3
Overrides:

saturation :Number

饱和度调整，取值范围 0~2
Type:
  • Number

scale :Number

缩放比例系数
Type:
  • Number

selectedColor :String

选中颜色
Type:
  • String
Inherited From:
Overrides:

shadowMode :String

阴影模式
Type:
  • String

show :Boolean

是否显示图层
Type:
  • Boolean
Overrides:

sizeForDragger :Number

拖拽 Gizmo 轴长参考值，取自模型包围球半径
Type:
  • Number

transform :Cesium.Matrix4|undefined

模型世界变换矩阵
Type:
  • Cesium.Matrix4 | undefined

<readonly> type :String

图层类型
Type:
  • String
Inherited From:
Overrides:

<readonly> url :String

图层url地址
Type:
  • String
Inherited From:
Overrides:

Methods

<protected> _addTo(engine)

添加到地图并触发加载
Parameters:
Name Type Description
engine Cesium.Engine 引擎

<protected> _updateOffset()

根据 offsetRotation 与指定旋转点，反算 offset

<protected> _updateOffsetRotation()

根据 offset 与指定旋转点，同步 offsetRotation

addAllAnimations(playOpt)

播放模型内全部骨骼动画
Parameters:
Name Type Description
playOpt Object 播放选项
Properties
Name Type Argument Default Description
playMode Number <optional>
 循环模式，默认 REPEAT
multiplier Number <optional>
 1 播放倍速
delay Number <optional>
 0 延迟（秒）
reverse Boolean <optional>
 false 是否反向播放
Returns:
Type
Cesium.ModelAnimation | undefined

addAnimation(animationOpt)

按名称或索引播放单个骨骼动画
Parameters:
Name Type Description
animationOpt Object 动画选项
Properties
Name Type Argument Description
name String <optional>
 动画名称
index Number <optional>
 动画索引
playMode Number <optional>
 循环模式，默认 REPEAT
Returns:
Type
Cesium.ModelAnimation | undefined

addDragHandle()

在场景中添加拖拽操作句柄
Overrides:
  • Glodon.CIMCube.Layer.BaseLayer#addDragHandle
Returns:
拖拽句柄实例
Type
*

addMultiClippingPlane(id, collections, region)

按 id 添加一组多裁剪平面
Parameters:
Name Type Description
id String 裁剪组标识
collections Array.<Cesium.ClippingPlaneCollection> 裁剪平面集合数组
region Cesium.MultiClippingPlaneRegion 裁剪区域配置（边线颜色、宽度、模式等）

addTo(map)

将图层添加到图层管理器中
Parameters:
Name Type Description
map Glodon.CIMCube 地图实例
Inherited From:
Overrides:

dispatchEvent(event)

在此事件派发器上派发事件.
Parameters:
Name Type Description
event Object 待派发的事件.
Inherited From:
Overrides:

dispose()

释放 USDProvider 及内部 Model 资源

enuToWorldPosition(enuPosition)

将以图层原点为基准的东北天 ENU 偏移 (x=东, y=北, z=天) 转换为世界坐标
Parameters:
Name Type Description
enuPosition Cesium.Cartesian3 ENU 偏移坐标
Returns:
世界坐标
Type
Cesium.Cartesian3 | undefined

flyTo()

摄像机定位到图层；模型未就绪时会等待 ready 后再飞行
Returns:
是否成功发起飞行
Type
Promise.<Boolean>

getAllAnimation()

获取当前正在运行的全部动画
Returns:
Type
Array.<Cesium.ModelAnimation> | undefined

getAllUsdCustomAttributesByPath()

读取所有 Prim 路径及其 custom attributes
Returns:
Prim 路径 → custom attributes
Type
Record.<String, Object>

getAnimationByIndex(index)

按索引查找骨骼动画
Parameters:
Name Type Description
index Number 动画索引
Returns:
Type
Cesium.ModelAnimation | undefined

getAnimationByName(animationName)

按名称查找骨骼动画
Parameters:
Name Type Description
animationName String 动画名称
Returns:
Type
Cesium.ModelAnimation | undefined

getBoundingSphere()

获取模型包围球；优先使用 USDProvider 的视觉包围球
Returns:
Type
Cesium.BoundingSphere | undefined

getBoundingVolume()

获取模型有向包围盒（基于 sceneGraph 顶点 AABB 计算，结果会缓存）
Returns:
Type
Cesium.OrientedBoundingBox | undefined

getBoundingVolumeHeight()

获取有向包围盒高度（米）
Returns:
Type
Number | undefined

getClipTarget()

获取模型剖切目标对象
Returns:
Type
Cesium.Model | undefined

getModel()

获取内部 Cesium Model，用于动画、剖切、拾取等操作
Returns:
Type
Cesium.Model | undefined

getOriginWorldCoord()

获取图层原点世界坐标（含当前变换）
Returns:
Type
Cesium.Cartesian3 | undefined

getParentId()

获取父节点ID
Inherited From:
Overrides:
Returns:
父节点ID
Type
String

getUsdCustomAttributesByPath(usdPath)

读取指定 USD Prim 路径上的 custom attributes
Parameters:
Name Type Description
usdPath String Prim 路径，例："/World/Building"
Returns:
custom attributes 键值对象
Type
Object | undefined

invalidateBoundingVolume()

清除 OBB 缓存，下次 getBoundingVolume / getBoundingVolumeHeight 将重新计算

localToWorldPosition(localPosition)

将模型局部坐标转换为世界坐标
Parameters:
Name Type Description
localPosition Cesium.Cartesian3 模型局部坐标
Returns:
世界坐标
Type
Cesium.Cartesian3 | undefined

move(angle, distance [, mode])

指定角度移动图层，顺时针旋转
Parameters:
Name Type Argument Default Description
angle Number 指定角度（度）；y-x 平面 0° 为正北，z-x / z-y 平面 0° 为垂直地表向外
distance Number 移动距离（米）
mode String <optional>
 "y-x" 移动平面，枚举：y-x、z-x、z-y
Returns:
更新后的 offset
Type
Array.<Number>

removeAllAnimation()

移除模型内全部骨骼动画

removeAnimation(targetAnimation)

移除指定骨骼动画
Parameters:
Name Type Description
targetAnimation Cesium.ModelAnimation 目标动画实例

removeDragHandle()

在场景中移除操作句柄
Inherited From:
Overrides:

<protected> removeFrom(callByManager)

从地图中移除
Parameters:
Name Type Description
callByManager Boolean 是否由管理器调用
Overrides:

removeMultiClippingPlane(id)

按 id 移除一组多裁剪平面
Parameters:
Name Type Description
id String 裁剪组标识

setClippingPlanes(value)

设置裁剪平面集合
Parameters:
Name Type Description
value Cesium.ClippingPlaneCollection 裁剪平面集合

setMultiClippingPlanes(value)

设置多裁剪平面集合
Parameters:
Name Type Description
value Cesium.MultiClippingPlaneCollection 多裁剪平面集合

setStyle(style)

设置模型高亮与轮廓样式
Parameters:
Name Type Description
style Object 样式对象
Properties
Name Type Description
modelColor Object 模型颜色
Properties
Name Type Argument Default Description
mode String <optional>
 "Highlight" 着色模式：Highlight | Replace | Mix
color String <optional>
 "yellow" 模型颜色
mixAmount Number <optional>
 0.5 混合度，mode 为 Mix 时有效，取值 0~1
modelSilhouette Object 模型轮廓
Properties
Name Type Argument Default Description
color String <optional>
 "yellow" 轮廓颜色
size Number <optional>
 1 轮廓宽度（像素）

updateLayerTransformation()

根据当前 origin、offset、rotation、scale 更新模型变换，并触发 TRANSFORM_CHANGED

worldPositionToLayerENU(worldPosition)

将世界坐标转换为以图层原点为基准的东北天 ENU 偏移 (x=东, y=北, z=天)
Parameters:
Name Type Description
worldPosition Cesium.Cartesian3 世界坐标
Returns:
ENU 偏移坐标
Type
Cesium.Cartesian3 | undefined

worldPositionToLocal(worldPosition)

将世界坐标转换为模型局部坐标
Parameters:
Name Type Description
worldPosition Cesium.Cartesian3 世界坐标
Returns:
模型局部坐标
Type
Cesium.Cartesian3 | undefined

Events

LOADED

数据加载完成后触发
Type: Object
Properties:
Name Type Description
arguments Cesium.Model 内部 Cesium Model 实例
Example
layer.on(Glodon.CIMCube.Global.Defines.LayerEventType.LOADED, function (event) {
  console.log(event.arguments);
})

TRANSFORM_CHANGED

图层变换矩阵发生变化后触发
Type: Object
Properties:
Name Type Description
arguments Cesium.Matrix4 当前模型变换矩阵
Example
layer.on(Glodon.CIMCube.Global.Defines.LayerEventType.TRANSFORM_CHANGED, function (event) {
  console.log(event.arguments);
})