Cesium中文網：http://cesiumcn.org/ | 國內快速訪問：http://cesium.coinidea.com/
本教程將教讀者如何使用Cesium的實體（Entity）API繪制空間數據，如點、標記、標簽、線、模型、形狀和物體。不需要Cesium的先驗知識，但是如果讀者完全沒有這方面的經驗，那么讀者可能希望從“新手入門中文教程（原創）”開始學習。

什么是實體（Entity）API？

Cesium具有豐富的用于空間數據的API，可以分為兩類：面向圖形開發人員的低級API（通常稱為原始(Primitive)API）和用于數據驅動的可視化的高級API（稱為實體(Entity)API）。

原始API的主要目標是暴露手頭執行任務所需的最小抽象量。它希望我們像圖形程序員一樣思考，并使用圖形術語。它的結構是為給定的可視化類型提供最有性能和靈活性的實現，而不是為了API的一致性。加載一個模型不同于創建一個廣告牌，兩者都與創建多邊形完全不同。每種類型的可視化都有其獨特的特征。此外，它們各自具有不同的性能特征，并且需要遵循不同的最佳實踐。雖然它功能強大且靈活，但大多數應用程序都比Primitive API提供的抽象級別更高。原始API的主要目標是開放手頭當前研發工作的所需的最小抽象量。它希望我們像圖形程序員一樣思考，并使用圖形術語。它的結構是為給定的可視化類型提供最有性能和靈活性的實現，而不是為了API的一致性。加載一個模型不同于創建一個廣告牌（Billboard ），兩者都與創建多邊形完全不同。每種類型的可視化都有其獨特的特征。此外，它們各自具有不同的性能特征，并且需要遵循不同的最佳實踐。雖然它功能強大且靈活，但大多數應用程序都提供比Primitive API的抽象級別更高的服務接口。

實體API的目的是公開一組設計一致的高級對象，這些對象將相關的可視化和信息聚合到一個統一的數據結構中，我們稱之為實體。它讓我們專注于展示我們的數據，而不是擔心可視化的潛在機制。它還提供了易于構建復雜的、時間動態可視化的構造，這種可視化方式與靜態數據自然相適應。雖然實體API實際上在背后使用了原始API(Primitive API)，但這是我們（幾乎）永遠不必關注的實現細節。通過將各種啟發式應用到我們提供的數據，實體API能夠提供靈活的、高性能的可視化，同時公開一致的、易于學習和易于使用的接口。

我們的第一個實體

學習實體API的基本方法之一是通過查看一些代碼。為了讓事情簡單化，我們將在CesiumSandcastle的Hello World例子中構建。如果讀者在本地開發Cesium，可以自由地使用自己的應用程序。

假設我們想從經度和緯度的列表中添加一個美國州懷俄明的多邊形。（懷俄明之所以被選中是因為它是一個簡單的多邊形）我們可以把下面的代碼復制粘貼到Sandcastle去做：

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

var wyoming = viewer.entities.add({
  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]),
    height : 0,
    material : Cesium.Color.RED.withAlpha(0.5),
    outline : true,
    outlineColor : Cesium.Color.BLACK
  }
});

viewer.zoomTo(wyoming);

點擊運行按鈕（或者F8）能看到下面的圖像：

image

因為我們的一個目標是讓Cesium的代碼易于理解，希望這是不言自明的。我們創建了Viewer widget，它充當幾乎所有Cesium應用程序的基礎，然后通過viewer.entities.add. 添加一個新的Entity。我們傳遞的需add的對象只是一個提供初始值的選項參數。返回值是實際的實體實例。最后，我們調用 viewer.zoomTo 以確保實體處于視圖中。
有很多實體選項可用，但是現在我們指定polygon內部的半透明紅色和邊界的黑色輪廓。我們也給實體一個“Wyoming 懷俄明”的顯示名稱。

形狀和物體

有了創建多邊形的基本知識，并且由于實體API的同質性，我們現在可以通過簡單地使用Sandcastle中的示例作為參考來創建各種圖形。下面是支持的形狀和物體的完整列表。

image

材質和輪廓

