ST_ShadowRatio-PolarDB(PolarDB)-阿里云帮助中心

Calculates the shadow ratio for one or more points in a 3D scene and stores the result in the M coordinate of each output point. Method 1 returns a ratio from 0 to 1 over a time range; Method 2 returns a binary value (0 or 1) at a single point in time.

Syntax

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

Parameters

Parameter	Type	Description
`sc`	scene	The scene object.
`points`	geometry	One or more points for which to calculate the shadow ratio.
`sunlight`	cstring (JSON)	The sunlight configuration. See Sunlight JSON fields.
`location`	geometry	The longitude and latitude of the scene, used to determine the sun direction at the specified time. Must use the EPSG 4326 coordinate system.
`time`	cstring	The point in time at which to check shadow coverage.

Sunlight JSON fields

Used by Method 1. All fields are required.

Field	Type	Description
`location`	string	The longitude and latitude of the scene in EPSG 4326 format. Scene objects use local coordinates — this field maps the scene to a geographic position so the function can calculate the sun direction.
`start_time`	string	The start of the analysis period. Must be a valid timestamp with timezone.
`end_time`	string	The end of the analysis period. Must be a valid timestamp with timezone.
`time_interval`	string	The sampling interval. Cannot be `0`.

Example sunlight JSON:

{
  "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"
}

Description

Method 1 — Time-range sampling

Samples the sun position at each interval between start_time and end_time. For each input point, it counts how many sampled positions cast a shadow over that point, then divides by the total number of samples to produce a ratio from 0 to 1. A value of 0.636 means the point was in shadow during about 63.6% of the sampled time steps. The result is stored in the M coordinate of each output point.

Method 2 — Single point in time

Checks whether the shadow covers each input point at the specified time. Returns 1 if the point is in shadow, 0 if it is not. The result is stored in the M coordinate of each output point.

Examples

Method 1: Calculate shadow ratio over a time range

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))

The M coordinate of each point holds its shadow ratio. The first point (0 0 -2) has a ratio of approximately 0.636, meaning it was in shadow for about 7 of the 11 hourly samples. The other two points have a ratio of 0, meaning they were never in shadow.

Method 2: Check shadow coverage at a single point in time

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))

The M coordinate is 1 for the point at (0 0 0) — it is in shadow at noon — and 0 for all other points.

Usage notes

The location field in the sunlight JSON and the location parameter in Method 2 must use the EPSG 4326 coordinate system. Scene objects use local coordinates, so location is required to resolve the geographic position of the scene and compute the correct sun direction.
time_interval cannot be 0.
Output geometry type is MULTIPOINT ZM. The M coordinate holds the shadow ratio.
Method 1 shadow ratio range: 0 (never in shadow) to 1 (always in shadow).
Method 2 shadow ratio values: 1 (in shadow at the specified time) or 0 (not in shadow).