@cesium/engine 2.2.0 → 2.4.0

package/Source/Scene/createGooglePhotorealistic3DTileset.js

@@ -0,0 +1,53 @@
+import Cesium3DTileset from "./Cesium3DTileset.js";
+import defaultValue from "../Core/defaultValue.js";
+import defined from "../Core/defined.js";
+import GoogleMaps from "../Core/GoogleMaps.js";
+import Resource from "../Core/Resource.js";
+
+/**
+ * Creates a {@link Cesium3DTileset} instance for the Google Photorealistic 3D Tiles tileset.
+ *
+ * @function
+ *
+ * @param {string} [key=GoogleMaps.defaultApiKey] Your API key to access Google Photorealistic 3D Tiles. See {@link https://developers.google.com/maps/documentation/javascript/get-api-key} for instructions on how to create your own key.
+ * @param {Cesium3DTileset.ConstructorOptions} [options] An object describing initialization options.
+ * @returns {Promise<Cesium3DTileset>}
+ *
+ * @see GoogleMaps
+ *
+ * @example
+ * Cesium.GoogleMaps.defaultApiKey = "your-api-key";
+ *
+ * const viewer = new Cesium.Viewer("cesiumContainer");
+ *
+ * try {
+ *   const tileset = await Cesium.createGooglePhotorealistic3DTileset();
+ *   viewer.scene.primitives.add(tileset));
+ * } catch (error) {
+ *   console.log(`Error creating tileset: ${error}`);
+ * }
+ */
+async function createGooglePhotorealistic3DTileset(key, options) {
+  key = defaultValue(key, GoogleMaps.defaultApiKey);
+
+  let credits;
+  const credit = GoogleMaps.getDefaultApiKeyCredit(key);
+  if (defined(credit)) {
+    credits = [credit];
+  }
+
+  options = defaultValue(options, {});
+  options.showCreditsOnScreen = true;
+
+  const resource = new Resource({
+    url: `${GoogleMaps.mapTilesApiEndpoint}3dtiles/root.json`,
+    queryParameters: {
+      key: key,
+    },
+    credits: credits,
+  });
+
+  return Cesium3DTileset.fromUrl(resource, options);
+}
+
+export default createGooglePhotorealistic3DTileset;

package/Source/Shaders/AtmosphereCommon.glsl

@@ -8,8 +8,16 @@ uniform vec3 u_atmosphereRayleighCoefficient;
 uniform vec3 u_atmosphereMieCoefficient;
 
 const float ATMOSPHERE_THICKNESS = 111e3; // The thickness of the atmosphere in meters.
