AnalyticalGraphicsInc/cesium — pull request #2315 by mramato (2014-12-10 04:30:29+00:00)
Title: Entity ease of use

This isn't ready yet, but I'm opening it up for early review.

The goal here is to further enhance the `DataSource` layer so that it can be easier to use for beginners and also become the primary high-level API for Cesium. This would eliminate the need for the "mid-level" api we've considered adding, such as the current `Polygon` primitive (which would eventually be made obsolete). While the overall goal is still a long way off, this PR gets it a lot closer.

This change looks bigger/scarier than it is, but it mainly does 3 things:
1. For simple values, you no longer need to create an instance of `ConstantProperty`, `ConstantPositionProperty`, `ColorMaterialProperty`, or `ImageMaterialProperty`. We create a new property on the fly if needed, mirroring the behavior of C# `implicit` types. `createPropertyDescriptor` has been deleted and replaced with several `PropertyHelper` functions to achieve this goal.
2. All of the constructor functions for `Entity` and the various `xxxGraphics` objects now take an `options` argument which mirrors their public properties.
3. A new `CustomDataSource` object, which makes easy to add Entities to a viewer instances in very little code. This is in lieu of simply having an `entities` property on `Viewer`. It fits a little better in the existing architecture. `viewer.entities` isn't off the table, but I think it would require more rework for not a lot of benefit. I've also thought about renaming the existing `DataSource` interface to something else (`DataSourceInterface`?) and renaming `CustomDatasource` to `DataSource`. This would be a non-breaking change that only affects documentation.

Here's a complete Sandcastle example that puts the above changes to use.
```
var viewer = new Cesium.Viewer('cesiumContainer');
viewer.extend(Cesium.viewerEntityMixin);

var source = new Cesium.CustomDataSource();

var entity = source.entities.add(new Cesium.Entity({
name: 'example',
description : 'HTML description!',
position : Cesium.Cartesian3.fromDegrees(3, -4, 50000),

label : new Cesium.LabelGraphics({
text : 'A label!',
verticalOrigin : Cesium.VerticalOrigin.BOTTOM
}),

point : new Cesium.PointGraphics({
pixelSize : 15,
color : Cesium.Color.RED
}),

polygon : new Cesium.PolygonGraphics({
material : Cesium.Color.BLUE,
extrudedHeight : 50000,
outline: true,
outlineColor : Cesium.Color.BLACK,
positions : [Cesium.Cartesian3.fromDegrees(-2, -2),
Cesium.Cartesian3.fromDegrees(3, -4),
Cesium.Cartesian3.fromDegrees(2, -2),
Cesium.Cartesian3.fromDegrees(2, 2),
Cesium.Cartesian3.fromDegrees(-2, 2)]
}),

viewFrom : new Cesium.Cartesian3(100000, 0, 100000)
}));

viewer.dataSources.add(source);
viewer.trackedEntity = entity;
```

Stuff that still needs to be done, regardless of feedback.
* [ ] Add tests
* [ ] Update documentation
* [ ] Add Sandcastle example
* [ ] Write blog post/tutorial for basic functionality.
* [ ] Update CHANGES
* [ ] Fix circular dependency in `PropertyHelper`

Let me know what you guys think.