An open-source JavaScript library for world-class 3D globes and maps :earth_americas:

Fixes #5167

Added the ability to create a partial ellipsoid volume using new ellipsoid geometry options: innerRadii, azimuthMin, azimuthMax, elevationMin, elevationMax.

For example: viewer.entities.add({ position: Cesium.Cartesian3.fromDegrees(-100, 40, 5000), ellipsoid: { radii: new Cesium.Cartesian3(1500000, 1000000, 800000), innerRadii: new Cesium.Cartesian3(500000, 400000, 300000), azimuthMin: 0, azimuthMax: 250, elevationMin: 20, elevationMax: 70, material: Cesium.Color.DARKCYAN.withAlpha(0.3), outline: true } });

Here is the thread in the forum that this originated from.

There are a few items that might need some work, but hopefully the hard part is done.

• [x] Unit tests
• [x] Sometimes an exception is thrown when the geometry spans a pole or meridian if 2D mode is enabled. Wasn't sure what was happening. 3D works fine.
• [x] Not supported for vertexFormat of: st, tangent, bitangent. I wasn't sure what was going on there. There are TODOs in the code where this needs work.
• [x] I did not duplicate the point at the poles of the ellipsoid. I couldn't tell why this was necessary.

This work is released under U.S. DoD Distribution Statement A: Approved for public release. Distribution is unlimited.

Adds the ability to layer imagery from multiple sources and adjust the alpha of each independently. It also has a new architecture for rendering the surface of the globe that is a big step toward rendering terrain. For starters, check out the two new Sandcastle apps: "Imagery Layers" and "Map Projections".

Most of the action happens (or at least starts) in CentralBodySurface.js. If you want to understand how it works, the (four line) update function is the place to start.

There is no shortage of additional things that could be done, but I think this is a significant improvement from master and is worthy of a review.

For #2594

This PR adds support for different types of shadows including cascaded directional shadows, spot light shadows, and point light shadows. It also adds the concept of derived commands which are used for OIT, shadows, and later 3D Tiles.

By default the scene contains a shadow map whose light source is the sun. It is disabled by default, but can be enabled with scene.shadowMap.enabled = true.

Shadow default settings:

| Type | Casts Shadows | Receives Shadows | | --- | --- | --- | | Globe | False | True | | Primitives | False | False | | Models | True | True |

Any of these can change by setting castShadows or receiveShadows.

TODO

• [x] Unit tests
• [ ] Cast shadows for terrain tiles that are out of view: on the shadows-globe branch.
• [x] Figure out the best approach approach for shadows when the light source is below the horizon. Currently if the globe casts shadows, the surface will be completely shadowed and dark. Maybe day-night shading should be on if shadows are on.
• [ ] Possible support for GroundPrimitive if needed.
• [x] Integration with higher level constructs like Viewer.
• [ ] 2D and Columbus view support.
• [ ] Screenshots for twitter
• [ ] Tech blog post
• [ ] Tutorial, including use cases
• [x] Fix IE11 and Edge - no glPolygonOffset support

Testing TODO

• [x] Review ShadowMap.js
• [x] Step through in debugger
• [x] FPS with shadows on/off to get a ballpark
• [x] Retest aircraft and satellite CZMLs
• [x] Test with lots of 3D models
• [x] Terrain

TODO now or later

• [ ] Use a good LOD when selecting tiles only in the shadow map frustum, e.g., not SSE from the light's perspective
• [ ] Do not request imagery for tiles only in the shadow map frustum

Added Karma support as a first step for integrating tests as part of Travis-CI build process.

• Added Karma and necessary karma plugins to package.json, including launchers for:
  • Chrome
  • Firefox
  • IE
  • Safari
• Configured Karma to run jasmine tests
• Added test and test-all targets to gulpfile.js
  • test runs karma tests using browser specified in config file, currently Chrome
  • test-all runs karma tests using all browsers available

TODO

• [x] Add back in minified release and webGL validation support.
• [x] Update wiki for new test targets (categories and the two above)

Post merge See #3571

Fixes #5025

Opening a PR for some early review, and also to say this is "stable" if anyone wants to play with it. TODO before full review:

• [x] texcoord rotations
• [x] Support for 2D/CV
• [x] better picking?
• [x] fix log depth incompatibility?
• [x] cleanup/doc
• [x] tests
• [x] fix planar texture coordinates (see below)
• [x] IE fallback
• [x] update CHANGE.md, Sandcastle?
• [x] on 3D Tilesets (fallback)

