Calculate shadow ratio for points using ST_ShadowRatio - PolarDB

Calculates the shadow ratio of one or more points over a time range or at a specific point in time. The result is stored in the m-coordinate of each input point.

Syntax

Method 1 — calculate shadow ratio over a time range using sunlight information:

geometry ST_ShadowRatio(scene sc, geometry points, cstring sunlight);

Method 2 — check whether a shadow covers points at a specific time:

geometry ST_ShadowRatio(scene sc, geometry points, geometry location, cstring time);

Usage notes

The location field in the sunlight JSON and the location parameter in Method 2 must use the EPSG 4326 coordinate system. Coordinates in scene objects are local coordinates; the longitude and latitude are required to calculate the sunlight direction.
time_interval cannot be 0.
Method 1 returns a continuous shadow ratio between 0 and 1. Method 2 returns a binary result: 1 if the shadow covers the point, 0 if it does not.
The shadow ratio result is stored in the m-coordinate (the fourth dimension) of each output point, in MULTIPOINT ZM format.

Parameters

Parameter	Type	Description
`sc`	scene	The scene object.
`points`	geometry	The points for which to calculate the shadow ratio.
`sunlight`	cstring (JSON)	Sunlight information as a JSON string. Used in Method 1.
`location`	geometry	The longitude and latitude of the scene. Used in Method 2.
`time`	cstring	The time at which to check shadow coverage. Used in Method 2.

sunlight JSON fields

Field	Description	Remarks
`location`	The longitude and latitude of the scene for shadow ratio analysis. For example: `"srid=4326; POINT(120 30)"`.	Must use the EPSG 4326 coordinate system. Coordinates in scene objects are local coordinates. Required to specify the longitude and latitude of the scene object to calculate the sunlight direction.
`start_time`	The start time of the shadow ratio analysis.	Must be a valid time string.
`end_time`	The end time of the shadow ratio analysis.	Must be a valid time string.
`time_interval`	The sampling interval for shadow ratio analysis. For example: `"01:00:00"`.	Cannot be `0`.

The following is an example sunlight value:

{
  "location": "srid=4326; POINT(120 30)",
  "start_time": "2021-07-12 08:00:00+0800",
  "end_time": "2021-07-12 18:00:00+0800",
  "time_interval": "01:00:00"
}

Examples

Method 1: Shadow ratio over a time range

The following query calculates the shadow ratio for three points from 08:00 to 18:00, sampled every hour.

SELECT ST_AsText(ST_ShadowRatio(the_scene,
    'MULTIPOINT(0 0 -2, 1 2 8, -70 -400 1330)'::geometry,
    '{"location": "srid=4326; POINT(120 30)",
      "start_time": "2021-07-12 08:00:00 +0800",
      "end_time": "2021-07-12 18:00:00 +0800",
      "time_interval": "01:00:00"}'
)) FROM t_scene;

Output:

MULTIPOINT ZM ((0 0 -2 0.636363636363636),(1 2 8 0),(-70 -400 1330 0))

Each output point is in (X Y Z M) format, where M is the shadow ratio:

Point (0 0 -2): shadow ratio 0.636 — in shadow for approximately 63.6% of the sampled time intervals.
Point (1 2 8): shadow ratio 0 — never in shadow during the analysis period.
Point (-70 -400 1330): shadow ratio 0 — never in shadow during the analysis period.

Method 2: Shadow coverage at a specific time

The following query checks whether a shadow covers four points at 12:00 on July 12, 2021.

SELECT ST_AsText(ST_ShadowRatio(the_scene,
    'MULTIPOINT(-2 0 0, 0 0 0, 2 0 0, 0 0 2)'::geometry,
    'srid=4326; POINT(120 30)'::geometry,
    '2021-07-12 12:00:00 +0800'
)) FROM t_scene;

Output:

MULTIPOINT ZM ((-2 0 0 0),(0 0 0 1),(2 0 0 0),(0 0 2 0))

Each output point is in (X Y Z M) format, where M is 1 (in shadow) or 0 (not in shadow):

Point (-2 0 0): 0 — not in shadow.
Point (0 0 0): 1 — in shadow at the specified time.
Point (2 0 0): 0 — not in shadow.
Point (0 0 2): 0 — not in shadow.