expose new scalar to change the visual density of fog

[jjspace]

Description

• Add a new property to adjust the visual density of fog relative to the "actual" density which also affects culling
• change the default visual scalar from 0.15 to 0.4 which should make the densest fog possible right around where tiles are culled

Old default 0.15	New default 0.4

Density function details

These graphs show the density function values. The y value between 0 and 1 is used to determine the percentage for mixing the original color and the fog color. `mix(originalColor, fogColor, percent)` ie. closer to 1 means more fog color Any tile with a value greater than 1 is culled and thus not rendered Any tile or model with a value less than `0.001` does not get any fog color at all to aid in performance, the fog would be negligible. The red line is the "true" fog function that is calculated without any scalar. This is the one used for culling The purple line is the fog function with the modifier included. The purple area is where fog is actually being displayed This is the before value with a modifier of `0.15`  This is the same functions with a modifier of `0.4`. As you can see the fog (purple) much closer matches reaching 1 around the same time the red fog function does. This means it's visually most dense at around the same distance tiles are culled.  The density is cranked up way higher than normal to make seeing the curves clearer [Desmos link](https://www.desmos.com/calculator/ujgnokdrhq) if you want to play with the values yourself (the `v` value is there to exaggerate the graphs visually so you can still see the curves even if you stretch the density out really far)

Issue number and link

Part of https://github.com/CesiumGS/cesium/issues/12126

Testing plan

• Open the updated Fog sandcastle and play around with the visual density scalar value
  • Modify the actual density with different scalar values to see how they affect each other.

Author checklist

• [x] I have submitted a Contributor License Agreement
• [x] I have added my name to CONTRIBUTORS.md
• [x] I have updated CHANGES.md with a short summary of my change
• [ ] I have added or updated unit tests to ensure consistent code coverage
• [x] I have updated the inline documentation, and included code examples where relevant
• [ ] I have performed a self-review of my code

[github-actions[bot]]

Thank you for the pull request, @jjspace!

:white_check_mark: We can confirm we have a CLA on file for you.

[ggetz]

This is the same functions with a modifier of 0.4. As you can see the fog (purple) much closer matches reaching 1 around the same time the red fog function does. This means it's visually most dense at around the same distance tiles are culled.

Good explanation! So for the default, we wouldn't want to go any less that 0.4 from the sound of it.

I was playing around with GE as a point of comparison, and their fog appears much denser, even than visual density equivalent of 1.0 in our system (which I think is the maximum, based on the function visualizations). What are your thoughts?

[jjspace]

I was playing around with GE as a point of comparison, and their fog appears much denser, even than visual density equivalent of 1.0 in our system (which I think is the maximum, based on the function visualizations). What are your thoughts?

I actually think the density of our fog is about the same. But ours is much darker. Maybe this has to do with some of the atmosphere values?

This is approximately the same location in CesiumJS (with 0.4) and Google Earth. (I just noticed GE seems to put a touch of a fish eye effect on the fov?)

This is that same view with the visualDensityScalar set to 1.0. I think this looks much more dense than GE's so i'm surprised to hear you say the opposite. does this match with what you saw?

Edit (immediate follow up...): I did just notice our fog seems inconsistently applied as we zoom in and out and very close to the ground it's not applied at all which I think might be the cause of your previous comment about it not being as dense as GE. They seem to apply fog consistently across all zoom levels. Not sure the cause for this.

https://github.com/user-attachments/assets/f2eb1b78-5f97-4df2-84f9-f7dd2fa2f41a

https://github.com/user-attachments/assets/4979d764-1a1f-40fa-86c2-d5a1ccfa1b60

[ggetz]

I did just notice our fog seems inconsistently applied as we zoom in and out and very close to the ground it's not applied at all which I think might be the cause of your previous comment about it not being as dense as GE. They seem to apply fog consistently across all zoom levels. Not sure the cause for this.

Yes, I was looking at a horizon few similar to this one. This is what prompted my question. I agree that from your more "aerial" screenshots, the density does read correctly at a value of 0.4.

My guess for what is causing this may be the atmosphere scattering code returning transparent colors for fog when close to the ground. Perhaps try stubbing out the atmosphere color function with one that returns a solid color for the sake of debugging. Once we identify the cause, we can figure out an implementation plan, and if it's scope.

If that's not the case, my shot in the dark is that this may be related to https://github.com/CesiumGS/cesium/issues/11922. The horizon angle is what's jumping out to me as similar.

But ours is much darker. Maybe this has to do with some of the atmosphere values?