This PR adds support for materials on ground primitives and also adds batching for non-overlapping, "similarly sized" ground entities with the same material. Quick rundown of how things work:

Materials on Ground Primitives

Normals and texture coordinates and the like are computed in the fragment shader, almost like a post-process. Normals are easy - sample the depth texture (which has to be enabled for this to work), do some eye space math, lovely. Texture coordinates are done in either of two ways:

• for entities large enough that the curve of the Earth is noticeable, a world position is computed from the depth texture and is then used to approximate the latitude/longitude at the fragment using spherical coordinates and approximate inverse trigonometry. This spherical coordinate is then compared with a spherical extent per-instance attribute to compute [0-1] range texcoords.
• for small entities, we compute the distance from the fragment in eye space to a pair of planes, also in eye space, which are computed in the vertex shader from a double-precision position and a pair of offset vectors that form a bounding box in the local ENU coordinate system centered around the entity.

Batching

We couldn't batch ground entities before because of overdraw problems - the shadow volumes used to color terrain often extend well beyond the area they're supposed to cover in screen space and sometimes overlap in the camera plane, leading to artifacts.

This PR adds the ability to use texture coordinates to clip fragments outside a lat/long volume (rectangle) in space, preventing overdraw as long as the batched primitives' rectangles on the globe don't overlap.

Ground entities with per-instance color are no longer batched by color but based on overlap, so it's now possible to render ~10,000 uniquely colored non-overlapping ground entities in a scene on a mid-range mobile GPU like the GT 750M without crashing. More performance anecdotes to follow.

We may also want to discuss if batching everything that's batchable is a little naive, since in some cases we can actually suffer from loss of culling benefits (I think...).

Changes from PRs #6065 and #6107 Opt in fix for #1865

Created opt-in requestRenderMode which will only render the scene when needed. Renders can be triggered as needed by calling requestRender(), for example if picking a feature should change it's color, or you make changes to the scene via the API.

We render each time the simulation time change exceeds scene.maximumRenderTimeChange, which defaults to 0.5 seconds. It can be set to undefined or Infinity to never change based on simulation time.

Besides simulation time changes and calls to requestRender, always render when:

• The camera changes
• Web worker returns, successfully or with an error
• RequestScheduler fulfills a request, successfully or not
• A FrameState.afterRender function was called (this is used thorough the code base when changes are made after a render to keep the current state. An example would be when a new LOD of a tileset is shown or when a model is ready)
• Globe tiles are loaded
• ImageryLayers are added, removes, shown, hidden, or moved.
• The scene morphs

In addition, I refactored some of the update/render logic in Globe, QuadtreePrimitive, and GlobeSurfaceTileProvider so that loading new tiles will continue to prompt render requests and finish processing the load queue. When the scene has requestRenderMode enabled and there is a large or undefined maximumRenderTimeChange, the globe will still load in completely, and changing terrain providers or imagery, and loading in higher level tiles when the camera changes will automatically trigger a render.

Progress toward #4846. I would love to have some initial feedback on this

This replaces the debug options in the Sandcastle example http://localhost:8080/Apps/Sandcastle/index.html?src=3D%20Tiles.html&label=Showcases with an inspector widget. All previous functionality has been ported with the exception of the styling options.

Additional Todos:

• [x] Show URL of clicked tile
• [x] Click on tileset to inspect
• [x] Styling integration
• [x] Port other Sandcastle examples

Example initialization:

viewer.extend(Cesium.viewerCesium3DTilesInspectorMixin);
var model = viewer.cesium3DTilesInspector.viewModel;

model.tileset = new Cesium.Cesium3DTileset({
    url: ...
});

Preview:

For #449, #549, and #1060.

• Default panning now picks the terrain.
• Modified the default camera tilt mouse behavior to tilt about the point clicked.
• Added camera collision detection with terrain to the default mouse interaction.
• Added the following methods to IntersectionTests: rayTriangle, lineSegmentTriangle, raySphere, and lineSegmentSphere.
• Fixed camera rotation near the camera's constrained axis.
• Added Globe.getHeight and Globe.pick for finding the terrain height at a given Cartographic coordinate and picking the terrain with a ray.

A start for post processing effects in Cesium. I trimmed down this PR so it only applies to scene post-processing. Per-entity post processing will be ready soon too, but I want to keep this PR a bit simpler.