不管它們的幾何定義如何，所有形狀和物體都有一組共同的屬性來控制它們的外觀。fill屬性是一個布爾值，它指定是否填充了表面的內部，而outline屬性控制形狀的邊緣是否被輪廓化。
當fill設為true，material屬性決定填充物是什么。在接下來的例子中，讓我們創建一個半透明的藍色橢圓。默認情況下，fill是true，outline是false，所以我們只需要指定material。

var entity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(-103.0, 40.0),
  ellipse : {
    semiMinorAxis : 250000.0,
    semiMajorAxis : 400000.0,
    material : Cesium.Color.BLUE.withAlpha(0.5)
  }
});
viewer.zoomTo(viewer.entities);

var ellipse = entity.ellipse; // For upcoming examples

Image

我們也可以將材質指定為一個圖片鏈接：

ellipse.material = '//cesiumjs.org/tutorials/images/cats.jpg';

image

在上述兩種情況下，在賦值時自動為我們創建一個ColorMaterialProperty屬性或ImageMaterialProperty屬性。對于更復雜的材料，我們需要自己創建一個材料屬性實例。目前，實體形狀和物體支持顏色、圖像、棋盤、條紋和網格材料。

棋盤

ellipse.material = new Cesium.CheckerboardMaterialProperty({
  evenColor : Cesium.Color.WHITE,
  oddColor : Cesium.Color.BLACK,
  repeat : new Cesium.Cartesian2(4, 4)
});

image

條紋

ellipse.material = new Cesium.StripeMaterialProperty({
  evenColor : Cesium.Color.WHITE,
  oddColor : Cesium.Color.BLACK,
  repeat : 32
});

image

網格

ellipse.material = new Cesium.GridMaterialProperty({
  color : Cesium.Color.YELLOW,
  cellAlpha : 0.2,
  lineCount : new Cesium.Cartesian2(8, 8),
  lineThickness : new Cesium.Cartesian2(2.0, 2.0)
});

image

輪廓

與fill屬性不同，outline沒有相應的材料，而是依賴于兩個獨立的outlineColor和outlineWidth屬性。outlineWidth只適用于非Windows系統，如Android、iOS、Linux和OS X。這是由于WebGL是如何在Windows上的所有三個主要瀏覽器引擎中實現所限制的。

ellipse.fill = false;
ellipse.outline = true;
ellipse.outlineColor = Cesium.Color.YELLOW;
ellipse.outlineWidth = 2.0;

image

折線

折線是一種特殊情況，因為它們沒有填充或輪廓屬性。相反，他們依靠專門的材料來代替顏色。由于這些特殊材料，不同寬度和輪廓寬度的折線將對所有系統起作用。

var entity = viewer.entities.add({
    polyline : {
        positions : Cesium.Cartesian3.fromDegreesArray([-77, 35,
                                                        -77.1, 35]),
    width : 5,
    material : Cesium.Color.RED
}});
viewer.zoomTo(viewer.entities);

var polyline = entity.polyline // For upcoming examples

image

折線輪廓

polyline.material = new Cesium.PolylineOutlineMaterialProperty({
    color : Cesium.Color.ORANGE,
    outlineWidth : 3,
    outlineColor : Cesium.Color.BLACK
});

image

折現光暈

polyline.material = new Cesium.PolylineGlowMaterialProperty({
    glowPower : 0.2,
    color : Cesium.Color.BLUE
});

image

高度與擠壓

覆蓋在地球上的所有形狀，當前是圓、橢圓、多邊形和矩形，也可以放置在海拔高度或擠壓成一個物體。在這兩種情況下，形狀或物體仍然符合其下方的地球曲率。

對于高度，我們所要做的就是在相應的圖形對象上設置高度屬性，對于上面列出的所有形狀都是一樣的。這可能是提到Cesium總是使用米、弧度和秒作為單位的好時機，除非函數明確地表示了其他情況，比如Cartesian3.fromDegrees。下面的代碼行將多邊形提升到地球上方250000米處。

wyoming.polygon.height = 250000;

image

wyoming.polygon.height = 200000;
wyoming.polygon.extrudedHeight = 250000;

image

Cesium中文網交流QQ群：807482793

Cesium中文網：http://cesiumcn.org/ | 國內快速訪問：http://cesium.coinidea.com/