From 6e89bbff5ddffc38e942ba257c4ce8d42252e280 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Thu, 14 Sep 2023 23:51:26 +0200 Subject: [PATCH 1/3] manual: r.sunmask and i.topo.corr improvements - r.sunmask: explain sun angles - i.topo.corr: improve angle descriptions --- imagery/i.topo.corr/i.topo.corr.html | 24 +++++---- raster/r.sunmask/r.sunmask.html | 74 ++++++++++++++++++---------- 2 files changed, 63 insertions(+), 35 deletions(-) diff --git a/imagery/i.topo.corr/i.topo.corr.html b/imagery/i.topo.corr/i.topo.corr.html index f141f6f053f..994be7c4756 100644 --- a/imagery/i.topo.corr/i.topo.corr.html +++ b/imagery/i.topo.corr/i.topo.corr.html @@ -3,12 +3,11 @@

DESCRIPTION

i.topo.corr is used to topographically correct reflectance from imagery files, e.g. obtained with i.landsat.toar, using a sun illumination terrain model. This illumination model represents the -cosine of the incident angle i, i.e. the angle between the normal to the -ground and the sun rays. +cosine of the incident angle i, i.e. the angle between the normal +to the ground and the sun rays.

-Note: If needed, the sun position can be calculated for a given date with -r.sunmask. - +Note: If needed, the sun position can be calculated for a given date and +time with r.sunmask.

Figure showing terrain and solar angles
@@ -18,15 +17,20 @@

DESCRIPTION

Using the -i flag and given an elevation basemap (metric), i.topo.corr creates a simple illumination model using the formula: +

+ where, -i is the incident angle to be calculated, -s is the terrain slope angle, -z is the solar zenith angle, -a the solar azimuth angle, -o the terrain aspect angle. + +

For each band file, the corrected reflectance (ref_c) is calculate from diff --git a/raster/r.sunmask/r.sunmask.html b/raster/r.sunmask/r.sunmask.html index 8d8f8e9a2fd..148015e877e 100644 --- a/raster/r.sunmask/r.sunmask.html +++ b/raster/r.sunmask/r.sunmask.html @@ -1,34 +1,58 @@

DESCRIPTION

r.sunmask creates an output map layer based on an input elevation -raster map layer and the sun position. The output map layer contains the -cast shadow areas arising from sun shine and elevations. The user can define -the sun position either directly or the module calculates it from given -location and date/time parameters using the -NREL sun position algorithm. So either -"A:"-parameters to specify the exact known sun position or "B:-parameters" -to specify date/time for sun position calculation by r.sunmask itself -have to be used. - -

The module performs sunset/sunrise checks and refraction correction for sun -position calculation. Local coordinate systems are internally transformed to -latitude/longitude for the SOLPOS algorithm. The elevation is not considered -in the sunset/sunrise calculations. +raster map layer and the position of the sun. The output map layer contains the +cast shadow areas resulting from sunlight and elevation. The user can either +specify the sun position directly or the module calculates it from given +location and date/time parameters using the SOLPOS (Solar and Moon Position Algorithm) +developed by the +National Renewable Energy Laboratory +(NREL). SOLPOS operates in two modes, either + +

+must be used. + +

+The module performs sunset/sunrise checks and refraction correction for +sun position calculation. Local coordinate systems are internally transformed +to latitude/longitude for the SOLPOS algorithm. Elevation is not taken into +account for sunset/sunrise calculations. + +

+The solar zenith angle ("sun angle above horizont") is defined as the angle +between the horizont and the vertical (directly overhead or zenith). Its +values can range from 90°, when the sun is directly overhead, to 0°, +when the sun is on the horizon. Values lower than 0° indicate that the +sun is below the horizon. + +

+The solar azimuth angle ("sun azimuth") defines the direction of the sun. +It is the angle between north (in the northern hemisphere) or south (in +the southern hemisphere) and the projection of the sun's rays onto the +horizontal plane. This angle is measured in a clockwise direction and can +vary between 0° and 360°. Specifically, an azimuth of 0° means +the sun is in the north, 90° in the east, 180° in the south and +270° in the west.

NOTES