@byumjin u_depthTexture now works so you can test out SSAO. However it uses the last frustum's depth only! This actually works okay for some situations, but to guarantee that only one frustum is rendered, set scene.farToNearRatio to a large number like 100000000.0.

I'll bump again when this is ready to review.

To-do:

• [x] Merge lens flare, HBAO, DOF, toon shading, bloom effects: https://github.com/AnalyticalGraphicsInc/cesium/pull/5498
• [x] Put PostProcessLibrary shaders in .glsl file
• [x] Fix FXAA - it is now a post process stage but isn't working. It seems like FXAA requires LINEAR filtering on its texture, but PostProcess uses NEAREST for everything
• [x] Scissor test considerations - no changes have been made to the post processing files related to https://github.com/AnalyticalGraphicsInc/cesium/pull/5225/
• [x] Update sun post-process to use this, separate PR
• [x] Smarter resource allocation and sharing
• [x] ~~Consolidate depth textures from all frustums, separate PR~~ Log depth
• [ ] Add entity support, separate PR
• [x] Lens flare artifact, #5932
• [x] Doc
• [x] Tests
• [x] Update CHANGES.md

There's a lot more I could do here, but I think it's reasonable to merge it into master in its current state.

I suspect the most controversial thing here is the location of the new widget in the Viewer. I originally had it in the top left, but @emackey made the excellent point that we should reserve that for app-specific functionality.

This branch includes all the bingKey changes as well, so the diff will get simpler once that branch is merged.

Opening a PR to indicate that this is "stable" enough to preview and for preliminary review, but there's still a decent amount of work to be done.

Features:

• support for PolylineMaterialAppearance
• mitered polylines
• batching multiple instances with per-instance show and line width

Implementation notes:

More details in https://github.com/AnalyticalGraphicsInc/cesium/issues/2172#issuecomment-385685782. We're using a single-pass, globe-depth-based algorithm. ~For each line segment in the polyline we generate a geometry instance volume that has several planes encoded in the batch table. For each fragment on the volume, we look up the globe depth to compute a terrain position in eyespace and clip this position based on the planes from the batch table. The planes are also used to compute the position's distance from the center and ends of the line for material support.~

~Due to the batch table dependence and mapping of attributes from multiple instances to a single pick ID, this PR introduces a new Primitive type, GroundPolylinePrimitive. There's also a new user-facing geometry, GroundPolylineGeometry, that doesn't actually have a createGeometry function but rather gets decomposed into individual volumes that are then used to generate vertex buffers and attributes.~

~This is a little troublesome for asynchronous geometry since GroundPolylineGeometry's computation currently happens on the main thread, with the worker threads mostly just converting chunks of this into the combined vertex buffer. In practice this doesn't seem to be a huge problem, but it's something we should talk about.~

For each line segment in the polyline we generate a volume with vertex attributes that describe the line segment using a series of planes. For each fragment on the volume, we look up the globe depth to compute a terrain position in eyespace and clip this position based on the planes from the vertex attributes. The planes are also used to compute the position's distance from the center and ends of the line for material support.

The planes differ between 2D and 3D, and I haven't figured out yet how to interpolate them for morphing, so there's a new Primitive type that issues draw commands with different shaders for 2D and morph. When morphing we actually just draw the volumes themselves with materials, which seems acceptable because the camera goes so far away during the morph anyway.

• [x] I should also do load and runtime comparisons with a hack that attempts to simulate polylines using corridors or something.

TODO:

• [x] Integrate with changes in https://github.com/AnalyticalGraphicsInc/cesium/pull/6434 for better geometry heights
• [x] batch per-instance colors
• [x] doc and specs, compatibility checks
• [x] spruce up Sandcastle example
  • more geometry cases
  • selection indicator?
  • volume debug toggle
  • Z ordering/Z ordering with GroundPrimitives

Couple Post-PR roadmap items:

• Entity API integration (priority)
• Investigate smear reduction with something like screen-space partial derivatives
• terrain height and volume length improvements
• Evaluate whether dashed lines should "swim" or stay put
• Investigate fixes for floating point problems with very long arrow lines

Ellipsoid clipping was broken in two ways:

• The intersection against the ellipsoid was not taking into account the height difference between the clip height and the shape height. So even if the clip height was less than the shape height the intersection would act as if it hit the shape height.
• Voxels with infinitely thin clipping bounds would always render the topmost voxels. Several RENDER related defines were incorrectly used in convertUvToCylinder and convertUvToEllipsoid.

