Add support for polygon holes to CZML

[shunter]

Holes are specified as an array of arrays of positions. Polygon holes can be constant, interval-based, or defined as references. Using references allows for each vertex of the hole to be expressed as a sampled value. This is essentially the same limitations as the existing array of positions.

These changes also change the behavior of PolygonGraphics.hierarchy to always produce a PolygonHierarchy.

This makes the behavior more closely match the documentation. Previously, CzmlDataSource would shove a Cartesian array into the hierarchy property, and then all use sites had compatibility logic to adapt. For backwards compatibility, we preserve the existing behavior of allowing an array of positions to be set. The ability to set an array of positions was undocumented, though some Sandcastle examples do this. CzmlDataSource no longer sets the incorrect type of data into hierarchy, because we now need to handle holes.

Fixes #3826

Sample CZML syntax for a constant set of holes.

 {
    "polygon" : {
        "positions" : {
            "cartographicDegrees" : [
                -82.0, 40.8, 0,
                -83.0, 36.5, 0,
                -76.0, 35.6, 0,
                -73.5, 43.6, 0
            ]
        },
        "holes" : {
            "cartographicDegrees" : [
                [
                    -81.0, 40.0, 0,
                    -81.0, 38.2, 0,
                    -79.0, 38.2, 0,
                    -78.0, 40.8, 0
                ],
                [
                    -77.5, 36.7, 0,
                    -78.5, 37.0, 0,
                    -76.5, 39.6, 0
                ]
            ]
        }
    }
}

Existing Sandcastle examples for CZML polygons now demonstrate holes using constant, intervals, and references.

[cesium-concierge]

Thanks for the pull request @shunter!

• ✔️ Signed CLA found.
• ❔ CHANGES.md was not updated.
  • If this change updates the public API in any way, please add a bullet point to CHANGES.md.

Reviewers, don't forget to make sure that:

• Cesium Viewer works.
• Works in 2D/CV.
• Works (or fails gracefully) in IE11.

[shunter]

As an additional side note I spent some effort on code coverage for CzmlDataSource. In particular, loading intervals of arrays of references was broken (pretty esoteric, admittedly)

[mramato]

Awesome, thanks @shunter. Will look at this ASAP.

[emackey]

Should this say "array of objects" instead of "object"? And is it a breaking API change?

[shunter]

Not a breaking change, the documentation was wrong, not the code.

[mramato]

Just to clarify, PolygonGraphics.hierarchy.getValue in master would return a Cartesian3 array or a PolygonHierarchy depending on what the user set, right? And in this branch it will now always return a PolygonHierarchy? Technically the documentation said it was always a PolygonHierarchy but was wrong?

If the above is correct, I still think it's worth mentioning in CHANGES, even if we don't consider it a breaking change. Just treat it like a bug and state that it now always returns a PolygonHirearchy

[mramato]

That's the only question/comment I have. Another flawless PR, thanks @shunter

[shunter]

PolygonGraphics.hierarchy.getValue in master would return a Cartesian3 array or a PolygonHierarchy depending on what the user set, right?

It would store whatever value was set into it, without really caring what it was, which is what nearly all properties do.

And in this branch it will now always return a PolygonHierarchy? Technically the documentation said it was always a PolygonHierarchy but was wrong?

Yes, it was documented as a property of type PolygonHierarchy but the CZML loading didn't respect that. So the entities created by CZML did not match the documentation.

[mramato]

Thanks, I'll merge once green.

[mramato]

Thanks again @shunter! I couldn't find any "holes" in your work...