-const int PRIMARY_STEPS = 16; // Number of times the ray from the camera to the world position (primary ray) is sampled.
-const int LIGHT_STEPS = 4; // Number of times the light is sampled from the light source's intersection with the atmosphere to a sample position on the primary ray.
+const int PRIMARY_STEPS_MAX = 16; // Maximum number of times the ray from the camera to the world position (primary ray) is sampled.
+const int LIGHT_STEPS_MAX = 4; // Maximum number of times the light is sampled from the light source's intersection with the atmosphere to a sample position on the primary ray.
+
+/**
+ * Rational approximation to tanh(x)
+*/
+float approximateTanh(float x) {
+    float x2 = x * x;
+    return max(-1.0, min(+1.0, x * (27.0 + x2) / (27.0 + 9.0 * x2)));
+}
 
 /**
  * This function computes the colors contributed by Rayliegh and Mie scattering on a given ray, as well as
@@ -50,14 +58,36 @@ void computeScattering(
         return;
     }
 
+    // To deal with smaller values of PRIMARY_STEPS (e.g. 4)
+    // we implement a split strategy: sky or horizon.
+    // For performance reasons, instead of a if/else branch
+    // a soft choice is implemented through a weight 0.0 <= w_stop_gt_lprl <= 1.0
+    float x = 1e-7 * primaryRayAtmosphereIntersect.stop / length(primaryRayLength);
+    // Value close to 0.0: close to the horizon
+    // Value close to 1.0: above in the sky
+    float w_stop_gt_lprl = 0.5 * (1.0 + approximateTanh(x));
+    
     // The ray should start from the first intersection with the outer atmopshere, or from the camera position, if it is inside the atmosphere.
+    float start_0 = primaryRayAtmosphereIntersect.start;
     primaryRayAtmosphereIntersect.start = max(primaryRayAtmosphereIntersect.start, 0.0);
     // The ray should end at the exit from the atmosphere or at the distance to the vertex, whichever is smaller.
     primaryRayAtmosphereIntersect.stop = min(primaryRayAtmosphereIntersect.stop, length(primaryRayLength));
 
+    // For the number of ray steps, distinguish inside or outside atmosphere (outer space)
+    // (1) from outer space we have to use more ray steps to get a realistic rendering
+    // (2) within atmosphere we need fewer steps for faster rendering
+    float x_o_a = start_0 - ATMOSPHERE_THICKNESS; // ATMOSPHERE_THICKNESS used as an ad-hoc constant, no precise meaning here, only the order of magnitude matters
+    float w_inside_atmosphere = 1.0 - 0.5 * (1.0 + approximateTanh(x_o_a));
+    int PRIMARY_STEPS = PRIMARY_STEPS_MAX - int(w_inside_atmosphere * 12.0); // Number of times the ray from the camera to the world position (primary ray) is sampled.
+    int LIGHT_STEPS = LIGHT_STEPS_MAX - int(w_inside_atmosphere * 2.0); // Number of times the light is sampled from the light source's intersection with the atmosphere to a sample position on the primary ray.
+
     // Setup for sampling positions along the ray - starting from the intersection with the outer ring of the atmosphere.
-    float rayStepLength = (primaryRayAtmosphereIntersect.stop - primaryRayAtmosphereIntersect.start) / float(PRIMARY_STEPS);
     float rayPositionLength = primaryRayAtmosphereIntersect.start;
+    // (1) Outside the atmosphere: constant rayStepLength
+    // (2) Inside atmosphere: variable rayStepLength to compensate the rough rendering of the smaller number of ray steps
+    float totalRayLength = primaryRayAtmosphereIntersect.stop - rayPositionLength;
+    float rayStepLengthIncrease = w_inside_atmosphere * ((1.0 - w_stop_gt_lprl) * totalRayLength / (float(PRIMARY_STEPS * (PRIMARY_STEPS + 1)) / 2.0));
+    float rayStepLength = max(1.0 - w_inside_atmosphere, w_stop_gt_lprl) * totalRayLength / max(7.0 * w_inside_atmosphere, float(PRIMARY_STEPS));
 
     vec3 rayleighAccumulation = vec3(0.0);
     vec3 mieAccumulation = vec3(0.0);
@@ -65,10 +95,17 @@ void computeScattering(
     vec2 heightScale = vec2(u_atmosphereRayleighScaleHeight, u_atmosphereMieScaleHeight);
 
     // Sample positions on the primary ray.
-    for (int i = 0; i < PRIMARY_STEPS; i++) {
+    for (int i = 0; i < PRIMARY_STEPS_MAX; ++i) {
+
+        // The loop should be: for (int i = 0; i < PRIMARY_STEPS; ++i) {...} but WebGL1 cannot
+        // loop with non-constant condition, so it has to break early instead
+        if (i >= PRIMARY_STEPS) {
+            break;
+        }
+
         // Calculate sample position along viewpoint ray.
         vec3 samplePosition = primaryRay.origin + primaryRay.direction * (rayPositionLength + rayStepLength);
-        
+
         // Calculate height of sample position above ellipsoid.
         float sampleHeight = length(samplePosition) - atmosphereInnerRadius;
 
@@ -79,14 +116,20 @@ void computeScattering(
         // Generate ray from the sample position segment to the light source, up to the outer ring of the atmosphere.
         czm_ray lightRay = czm_ray(samplePosition, lightDirection);
         czm_raySegment lightRayAtmosphereIntersect = czm_raySphereIntersectionInterval(lightRay, origin, atmosphereOuterRadius);
-        
+
         float lightStepLength = lightRayAtmosphereIntersect.stop / float(LIGHT_STEPS);
         float lightPositionLength = 0.0;
 
         vec2 lightOpticalDepth = vec2(0.0);
 
         // Sample positions along the light ray, to accumulate incidence of light on the latest sample segment.
-        for (int j = 0; j < LIGHT_STEPS; j++) {
+        for (int j = 0; j < LIGHT_STEPS_MAX; ++j) {
+
+            // The loop should be: for (int j = 0; i < LIGHT_STEPS; ++j) {...} but WebGL1 cannot
+            // loop with non-constant condition, so it has to break early instead
+            if (j >= LIGHT_STEPS) {
+                break;
+            }
 
             // Calculate sample position along light ray.
             vec3 lightPosition = samplePosition + lightDirection * (lightPositionLength + lightStepLength * 0.5);
@@ -109,7 +152,7 @@ void computeScattering(
         mieAccumulation += sampleDensity.y * attenuation;
 
         // Increment distance on primary ray.
-        rayPositionLength += rayStepLength;
+        rayPositionLength += (rayStepLength += rayStepLengthIncrease);
     }
 
     // Compute the scattering amount.

package/Source/Shaders/AtmosphereCommon.js

@@ -9,8 +9,16 @@ uniform vec3 u_atmosphereRayleighCoefficient;\n\
 uniform vec3 u_atmosphereMieCoefficient;\n\
 \n\
 const float ATMOSPHERE_THICKNESS = 111e3; // The thickness of the atmosphere in meters.\n\
-const int PRIMARY_STEPS = 16; // Number of times the ray from the camera to the world position (primary ray) is sampled.\n\
-const int LIGHT_STEPS = 4; // Number of times the light is sampled from the light source's intersection with the atmosphere to a sample position on the primary ray.\n\
+const int PRIMARY_STEPS_MAX = 16; // Maximum number of times the ray from the camera to the world position (primary ray) is sampled.\n\
+const int LIGHT_STEPS_MAX = 4; // Maximum number of times the light is sampled from the light source's intersection with the atmosphere to a sample position on the primary ray.\n\
+\n\
+/**\n\
+ * Rational approximation to tanh(x)\n\
+*/\n\
+float approximateTanh(float x) {\n\
+    float x2 = x * x;\n\
+    return max(-1.0, min(+1.0, x * (27.0 + x2) / (27.0 + 9.0 * x2)));\n\
+}\n\
 \n\
 /**\n\
  * This function computes the colors contributed by Rayliegh and Mie scattering on a given ray, as well as\n\
@@ -51,14 +59,36 @@ void computeScattering(\n\
         return;\n\
     }\n\
 \n\
+    // To deal with smaller values of PRIMARY_STEPS (e.g. 4)\n\
+    // we implement a split strategy: sky or horizon.\n\
+    // For performance reasons, instead of a if/else branch\n\
+    // a soft choice is implemented through a weight 0.0 <= w_stop_gt_lprl <= 1.0\n\
+    float x = 1e-7 * primaryRayAtmosphereIntersect.stop / length(primaryRayLength);\n\
+    // Value close to 0.0: close to the horizon\n\
+    // Value close to 1.0: above in the sky\n\
+    float w_stop_gt_lprl = 0.5 * (1.0 + approximateTanh(x));\n\
+    \n\
     // The ray should start from the first intersection with the outer atmopshere, or from the camera position, if it is inside the atmosphere.\n\
+    float start_0 = primaryRayAtmosphereIntersect.start;\n\
     primaryRayAtmosphereIntersect.start = max(primaryRayAtmosphereIntersect.start, 0.0);\n\
     // The ray should end at the exit from the atmosphere or at the distance to the vertex, whichever is smaller.\n\
     primaryRayAtmosphereIntersect.stop = min(primaryRayAtmosphereIntersect.stop, length(primaryRayLength));\n\
+\n\
+    // For the number of ray steps, distinguish inside or outside atmosphere (outer space)\n\
+    // (1) from outer space we have to use more ray steps to get a realistic rendering\n\
+    // (2) within atmosphere we need fewer steps for faster rendering\n\
+    float x_o_a = start_0 - ATMOSPHERE_THICKNESS; // ATMOSPHERE_THICKNESS used as an ad-hoc constant, no precise meaning here, only the order of magnitude matters\n\
+    float w_inside_atmosphere = 1.0 - 0.5 * (1.0 + approximateTanh(x_o_a));\n\
+    int PRIMARY_STEPS = PRIMARY_STEPS_MAX - int(w_inside_atmosphere * 12.0); // Number of times the ray from the camera to the world position (primary ray) is sampled.\n\
+    int LIGHT_STEPS = LIGHT_STEPS_MAX - int(w_inside_atmosphere * 2.0); // Number of times the light is sampled from the light source's intersection with the atmosphere to a sample position on the primary ray.\n\
 \n\
     // Setup for sampling positions along the ray - starting from the intersection with the outer ring of the atmosphere.\n\
-    float rayStepLength = (primaryRayAtmosphereIntersect.stop - primaryRayAtmosphereIntersect.start) / float(PRIMARY_STEPS);\n\
     float rayPositionLength = primaryRayAtmosphereIntersect.start;\n\
+    // (1) Outside the atmosphere: constant rayStepLength\n\
+    // (2) Inside atmosphere: variable rayStepLength to compensate the rough rendering of the smaller number of ray steps\n\
+    float totalRayLength = primaryRayAtmosphereIntersect.stop - rayPositionLength;\n\
+    float rayStepLengthIncrease = w_inside_atmosphere * ((1.0 - w_stop_gt_lprl) * totalRayLength / (float(PRIMARY_STEPS * (PRIMARY_STEPS + 1)) / 2.0));\n\
+    float rayStepLength = max(1.0 - w_inside_atmosphere, w_stop_gt_lprl) * totalRayLength / max(7.0 * w_inside_atmosphere, float(PRIMARY_STEPS));\n\
 \n\
     vec3 rayleighAccumulation = vec3(0.0);\n\
     vec3 mieAccumulation = vec3(0.0);\n\
@@ -66,10 +96,17 @@ void computeScattering(\n\
     vec2 heightScale = vec2(u_atmosphereRayleighScaleHeight, u_atmosphereMieScaleHeight);\n\
 \n\
     // Sample positions on the primary ray.\n\
-    for (int i = 0; i < PRIMARY_STEPS; i++) {\n\
+    for (int i = 0; i < PRIMARY_STEPS_MAX; ++i) {\n\
+\n\
+        // The loop should be: for (int i = 0; i < PRIMARY_STEPS; ++i) {...} but WebGL1 cannot\n\
+        // loop with non-constant condition, so it has to break early instead\n\
+        if (i >= PRIMARY_STEPS) {\n\
+            break;\n\
+        }\n\
+\n\
         // Calculate sample position along viewpoint ray.\n\
         vec3 samplePosition = primaryRay.origin + primaryRay.direction * (rayPositionLength + rayStepLength);\n\
-        \n\
+\n\
         // Calculate height of sample position above ellipsoid.\n\
         float sampleHeight = length(samplePosition) - atmosphereInnerRadius;\n\
 \n\
@@ -80,14 +117,20 @@ void computeScattering(\n\
         // Generate ray from the sample position segment to the light source, up to the outer ring of the atmosphere.\n\
         czm_ray lightRay = czm_ray(samplePosition, lightDirection);\n\
         czm_raySegment lightRayAtmosphereIntersect = czm_raySphereIntersectionInterval(lightRay, origin, atmosphereOuterRadius);\n\
-        \n\
+\n\
         float lightStepLength = lightRayAtmosphereIntersect.stop / float(LIGHT_STEPS);\n\
         float lightPositionLength = 0.0;\n\
 \n\
         vec2 lightOpticalDepth = vec2(0.0);\n\
 \n\
         // Sample positions along the light ray, to accumulate incidence of light on the latest sample segment.\n\
-        for (int j = 0; j < LIGHT_STEPS; j++) {\n\
+        for (int j = 0; j < LIGHT_STEPS_MAX; ++j) {\n\
+\n\
+            // The loop should be: for (int j = 0; i < LIGHT_STEPS; ++j) {...} but WebGL1 cannot\n\
+            // loop with non-constant condition, so it has to break early instead\n\
+            if (j >= LIGHT_STEPS) {\n\
+                break;\n\
+            }\n\
 \n\
             // Calculate sample position along light ray.\n\
             vec3 lightPosition = samplePosition + lightDirection * (lightPositionLength + lightStepLength * 0.5);\n\
@@ -110,7 +153,7 @@ void computeScattering(\n\
         mieAccumulation += sampleDensity.y * attenuation;\n\
 \n\
         // Increment distance on primary ray.\n\
-        rayPositionLength += rayStepLength;\n\
+        rayPositionLength += (rayStepLength += rayStepLengthIncrease);\n\
     }\n\
 \n\
     // Compute the scattering amount.\n\

package/Source/Shaders/PostProcessStages/AmbientOcclusionGenerate.glsl

@@ -58,7 +58,7 @@ void main(void)
     float gapAngle = 90.0 * czm_radiansPerDegree;
 
     // RandomNoise
-    float randomVal = texture(randomTexture, v_textureCoordinates).x;
+    float randomVal = texture(randomTexture, v_textureCoordinates / pixelSize / 255.0).x;
 
     //Loop for each direction
     for (int i = 0; i < 4; i++)

package/Source/Shaders/PostProcessStages/AmbientOcclusionGenerate.js

@@ -59,7 +59,7 @@ void main(void)\n\
     float gapAngle = 90.0 * czm_radiansPerDegree;\n\
 \n\
     // RandomNoise\n\
-    float randomVal = texture(randomTexture, v_textureCoordinates).x;\n\
+    float randomVal = texture(randomTexture, v_textureCoordinates / pixelSize / 255.0).x;\n\
 \n\
     //Loop for each direction\n\
     for (int i = 0; i < 4; i++)\n\

package/Source/Shaders/PostProcessStages/AmbientOcclusionModulate.glsl

@@ -5,7 +5,7 @@ in vec2 v_textureCoordinates;
 
 void main(void)
 {
-    vec3 color = texture(colorTexture, v_textureCoordinates).rgb;
-    vec3 ao = texture(ambientOcclusionTexture, v_textureCoordinates).rgb;
-    out_FragColor.rgb = ambientOcclusionOnly ? ao : ao * color;
+    vec4 color = texture(colorTexture, v_textureCoordinates);
+    vec4 ao = texture(ambientOcclusionTexture, v_textureCoordinates);
+    out_FragColor = ambientOcclusionOnly ? ao : ao * color;
 }

package/Source/Shaders/PostProcessStages/AmbientOcclusionModulate.js

@@ -6,8 +6,8 @@ in vec2 v_textureCoordinates;\n\
 \n\
 void main(void)\n\
 {\n\
-    vec3 color = texture(colorTexture, v_textureCoordinates).rgb;\n\
-    vec3 ao = texture(ambientOcclusionTexture, v_textureCoordinates).rgb;\n\
-    out_FragColor.rgb = ambientOcclusionOnly ? ao : ao * color;\n\
+    vec4 color = texture(colorTexture, v_textureCoordinates);\n\
+    vec4 ao = texture(ambientOcclusionTexture, v_textureCoordinates);\n\
+    out_FragColor = ambientOcclusionOnly ? ao : ao * color;\n\
 }\n\
 ";

package/Source/Widget/CesiumWidget.js

@@ -520,6 +520,18 @@ Object.defineProperties(CesiumWidget.prototype, {
     },
   },
 
+  /**
+   * Manages the list of credits to display on screen and in the lightbox.
+   * @memberof CesiumWidget.prototype
+   *
+   * @type {CreditDisplay}
+   */
+  creditDisplay: {
+    get: function () {
+      return this._scene.frameState.creditDisplay;
+    },
+  },
+
   /**
    * Gets the camera.
    * @memberof CesiumWidget.prototype