Cesium中的Entity API和Primitive API

Cesium中提供两类API：

（1）面向图形开发人员的底层API，通常称为“Primitive API”。该API暴露最小限度的抽象，使用图形学术语，具有很大的灵活性，需要具有图形学编程的知识；

（2）高级别的数据驱动的API，称为“Entity API”。该API使用一致性设计的、高级别的对象来管理一组相关性的可视化对象，其底层使用Primitive API；

Entity API简介

Cesium提供Entity API来绘制空间数据，例如点、标记、标签、线、3D模型、形状、立体形状（volume）。下面是Entity API的简单例子，用红色半透明区域标记出美国怀俄明州：

 var viewer = new Cesium.Viewer('cesiumContainer'); //创建一个查看器（Viewer widget）  

 var wyoming = viewer.entities.add({  //添加一个实体，仅需要传递一个简单JSON对象，返回值是一个Entity对象  

 name : 'Wyoming',  

  polygon : {  

   hierarchy : Cesium.Cartesian3.fromDegreesArray([//一组地理坐标  

                               -109.080842,45.002073,  

                             -105.91517,45.002073,  

                              -104.058488,44.996596,  

                          -104.053011,43.002989,  
                              -104.053011,41.003906,  

                            -105.728954,40.998429,  

                             -107.919731,41.003906,  

                            -109.04798,40.998429,  

                         -111.047063,40.998429,  

                           -111.047063,42.000709,  

                              -111.047063,44.476286,  

                               -111.05254,45.002073]),  

    material : Cesium.Color.RED.withAlpha(0.5), //材质  

    outline : true, //是否显示轮廓  

    outlineColor : Cesium.Color.BLACK //轮廓的颜色  

   }  

});  

 viewer.zoomTo(wyoming);//缩放、平移视图使实体可见   

材质（Material）与轮廓（Outline）

多数形状均支持通过一致的方式来设置属性、控制外观：

1.  （1）fill：布尔型，用于指定目标形状是否被填充
   

2.  （2）outline：布尔型，用于指定是否绘制形状的边缘
   

3.  （3）material：如果fill为true，该属性可以控制填充的材质类型
   

一个例外是多段线，可以设置outlineWidth 、outlineColor、glowPower 等属性。

高度与拉伸（Extrusion）

所有的形状均默认均是沿着地表的，目前圆形、椭圆、矩形可以在一定高度浮空显示，或者拉伸为Volume。

需要注意：Cesium总是使用米、弧度、秒为度量单位。下面是一个例子：

1. wyoming.polygon.height = 200000; //设置高度

2. wyoming.polygon.extrudedHeight = 250000; //设置拉伸高度

在Viewer中可用的Entity特性

除非显式禁用，点击实体后会显示SelectionIndicator小器件，以及一个信息框。通过设置Entity.description，可以在信息框中显示任何HTML内容。

镜头控制

zoomTo方法可以立即定位到某个位置，而flyTo则是通过动画方式转移到某个位置，这两个方法均可以传递EntityCollection对象，并且均是异步方法，返回一个Promises对象

默认情况下，镜头是朝北、45度倾斜查看地球。下面的代码可以让镜头朝东、倾斜三十度查看：

1.  //镜头顺时针旋转九十度，即东向  

2.  **var** heading = Cesium.Math.toRadians(90);  

3.  //镜头倾斜30度俯视  

4.  **var** pitch = Cesium.Math.toRadians(-30);  

5.  viewer.zoomTo(wyoming, **new** Cesium.HeadingPitchRange(heading, pitch)).then(**function**(result){  

6.      //执行完毕后，进行的动作  

7.      **if** (result) { //如果镜头切换成功，则result=true  

8.          viewer.selectedEntity = wyoming;  

9.      }  

10. });  

有时需要镜头跟踪某个实体（使居中）而不是地球，可以使用如下代码：

1.  wyoming.position = Cesium.Cartesian3.fromDegrees(-107.724, 42.68);  

2.  viewer.trackedEntity = wyoming;  //跟踪某个实体。如果调用zoomTo、flyTo自动取消跟踪  

管理Entity

EntityCollection对象是一个从Entity Id到Entity的关联数组，其提供例如add、remove、removeAll之类的常规函数，用于添加或者删除某个Entity：

1.  //添加一个实体，并且提供ID  

2.  viewer.entities.add({  

3.    id : '182bdba4-2b3e-47ae-bf0b-83f6fde285fd'  

4.  });  

5.  //获取一个实体  

6.  **var** entity = viewer.entities.getById('uniqueId')  

7.  //获取一个实体，如果不存在则创建之  

8.  **var** entity = viewer.entities.getOrCreateEntity('uniqueId');  

9.     