In this sandcastle you can see that changing the clipping min/max height to the same value works now. It correctly samples data in the middle of the voxel grid rather than the outer edge.

Before|After --|-- |

Cesium3DTilesVoxelProvider expects tilesets to be structured in a specific way. It should be documented in the constructor.

• Single root tile with content
• Must use 3DTILES_voxel_content
• Must use implicit tiling. Only OCTREE subdivision scheme is allowed.
• Sphere bounding volume disallowed
• Empty tiles disallowed
• Allowed types: SCALAR, VEC2, VEC3, VEC4
• Allowed component types: TBD

Recommended but not required:

• Statistics min and max for each property for custom shaders
• TILESET_TILE_COUNT semantic as optimization hint. https://github.com/CesiumGS/cesium/pull/10996

One of the visual quality improvements we want to tackle next is rendering sharp edges for opaque voxels.

It's possible to approximate sharp edges by setting a smaller step size, but this hurts performance and may cause the ray to miss the dataset completely if it exceeds STEP_COUNT_MAX before it hits a non no-data value.

options.jitter was added to improve the visual quality, but it's still not great.

No jitter|Jitter --|-- |

This isn't always a problem. For example, if a voxel is on the edge of shape it looks nice and crisp. That's because the ray casting starts from the point of the first intersection and the math to determine the intersection point is fairly precise. It's only when it starts traversing through space (i.e. noData values or translucent values) before it hits an opaque voxel that the visualization becomes non crisp. You can see that near the top of the screenshot below.

Option A: Since we know the intersection math is precise, one possible solution might be to step until we hit an opaque value, then do a ray intersection against that individual voxel. That will give us the exact t that the ray enters the voxel. One problem is that if the step size is large enough it could jump over the corner of the voxel, and we're back where we started.

Option B: This could be extended further so that we don't do stepping at all, and always do ray-shape intersections even through empty space. That's what the bottom ray is doing. I'm worried that this will have terrible performance for cylinders and ellipsoids because there will be many shape intersections to get to the first opaque voxel.

These are just starting points for thinking about the problem, need to try some stuff out to see what works.

Currently voxels are always rendered above objects in the OPAQUE and TRANSLUCENT pass.

Some different options for improving this:

1. Render the VOXELS pass before the OPAQUE pass. This will have the opposite effect where opaque geometry will always render above voxels.
2. In IntersectDepth.glsl, read from the currently bound depth texture instead of czm_globeDepthTexture. The latter only includes depth from the GLOBE and CESIUM_3D_TILE passes, while the former includes depth from all previous passes. This might require some plumbing with textures, framebuffers on the JavaScript side.
3. Participate in depth testing the normal WebGL way. One way to do that is to write depth when the alpha becomes fully saturated and enable depthTest and depthMask in the renderState. The main problem with this approach is that the entire fragment gets discarded if the depth test fails, so any translucent color accumulation gets lost. Of course this wouldn't be a problem for fully opaque voxels.

And some future ideas:

• How do we handle different VoxelPrimitives depth testing against each other? Currently we don't: the VoxelPrimitive that's rendered last has priority.
• How do we handle translucency? VoxelPrimitive draw commands do not participate in OIT.

A tile's geometric error is computed automatically in SpatialNode based on the approximate voxel size. When loading voxels as 3D Tiles the geometric error in tileset.json is ignored.

The correct behavior would be to expose a geometricError property in VoxelProvider. Cesium3DTilesVoxelProvider would set this to the root tile's geometricError. Other voxel providers might leave this undefined. When undefined, geometric error would be computed automatically like it is now. When defined geometric error would be computed as provider.geometricError / Math.pow(2, level).

The voxel code allows for creating infinitely thin shapes, which is a handy feature for inspecting individual slices of voxel data. There are some artifacts though:

• When making a shape infinitely thin via min/maxBounds it always renders the front side. Instead it should render just the side that was hit. This happens for most shape types. Note: this bug only happens for min/maxBounds, not min/maxClippingBounds. See message previously in convertUvToEllipsoid.glsl:

    #if defined(ELLIPSOID_HAS_SHAPE_BOUNDS_HEIGHT_FLAT)
        // TODO: This breaks down when minBounds == maxBounds. To fix it, this
        // function would have to know if ray is intersecting the front or back of the shape
        // and set the shape space position to 1 (front) or 0 (back) accordingly.
        float height = 1.0;

• Ellipsoids only render one side of the shape when the latitude range is zero. This happens for both min/maxBounds and min/maxClippingBounds.