title: Cesium how to 'drape' a polygon or line onto terrain surface
body: <p>So, I'm using cesium and I want to add a polygon or line to represent a property boundary on a terrain surface.</p>
  
  <p>My polygon works fine on the flat/Ellipsoid surface, unfortunately however the polygon doesn't automagically drape over the surface when the terrain layer is shown.</p>
  
  <p>Fair enough, I don't actually have the z/height values - so I'm using the <a href="https://cesiumjs.org/Cesium/Build/Documentation/sampleTerrain.html">sampleTerrain.js</a> promise method to interpolate the height values based on the terrain. This part works fine, I get my height values. But then what?</p>
  
  <p>I've tried creating a polygon entity with my height-laden positions, but to no avail - it just ignores the height values. <a href="https://cesiumjs.org/Cesium/Build/Documentation/Polygon.html">When I read the docs</a>, I can really see any reference to height values being ingested - all the "positions" array are two dimensional?</p>
  
  <p>The only reference to height values being considered is in the <a href="http://cesiumjs.org/Cesium/Build/Documentation/PolygonOutlineGeometry.html">PolygonOutlineGeometry</a>, which has a promising looking property called <code>perPositionHeight</code>.</p>
  
  <p>This is essentially what I want - I don't want to set the height of the whole poly, I want every points height value to be used..</p>
  
  <p>Here's one of my unsuccessful attempts:</p>
  
  <p><strong>Entity/Polygon:</strong></p>
  
  <pre><code>var entity = viewer.entities.add({
      polygon : {
          hierarchy : cartesianPositions, //array of positions with z values
          outline : true,
          outlineColor : Cesium.Color.RED,
          outlineWidth : 9,
          material : Cesium.Color.BLUE.withAlpha(0.0),
     }
  });
  </code></pre>
  
  <p><br/>
  <strong>Bottom line:</strong> I just want a polygon or polyline entity that sits nicely on the surface of the terrain.</p>
  
  <p><strong>EDIT:</strong></p>
  
  <p>Using the <a href="http://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=Polygon.html&amp;label=Geometries">Orange Polygon example</a> in the comments of the accepted answer combined with <a href="https://cesiumjs.org/Cesium/Build/Documentation/sampleTerrain.html">sampleTerrain.js</a>, I've been able to simulate 'draping' a polygon onto terrain, with a list of positions that did not have z values, here's a crude example:</p>
  
  <pre><code>var positions = []; // xy position array    
  
  var cesiumTerrainProvider = new Cesium.CesiumTerrainProvider({
      url : '//assets.agi.com/stk-terrain/world'
  });
  viewer.terrainProvider = cesiumTerrainProvider;
  
  // go off and sample the terrain layer to get interpolated z values for each position..
  var promise = Cesium.sampleTerrain(cesiumTerrainProvider, 11, positions);
  Cesium.when(promise, function(updatedPositions) {
  
      var cartesianPositions = Cesium.Ellipsoid.WGS84.cartographicArrayToCartesianArray(updatedPositions);
  
          var entity = viewer.entities.add({
              polygon : {
                    hierarchy : cartesianPositions,
                    outline : true,
                    outlineColor : Cesium.Color.RED,
                    outlineWidth : 9,
                    perPositionHeight: true,
                    material : Cesium.Color.BLUE.withAlpha(0.0),
              }
          });
  
      viewer.flyTo(entity);   
  
  });
  </code></pre>