-r.sunmask and daylight savings: Rather than converting the -local time to GMT, the SOLPOS algorithm uses what is called Local -Standard Time, which is generally politically defined as an offset -from GMT. So the key is the offset from GMT, which the solpos Time +r.sunmask and daylight saving time: Instead of converting the +local time to GMT, the SOLPOS algorithm uses what is known as Local +Standard Time, which is generally defined as an offset from GMT. +So the key is the offset from GMT, which the solpos Time Zone parameter. If the user specifies clock time (different for -winter and summer), s/he would have to change the Time Zone -parameter seasonally in r.sunmask (timezone parameter). See also -Daylight saving time by region and country. +winter and summer), s/he would have to change the Time Zone parameter in +r.sunmask (timezone parameter) seasonally. See also +Daylight saving time by region and country. +

Note: In latitude/longitude locations the position coordinates pair -(east/west) has to be specified in decimal degree (not D:M:S). If +(east/west) has to be specified in decimal degree (not DD:MM:SS). If not specified, the map center's coordinates will be used. Also g.region -l displays the map center's coordinates in latitude/longitude (or g.region -c in the actual coordinate @@ -98,7 +122,7 @@

EXAMPLE

Acknowledgements

Acknowledgements: National Renewable Energy Laboratory for their -SOLPOS 2.0 sun position +SOLPOS 2.0 sun position algorithm.

SEE ALSO

@@ -112,6 +136,6 @@

SEE ALSO

AUTHORS

-Janne Soimasuo, Finland 1994
-update to FP by Huidae Cho 2001
-SOLPOS algorithm feature added by Markus Neteler 2001 +Janne Soimasuo, Finland, 1994
+update to FP by Huidae Cho, 2001
+SOLPOS algorithm feature added by Markus Neteler, 2001 From 1658d04aa03564a567408dd1b0e3cb83ea6deab4 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Tue, 26 Sep 2023 21:37:06 +0200 Subject: [PATCH 2/3] fix grammar/typos Co-authored-by: Markus Metz <33666869+metzm@users.noreply.github.com> --- raster/r.sunmask/r.sunmask.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/raster/r.sunmask/r.sunmask.html b/raster/r.sunmask/r.sunmask.html index 148015e877e..4b2ba78a032 100644 --- a/raster/r.sunmask/r.sunmask.html +++ b/raster/r.sunmask/r.sunmask.html @@ -23,8 +23,8 @@

DESCRIPTION

account for sunset/sunrise calculations.

-The solar zenith angle ("sun angle above horizont") is defined as the angle -between the horizont and the vertical (directly overhead or zenith). Its +The solar zenith angle ("sun angle above horizon") is defined as the angle +between the horizon and the vertical (directly overhead or zenith). Its values can range from 90°, when the sun is directly overhead, to 0°, when the sun is on the horizon. Values lower than 0° indicate that the sun is below the horizon. @@ -43,7 +43,7 @@

NOTES

r.sunmask and daylight saving time: Instead of converting the local time to GMT, the SOLPOS algorithm uses what is known as Local Standard Time, which is generally defined as an offset from GMT. -So the key is the offset from GMT, which the solpos Time +So the key is the offset from GMT, which is the solpos Time Zone parameter. If the user specifies clock time (different for winter and summer), s/he would have to change the Time Zone parameter in r.sunmask (timezone parameter) seasonally. See also From 9b97ae93820421e08384b5e527a4ff851bf17d32 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Tue, 3 Oct 2023 19:06:58 +0200 Subject: [PATCH 3/3] correct hemisphere and azimuth angle definition --- raster/r.sunmask/r.sunmask.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/raster/r.sunmask/r.sunmask.html b/raster/r.sunmask/r.sunmask.html index 4b2ba78a032..ec3d4e715b6 100644 --- a/raster/r.sunmask/r.sunmask.html +++ b/raster/r.sunmask/r.sunmask.html @@ -31,8 +31,7 @@

DESCRIPTION

The solar azimuth angle ("sun azimuth") defines the direction of the sun. -It is the angle between north (in the northern hemisphere) or south (in -the southern hemisphere) and the projection of the sun's rays onto the +It is the angle between north and the projection of the sun's rays onto the horizontal plane. This angle is measured in a clockwise direction and can vary between 0° and 360°. Specifically, an azimuth of 0° means the sun is in the north, 90° in the east, 180° in the south and