視覺化空間資料

This tutorial will teach you how to use Cesium’s Entity API for drawing spatial data such as points, markers, labels, lines, models, shapes, and volumes. No prior knowledge of Cesium is needed, but if you have absolutely no experience with it, you might want to start with our first tutorial

本教程將教會你如何是使用Cesium 的Entity API 來繪製空間資料，諸如：points, markers, labels, lines, models, shapes以及volumes。本教程完全不需要您有關於Cesium 的知識儲備，但是如果您是完全沒有經驗，您可以試著從我們最簡單的demo 開始學習。Cesium up and running。

什麼是Entity API

Cesium has a rich API for spatial data that can be split into two categories: a low-level API geared towards graphics developers, commonly referred to as the Primitive API, and a high-level API for data-driven visualization, referred to as the Entity API.

cesium 包含了豐富的API文件，主要分成了兩大類：一類是面向圖形開發人員低層次API，通常我們稱他為Primitiva API。另外一類是驅動資料視覺化的高層次API，我們稱他們為Entity API。

The Primitive API’s primary goal is to expose the minimal amount of abstraction needed to perform the task at hand. It expects us to think like a graphics programmer and uses graphics terminology. It is structured to provide the most performant and flexible implementation for a given visualization type, not for API consistency. Loading a Model is different from creating a Billboard and both are radically different from creating a Polygon. Each type of visualization is its own distinct feature. Furthermore, they each have different performance characteristics and require different best practices to be followed. While it is powerful and flexible, most applications are better served with a higher level of abstraction than what is offered by the Primitive API.

Primitive API的主要目標是公開完成手頭任務所需的最小抽象量。它期望我們像圖形程式設計師一樣思考，並使用圖形術語。它的結構是為給定的視覺化型別提供最高效能和靈活的實現，而不是為了API的一致性。載入一個模型與建立一個廣告牌不同，兩者都與建立一個多邊形截然不同。每種型別的視覺化都是它自己獨特的特性。此外，它們各自具有不同的效能特徵，需要遵循不同的最佳實踐。雖然它強大而靈活，但是大多數應用程式的抽象級別比Primitive API提供的抽象級別更高。

The goal of the Entity API is to expose a set of consistently designed high-level objects that aggregate related visualization and information into a unified data structure, which we call an Entity. It lets us concentrate on the presentation of our data rather than worrying about the underlying mechanism of visualization. It also provides constructs for easily building complex, time-dynamic visualization in a way that fits naturally alongside static data. While the Entity API actually uses the Primitive API under the hood, that’s an implementation detail we will (almost) never have to concern ourselves with. By applying various heuristics to the data we give it, the Entity API is able to provide flexible, high-performance visualization while exposing a consistent, easy to learn, and easy to use interface.

Entity API的目標是公開一組一致設計的高階物件，這些物件將相關的視覺化和資訊聚合到一個統一的資料結構中，我們稱之為Entity。它讓我們專注於資料的呈現，而不是擔心視覺化的底層機制。它還提供了一些構造，以方便地構建複雜的、時間動態的視覺化，這與靜態資料很自然地吻合。雖然Entity API實際上使用了底層API，但這是我們將(幾乎)永遠不用關心的實現細節。通過對我們提供的資料應用各種各樣的啟發式方法，Entity API能夠提供靈活的、高效能的視覺化，同時公開一個一致的、易於學習的、易於使用的介面。

我們的第一個Entity 程式

One of the best ways to learn the basics of the Entity API is by looking at some code. In order to keep things simple, we’re going to build on the Hello World example in Cesium Sandcastle. If you are set up to develop with Cesium locally, feel free to use your own application instead.

學習Entity 的最有效的方法是試著就看一寫程式碼。為了使得這一切變得很簡單我們將會在Cesium 的Sandcastle 下建立Hello World example以方便學習者的檢視。如果您本地已經安裝了Cesium的執行環境，可以嘗試著在自己的應用程式上做簡單的開發試驗。

Suppose we wanted to add a polygon for the US state of Wyoming from a list of longitude and latitude degrees. (Wyoming was chosen because it’s such a simple polygon.) We can copy and paste the below code into Sandcastle to do it:

假設我們想要從經度和緯度的列表中為美國懷俄明州新增一個多邊形。(之所以選擇懷俄明州，是因為它是一個簡單的多邊形。)我們可以將下面的程式碼複製貼上到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鍵），我們可以看到下面的場景：
··············

例項二：

HTML code：

 <script src="../../Build/Cesium/Cesium.js"></script>

    <script src="../Sandcastle/Sandcastle-header.js"></script> <script src="../Sandcastle/Sandcastle-client.js"></script>
  <style>
      @import url(../../Build/Cesium/Widgets/widgets.css);
      @import url(../../Apps/Sandcastle/templates/0.css);

      html, body, #cesiumContainer {
          width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden;
      }
  </style>



</head>
<body>
<div id="cesiumContainer" class="fullSize"></div>
<div id="loadingOverlay"><h1>Loading...</h1></div>
<div id="toolbar">
    <div id="terrainMenu"></div>
    <div id="zoomButtons"></div>
    <div id="toggleLighting"></div>
    <div id="sampleButtons"></div>
</div>

<script>

javascript code:

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

      var cesiumTerrainProvider = new Cesium.CesiumTerrainProvider({
          url : 'https://assets.agi.com/stk-terrain/v1/tilesets/world/tiles',
          requestWaterMask : false,
          requestVertexNormals : true
      });

      viewer.terrainProvider = cesiumTerrainProvider;
      viewer.scene.globe.depthTestAgainstTerrain = true;


      var e = viewer.entities.add({
          corridor : {
              positions : Cesium.Cartesian3.fromDegreesArray([
                  -122.19, 46.1914,
                  -122.21, 46.21,
                  -122.23, 46.21
              ]),
              width : 2000.0,
              material : Cesium.Color.GREEN.withAlpha(0.5)
          }
      });
      viewer.zoomTo(e);

      Sandcastle.reset = function () {
          viewer.entities.removeAll();
      };

編譯執行之後的效果:

Since one of our goals is to make Cesium code easy to understand, hopefully the above is self explanatory. We create the Viewer widget, which serves as the base for almost all Cesium applications, and then add a new Entity via viewer.entities.add. The object we pass to add is just an options parameter which provides initial values. The return value is the actual entity instance. Finally, we call viewer.zoomTo to make sure the entity is in view.

因為我們的目標之一是讓Cesium程式碼易於理解，希望上面的程式碼是不言而喻的。我們建立了Viewer小部件，它是幾乎所有的Cesium應用程式的基礎，然後通過Viewer.enti.add新增一個新的Entity。我們傳遞給新增的物件只是一個選項引數，它提供初始值。返回值是實際的Entity例項。最後,我們呼叫viewer.zoomTo以確保實體在檢視中。

There are an incredible amount of Entity options available, but for now we specify translucent red for the interior of the polygon and a black outline for the border. We also give the entity a display name of “Wyoming”.

實際上Entity 有很多的引數可以用，但是我們現在只是提供了一個內紅外面是黑邊的輪廓。我們也給了這Entity個顯示名稱“Wyoming”。