CIMCubeSDK v3.58.0

Class: USDLayer

Glodon.CIMCube.Layer. USDLayer

USD 图层。加载 .usda / .usdc / .usd / .usdz， 在场景中显示为模型，并管理场景变换、渲染与交互。

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 :Cartesian3|undefined

拖拽 Gizmo 中心点（世界坐标）
Type:
  • 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 :Cartesian3

图层指定的旋转点，模型坐标系下基于原点的 ENU 偏移，默认为包围盒中心
Type:
  • 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 :Matrix4|undefined

模型世界变换矩阵
Type:
  • 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 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
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
ModelAnimation | undefined

addDragHandle()

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

addMultiClippingPlane(id, collections, region)

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

addTo(map)

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

applyNodeTransforms()

批量触发 sceneGraph 更新（等价 GSMMLayer.updateModelMatrix）： 将所有 setNodeTransform 的覆盖态重新写回运行时节点， 子树刷新按父子链去重后只刷最上层一次，最后刷新包围盒并标记动画/蒙皮矩阵重算。
Returns:
实际写回（含重写）的节点数
Type
number

dispatchEvent(event)

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

dispose()

释放图层及其内部模型资源

enuToWorldPosition(enuPosition)

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

flyTo()

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

getAllAnimation()

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

getAllUsdCustomAttributesByPath()

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

getAllUsdNodePaths()

枚举全部可控制的 USD Prim 节点路径
Returns:
Type
Array.<string>

getAnimationByIndex(index)

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

getAnimationByName(animationName)

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

getBoundingSphere()

获取模型包围球；优先使用加载阶段算出的视觉包围球
Returns:
Type
BoundingSphere | undefined

getBoundingVolume()

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

getBoundingVolumeHeight()

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

getClipTarget()

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

getJointPaths( [skeletonPath])

查询关节路径
Parameters:
Name Type Argument Description
skeletonPath string <optional>
 骨骼路径；缺省返回全部关节路径的并集
Returns:
关节路径列表
Type
Array.<string>

getModel()

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

getNodeByUsdPath(usdPath)

按 USD Prim 路径访问节点（对应 GSMMLayer.getChildByID）。 返回可操作包装对象；若路径对应的 glTF 节点尚未形成运行时节点，runtimeNode 为 undefined。
Parameters:
Name Type Description
usdPath string USD Prim 路径，如 "/World/Robot/Arm"
Returns:
USDNodeHandle
Type
Object | undefined

getNodeTransform(usdPath)

读取节点当前生效的局部 TRS（含矩阵）。
Parameters:
Name Type Description
usdPath string USD Prim 路径
Returns:
USDNodeTransform
Type
Object | undefined

getOriginWorldCoord()

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

getParentId()

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

getPhysicsJointData(usdPath)

读取单个 UsdPhysics 物理约束关节的描述对象。
Parameters:
Name Type Description
usdPath string 关节 USD Prim 路径
Returns:
关节描述对象： { kind: "joint", schemaName, jointType, body0, body1, axis, lowerLimit, upperLimit, localPos0, localPos1, localRot0, localRot1, drives, apiSchemas } body0/body1 为绑定刚体 Prim 路径；localPos/localRot 按 metersPerUnit 已换算为米； drives 形如 { linear?: {...}, angular?: {...} }。
Type
Object | undefined

getPhysicsJointPaths()

查询全部 UsdPhysics 物理约束关节的 USD Prim 路径。 识别依据：Prim 上应用了 UsdPhysicsJoint / UsdPhysicsRevoluteJoint 等关节 schema （USD 资产以 Xform + apiSchemas 或类型化 Prim 书写）。
Returns:
关节路径列表（无物理关节时为空数组）
Type
Array.<string>

getPhysicsRigidBodyPaths()

查询全部 UsdPhysicsRigidBodyAPI 刚体 Prim 路径。 一个路径对应一个物理刚体；其子 Collision/Mesh 是该刚体的碰撞形状，不是独立刚体。
Returns:
Type
Array.<string>

getUsdCableDataByPath()

查询 USD 钢缆元数据（BoomCable / BasisCurves）。不进物理，仅供 RopeLines。
Returns:
Type
Record.<string, Object> | null

getUsdCustomAttributesByPath(usdPath)

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

getUsdPhysicsDataByPath()

查询当前模型加载到的全部 UsdPhysics 关节数据映射（只读引用）。
Returns:
Type
Record.<string, Object> | null

invalidateBoundingVolume()

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

localToWorldPosition(localPosition)

将模型局部坐标转换为世界坐标
Parameters:
Name Type Description
localPosition Cartesian3 模型局部坐标
Returns:
世界坐标
Type
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 ModelAnimation 目标动画实例

removeDragHandle()

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

<protected> removeFrom(callByManager)

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

removeMultiClippingPlane(id)

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

resetNodeTransform(usdPath)

恢复某节点到原始局部变换（清除覆盖态；userAnimated 复位后预烘焙动画可重新接管该节点）。
Parameters:
Name Type Description
usdPath string USD Prim 路径
Returns:
是否成功
Type
Boolean

resolveNode(usdPath)

把 USD 路径解析成节点句柄。逐帧动画在首帧调用一次，之后把句柄交给 setNodeTransformsBatch，不再按名字查找。
Parameters:
Name Type Description
usdPath string USD Prim 路径
Returns:
Type
Object | null

setClippingPlanes(value)

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

setMultiClippingPlanes(value)

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

setNodeTransform(usdPath, trs)

实时设置单节点局部 TRS（对应 GSMMLayer 改 Child.TRS）。模型节点与关节统一经此控制节点位姿： - Skeleton 蒙皮骨骼关节（bone）为参与蒙皮的节点，修改即可驱动蒙皮形变； - UsdPhysics 约束关节 Prim 的位姿不驱动约束两侧刚体，转动请作用于 body1 部件节点或交给物理引擎。 未提供的分量取该节点当前局部值；立即写入 sceneGraph 运行时节点，后续可再调用 applyNodeTransforms() 汇总刷新。
Parameters:
Name Type Description
usdPath string USD Prim 路径
trs Object USDNodeTransformInput
Returns:
是否设置成功（路径未解析返回 false；模型未就绪时先排队，applyNodeTransforms 后生效）
Type
Boolean

setNodeTransformsBatch(list)

批量设置多个节点的局部 TRS（逐帧动画/整帧播放首选）。 与逐个 setNodeTransform 的区别：只写覆盖态，最后统一写运行时节点； 子树刷新按父子链去重（祖先已在本批时，后代由祖先的递归刷新覆盖）， 因此同一帧内整条关节链只刷新一次，而不是每个节点各刷一遍。
Parameters:
Name Type Description
list Array.<Object> 批量项数组。节点用 path / usdPath / node_name，或首帧 resolveNode 得到的 node 句柄。 TRS 字段 translation / rotation / scale 与 setNodeTransform 一致
Returns:
实际写入运行时节点的数量
Type
number

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 Cartesian3 世界坐标
Returns:
ENU 偏移坐标
Type
Cartesian3 | undefined

worldPositionToLocal(worldPosition)

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

Events

LOADED

数据加载完成后触发
Type: Object
Properties:
Name Type Description
arguments 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 Matrix4 当前模型变换矩阵
Example
layer.on(Glodon.CIMCube.Global.Defines.LayerEventType.TRANSFORM_CHANGED, function (event) {
  console.log(event.arguments);
})