10. //当添加、删除、修改EntityCollection中的Entity时，可以获得事件通知  

11. **function** onChanged(collection, added, removed, changed){  

12.     //add、removed、changed是增删改的Entity数组  

13.     **for**(**var** i = 0; i < added.length; i++) {  

14.           

15.     }  

16. }  

17. viewer.entities.collectionChanged.addEventListener(onChanged);  

18.    

19. //大批量操作时，临时禁用事件可以提高性能  

20. viewer.entities.suspendEvents();  

21. //执行各种Entity操作  

22. viewer.entities.resumeEvents();  

点、图标和标签

添加一个点、标签或者图标很简单：

1.  **var** viewer = **new** Cesium.Viewer( 'cesiumContainer' );  

2.     

3.  **var** citizensBankPark = viewer.entities.add( {  

4.      name : 'Citizens Bank Park',  

5.      position : Cesium.Cartesian3.fromDegrees( -75.166493, 39.9060534 ),  

6.      point : { //点  

7.          pixelSize : 5,  

8.          color : Cesium.Color.RED,  

9.          outlineColor : Cesium.Color.WHITE,  

10.         outlineWidth : 2  

11.     },  

12.     label : { //文字标签  

13.         text : 'Citizens Bank Park',  

14.         font : '14pt monospace',  

15.         style : Cesium.LabelStyle.FILL_AND_OUTLINE,  

16.         outlineWidth : 2,  

17.         verticalOrigin : Cesium.VerticalOrigin.BOTTOM, //垂直方向以底部来计算标签的位置  

18.         pixelOffset : **new** Cesium.Cartesian2( 0, -9 )   //偏移量  

19.     }  

20.     billboard : { //图标  

21.         image : 'http://localhost:81/images/2015/02-02/Philadelphia_Phillies.png',  

22.         width : 64,  

23.         height : 64  

24.     },  

25. } );  

26.    

27. viewer.zoomTo( viewer.entities );  

3D模型

Cesium支持glTF格式的3D模型，glTF是WebGL、 OpenGL ES、 OpenGL的一种运行时模型格式，在Cesium中创建3D模型很简单：

[javascript] view plain copy

print?

1.  **var** viewer = **new** Cesium.Viewer('cesiumContainer');  

2.  **var** entity = viewer.entities.add({  

3.      position : Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706),  

4.      model : {  

5.          uri : '../../SampleData/models/CesiumGround/Cesium_Ground.gltf'  

6.      },  

7.      scale : 1,//和原始大小相比的缩放比例  

8.      minimumPixelSize :100 //最小尺寸，防止太小而看不见  

9.  });  

10. viewer.trackedEntity = entity;  

默认情况下，模型竖直放置、并且面向东面。可以指定四元组（Quaternion）给Entity.orientation属性，以改变放置的方向：

1.  **var** viewer = **new** Cesium.Viewer('cesiumContainer');  

2.  **var** position = Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706); //位置  

3.  **var** heading = Cesium.Math.toRadians(45.0);//绕垂直于地心的轴旋转  

4.  **var** pitch = Cesium.Math.toRadians(15.0);  //绕纬度线旋转  

5.  **var** roll = Cesium.Math.toRadians(0.0);    //绕经度线旋转  

6.  **var** orientation = Cesium.Transforms.headingPitchRollQuaternion(position, heading, pitch, roll);  

8.  **var** entity = viewer.entities.add({  

9.      position : position,  

10.     orientation : orientation,  

11.     model : {  

12.         uri : '../../SampleData/models/CesiumGround/Cesium_Ground.gltf'  

13.     }  

14. });  

15. viewer.trackedEntity = entity;  

例子中的heading（yaw）、pitch、roll对应了绕Z（垂直轴）、Y（维度方向）、X（经度方向）进行旋转，正数表示顺时针旋转（由于相对运动，在浏览器上看起来是地球在逆时针旋转），可以参考下图理解（人面向北面，摇头heading、点头pitch、歪头roll）：

属性系统

Cesium提供了一些快捷方式来设置属性，例如outline:true，但是尝试使用e.polygon.outline这样的形式来获取轮廓时，会得到一个ConstantProperty对象，如果不使用快捷方式，则需要编写更多的代码，例如：

1.  polygon.outline = **new** Cesium.ConstantProperty(**true**);  

2.  polygon.outlineColor = **new** Cesium.ConstantProperty(Cesium.Color.BLACK);  

所有属性的实例均是Property的子类型，引入属性类层次而不是使用基本类型的原因是，某些属性是随着时间而变化的。

要得到属性的原始值，需要调用Property.getValue()方法，例如：

1.  //获取当前时间点，多边形轮廓是否存在  

2.  polygon.outline.getValue(viewer.clock.currentTime)