I agree. I assume that will be out of scope for this PR. I believe the reasons for this are documented in https://github.com/CesiumGS/cesium/issues/11717#issuecomment-1889894826.

[jjspace]

@ggetz I fixed up the couple docs issues and moved the fog sandcastle as discussed offline.

That said I'm still confused what's causing the fog to be basically non-existant close to the ground and have such a massive spike in density at a certain height. I tried swapping the fog color out for a static magenta 1, 0, 1 instead of the atmosphere color and still observe the same issues. I'm thinking it might have something to do with the depth/distance calculations? I made a slightly modified sandcastle to easily reproduce the zoom.

https://github.com/user-attachments/assets/8a65c731-5a20-4773-89f7-04e54770f58f

[ggetz]

That said I'm still confused what's causing the fog to be basically non-existant close to the ground and have such a massive spike in density at a certain height. I tried swapping the fog color out for a static magenta 1, 0, 1 instead of the atmosphere color and still observe the same issues. I'm thinking it might have something to do with the depth/distance calculations?

Hmm, I see it as well. I wonder if we need to scale based on the camera height. For instance, here's an exponential decay function based on camera height which seems to be producing decent results:

const float maxHeight = 10000.0;
const float minHeight = 500.0;
float height = (czm_eyeHeight - minHeight) / (maxHeight - minHeight);
float heightModifier = 1.0 + exp(-decay * height);

const float modifier = 0.4;
finalColor = vec4(czm_fog(v_distance * heightModifier, finalColor.rgb, fogColor.rgb, modifier), finalColor.a);

[jjspace]

@ggetz thank you for the pair programming on this. recapping a little here.

• Ever since fog was initially implemented it's used an internal table of heights and densities at those heights that seems to be somewhat arbitrary. These were not a fully smooth curve and were the cause of the weird "spikes" in density and practically no fog near the ground that we were observing.
  • Desmos graph with those values showing inconsistent densities across heights and some test curves to fit (messy but wanted to record somewhere)
• Those tables have been replaced with a smooth power function that somewhat closely matches the previous values.
• The "magic numbers" in that new function have been exposed as a set of new properties on the Fog class to allow customization. We should have good defaults so they don't normally have to be altered but the option is there.
• With this latest change I also updated the visualDensityScalar up to 1 from 0.4 which seems to have a nicer effect. We may even want to default to slightly higher.

I think the function and implementation is good now. The sandcastle has been updated with the new properties. Please play with them a little and see if you think there's a better set of default values, changing the numbers is easy. I'll fix up the tests tomorrow as long as we agree on this approach.

[ggetz]

@jjspace I did some quick network testing:

• On average, the current settings are using around 1.5MB network for horizon views at various heights
• To get the same network usage as in main, I used the following settings:

  viewer.scene.fog.density = 0.001;
  viewer.scene.fog.heightFalloff = 0.65;

• What do you think of splitting the difference? This is, on average, using 0.4MB more network, and I'm still seeing increased resolution at the mid-range and closer to the camera.

  viewer.scene.fog.density = 0.0006;
  viewer.scene.fog.heightFalloff = 0.59;

[jjspace]

@ggetz I think I'm fine with those values, especially if it helps with the network cost.

I was also thinking of switching the visualDensityScalar back down to 0.5 or 0.6 instead of 1 as I think 1 gets a bit too aggressivly dense at higher altitudes. Thoughts?

I'm still working through the tests, mostly value checking which these numbers but that should just be a simple value update.

[ggetz]

I was also thinking of switching the visualDensityScalar back down to 0.5 or 0.6 instead of 1 as I think 1 gets a bit too aggressively dense at higher altitudes. Thoughts?

I did some digging into why fog is so dark, and I think that the opacity of the ground atmosphere color is not being correctly handled. If we go with something similar to the fix I have there, I think 1 works, as the fog closer to the camera will actually be pretty thin and therefor the color more transparent. However, I doubt we could get that fix in before the next release.

If possible, I'd like to avoid breaking changes for this default. Maybe a weird idea, but what do you think of marking this value as experimental for the first release in case we want to adjust it after the fact?

[jjspace]

@ggetz I've added tests and marked the new scalar as experimental. I think that's fine for now but I also thought that if we want to update this in the future we could switch it back to 0.15 like it was before this PR to minimize impact until we get your other fix in?

[ggetz]

I think that's fine for now but I also thought that if we want to update this in the future we could switch it back to 0.15 like it was before this PR to minimize impact until we get your other fix in?

Sure, please change it to whatever the equivalent was for the previous behavior.

[jjspace]

@ggetz I believe this should now have all your comments addressed

[ggetz]

Looks good! Thanks @jjspace!