The distance functions compute the distance between the body of a temporal rigid geometry and a geometry, a temporal point, or the body of another temporal rigid geometry. The body at an instant is the reference geometry moved and turned by the pose at that instant.
The values of a temporal distance are exact. When a body turns, the distance between two instants does not change linearly, so the temporal distance also has an instant at each minimum and maximum of the distance. Thus the nearest approach distance and the nearest approach instant are exact.
The distance functions need a reference geometry that is a convex polygon without holes. A polygon of the other argument must also be convex and without holes. Other values give an error.
SELECT tDistance(trgeometry 'Polygon((0 0,4 0,4 4,2 1,0 4,0 0)); Pose(Point(0 0),0)@2001-01-01', geometry 'Point(7 3)'); -- ERROR: The distance of a temporal rigid geometry needs a reference geometry that is -- a convex polygon without holes
Return the temporal distance
{geometry,tgeompoint,trgeometry} <-> {geometry,tgeompoint,trgeometry} → tfloat
tDistance({geometry,tgeompoint,trgeometry},{geometry,tgeompoint,trgeometry}) → tfloat
In the first example, a square moves past a point. Its side stays at distance 2 from the point from 10:00 to 14:00. In the second example, the square turns a quarter turn next to the point. A corner of the square comes nearest to the point at 12:00, and the result has an instant there.
SELECT trgeometry 'Polygon((-1 -1,1 -1,1 1,-1 1,-1 -1)); [Pose(Point(-6 0),0)@2001-01-01, Pose(Point(6 0),0)@2001-01-02]' <-> geometry 'Point(0 3)'; -- [5.385164807134504@2001-01-01, 2@2001-01-01 10:00:00, 2@2001-01-01 14:00:00, -- 5.385164807134504@2001-01-02] SELECT round(trgeometry 'Polygon((-1 -1,1 -1,1 1,-1 1,-1 -1)); [Pose(Point(0 0),0)@2001-01-01, Pose(Point(0 0),1.5707963267948966)@2001-01-02]' <-> geometry 'Point(3 0)', 6); -- [2@2001-01-01, 1.828427@2001-01-01 05:11:32.371809, 1.585786@2001-01-01 12:00:00, -- 1.828427@2001-01-01 18:48:27.628191, 2@2001-01-02] SELECT trgeometry 'Polygon((-1 -1,1 -1,1 1,-1 1,-1 -1)); [Pose(Point(0 0),0)@2001-01-01, Pose(Point(0 0),0)@2001-01-02]' <-> tgeompoint '[Point(3 -4)@2001-01-01, Point(3 4)@2001-01-02]'; -- [3.605551275463989@2001-01-01, 2@2001-01-01 09:00:00, 2@2001-01-01 15:00:00, -- 3.605551275463989@2001-01-02] SELECT trgeometry 'Polygon((0 0,1 0,1 1,0 1,0 0)); [Pose(Point(0 0),0)@2001-01-01, Pose(Point(0 0),0)@2001-01-02]' <-> trgeometry 'Polygon((0 0,1 0,1 1,0 1,0 0)); [Pose(Point(2 0),0)@2001-01-01, Pose(Point(10 0),0)@2001-01-02]'; -- [1@2001-01-01, 9@2001-01-02]
Return the nearest approach distance
{geometry,stbox,tgeompoint,trgeometry} |=| {geometry,stbox,tgeompoint,trgeometry} → float
nearestApproachDistance({geometry,stbox,tgeompoint,trgeometry},
{geometry,stbox,tgeompoint,trgeometry}) → float
SELECT trgeometry 'Polygon((0 0,1 0,1 1,0 1,0 0)); [Pose(Point(0 0),0)@2001-01-01, Pose(Point(10 0),0)@2001-01-02]' |=| trgeometry 'Polygon((0 0,1 0,1 1,0 1,0 0)); [Pose(Point(50 0),0)@2001-01-01, Pose(Point(50 0),0)@2001-01-02]'; -- 39 SELECT round(nearestApproachDistance(trgeometry 'Polygon((-1 -1,1 -1,1 1,-1 1,-1 -1)); [Pose(Point(0 0),0)@2001-01-01, Pose(Point(0 0),1.5707963267948966)@2001-01-02]', geometry 'Point(3 0)')::numeric, 6); -- 1.585786
The |=| operator can be used for nearest-neighbour searches with GiST or SP-GiST indexes (see the section called “Indexing”).
Return the instant of the first argument at which the two arguments are nearest
nearestApproachInstant({geometry,tgeompoint,trgeometry},
{geometry,tgeompoint,trgeometry}) → trgeometry
If the distance stays at its minimum during an interval, the result is the first instant of the interval. In the second example, the square is at distance 4 from the point from 09:36 to 12:00.
SELECT asText(nearestApproachInstant(trgeometry 'Polygon((-1 -1,1 -1,1 1,-1 1,-1 -1)); [Pose(Point(0 0),0)@2001-01-01, Pose(Point(0 0),1.5707963267948966)@2001-01-02]', geometry 'Point(3 0)'), 6); -- POLYGON((-1 -1,1 -1,1 1,-1 1,-1 -1));Pose(POINT(0 0),0.785398)@2001-01-01 12:00:00 SELECT asText(nearestApproachInstant(trgeometry 'Polygon((0 0,1 0,1 1,0 1,0 0)); [Pose(Point(0 0),0)@2001-01-01, Pose(Point(10 0),0)@2001-01-02]', geometry 'Point(5 5)')); -- POLYGON((0 0,1 0,1 1,0 1,0 0));Pose(POINT(4 0),0)@2001-01-01 09:36:00
Return the line between the nearest points of the two arguments at their nearest approach instant
shortestLine({geometry,tgeompoint,trgeometry},{geometry,tgeompoint,trgeometry})
→ geometry
SELECT ST_AsText(shortestLine(trgeometry 'Polygon((0 0,1 0,1 1,0 1,0 0)); Pose(Point(0 0),0)@2001-01-01', geometry 'Point(10 0)')); -- LINESTRING(1 0,10 0)