Converting Azimuth to Solar Azimuth in three.js Sunlight Examples

Resources
1

The Sunlight examples (WebGL and WebGPU) provide useful templates for people using three.js to create open world scenarios. However, for those of us who work in those kinds of scenarios, there is some potential confusion regarding the azimuth and the computation of the position of the sun. To us, when the term azimuth is used in connection with the sun, the term refers to “solar azimuth” - which is the absolute direction of the sun - 0 degrees is North, 90 is East, 180 is South, and 270 is West.

However the Sunlight examples do not use solar azimuth to compute the sun position. They are using the definition of azimuth which is typically used in defining spherical coordinates (i.e. the rotation angle in the xy-plane measured counter-clockwise from the positive x-axis). This is absolutely okay (especially since the azimuth is being used in a spherical coordinate function), but it can be confusing to open world programmers (like myself) who expect azimuth to equate to solar azimuth. .

To illustrate the difference, go to one of the Sunlight examples. The starting azimuth is 135. If this were solar azimuth, it would indicate that the sun is roughly South-East of the viewer. The direction of the shadows indicates that you are facing North. If the sun now rotates to the South (as is typical in the Northern Hemisphere), the sun should move clockwise around you so that when the azimuth is 180, the sun is should now be directly behind you (South). However, in the example, the sun rotates counter-clockwise so that when the azimuth is 180, the sun is directly to your right (East).

The Sunlight examples compute the sun position using the setFromSphericalCoords function to compute the position of the sun, e.g.:

sunLight.position.setFromSphericalCoords(1,THREE.MathUtils.degToRad(90-params.elevation),THREE.MathUtils.degToRad(params.azimuth));

If you would prefer to use solar azimuth rather than standard azimuth and still want to use that function to compute sun position, you will need to convert solar azimuth to standard azimuth. It turns out that this conversion is quite simple. You simply define azimuth as 270-azimuth, to wit:

sunLight.position.setFromSphericalCoords(1,THREE.MathUtils.degToRad(90-params.elevation),THREE.MathUtils.degToRad(270-params.azimuth));

One you make that change, the position of the sun will correlate to the solar azimuth.

NOTE: When I discussed making this kind of change to the Sunlight examples with the three.js developers, they were reluctant to do so. Their main concern was that using solar azimuth would (as discussed) introduce the concept of heading to the examples. They wanted to keep the examples “heading neutral”. This is totally understandable since the Sunlight examples could also be useful in creating programs which are not open world programs. But this also means that the Sunlight (and Sun) examples will likely continue to use the standard definition of azimuth.

3 Likes
2

Thanks for writing this up.. I hit it this issue when trying to do a simulation a few years ago, and sorta hacked around it, but never really understood why it was happening. Nice to see it confirmed.

1 Like
3

A clean way to avoid mixing the two conventions is to name the input explicitly (for example, solarAzimuth) and convert it once at the scene boundary, rather than passing a transformed angle through the rest of the app. A quick check at the four cardinal directions with elevation held fixed will catch sign or origin mistakes. If the world uses a north direction that differs from the scene axes, apply that heading offset explicitly too.

1 Like
4

Thanks. It took me awhile to figure out what was going on since I have always used something equivalent to “solar azimuth” in my real world programs.

I have edited the title and the discussion to remove any implication that the computation of the sun position in the Sunlight programs is wrong. It is simply a definitional issue. The creators of the Sunlight (and Sun) programs are using the mathematical definition of azimuth to compute sun position in a spherical coordinate system.

But open world programmers generally prefer to use the “outside world” definition of azimuth - i.e. the definition used by navigators, weather people, pilots, etc.

1 Like
5

Yes, more explicit definitions would help.

And, yes, there is a lot more that could be said about all of this. In fact, that would be a perfect topic for a longer discussion of how to make three.js work with open world programming.