Chapter 13. Temporal Circular Buffers
Prev		Next

Chapter 13. Temporal Circular Buffers

A static circular buffer cbuffer represents a 2D point and a radius greater than or equal to 0 around the point. The radius represent the “impact” of the point on its surroundings. This impact could be interpreted as noise, pollution, or similar aspects depending on application requirements.

The cbuffer type serves as base type for defining the temporal circular buffer type tcbuffer. The tcbuffer type has similar functionality as the temporal point type tgeompoint with the exception that it only considers two dimensions. Thus, most functions and operators described before for the tgeompoint type are also applicable for the tcbuffer type. In addition, there are specific functions defined for the tcbuffer type.

Static Circular Buffers

A cbuffer value is a couple of the form (point,radius) where point is a geometric point and radius is a float value greater than or equal to zero representing a radius around the point expressed using the units of the SRID of the point. Examples of input of circular buffer values are as follows:

SELECT cbuffer 'Cbuffer(Point(1 1), 0.3)';
SELECT cbuffer 'Cbuffer(Point(1 1), 10.0)';

Values of the circular buffer type must satisfy several constraints so that they are well defined. Examples of incorrect circular buffer type values are as follows.

-- incorrect point value
SELECT cbuffer 'Cbuffer(Linestring(1 1,2 2), 1.0)';
-- incorrect 3D point
SELECT cbuffer 'Cbuffer(Point Z(1 1 1), 1.0)';
-- incorrect radius value
SELECT cbuffer 'Cbuffer(Point(1 1), -2.0)';

We give next the functions and operators for the circular buffer type.

Constructors

Constructor for circular buffers

cbuffer(geompoint,float) → cbuffer

SELECT asText(cbuffer(ST_Point(1,1), 0.3));
-- Cbuffer(POINT(1 1),0.3)

Conversions

Values of the cbuffer type can be converted to the geometry point type using an explicit CAST or using the :: notation as shown below. Similarly, a geometry that define a circle can be converted to a cbuffer values. For this, the geometry must be a curve polygon with three points. If this is not the case, an error is returned.

Convert between a circular buffer and a geometry point

cbuffer::geompoint

geompoint::cbuffer

SELECT ST_AsText(cbuffer(ST_Point(1,1), 1)::geometry);
-- CURVEPOLYGON(CIRCULARSTRING(0 0,2 2,0 0))
SELECT asText(geometry 'SRID=5676;CURVEPOLYGON(CIRCULARSTRING(0 0,2 2,0 0))'::cbuffer);
-- Cbuffer(POINT(1 1),1)
SELECT asText(geometry 'SRID=5676;CIRCULARSTRING(0 0,2 2,0 0)'::cbuffer);
-- Only circle geometries accepted

Convert a circular buffer and, optionally, a timestamp or a period, to a spatiotemporal box

stbox(cbuffer) → stbox

stbox(cbuffer,{timestamptz,tstzspan}) → stbox

SELECT stbox(cbuffer 'SRID=5676;Cbuffer(Point(1 1),0.3)');
-- SRID=5676;STBOX X((0.7,0.7),(1.3,1.3))
SELECT stbox(cbuffer 'Cbuffer(Point(1 1),0.3)', timestamptz '2001-01-01');
-- STBOX XT(((0.7,0.7),(1.3,1.3)),[2001-01-01, 2001-01-01])
SELECT stbox(cbuffer 'Cbuffer(Point(1 1),0.3)', tstzspan '[2001-01-01,2001-01-02]');
-- STBOX XT(((0.7,0.7),(1.3,1.3)),[2001-01-01, 2001-01-02])

Accessors

Return the point

point(cbuffer) → geompoint

SELECT ST_AsText(point(cbuffer 'Cbuffer(Point(1 1), 0.3)'));
-- Point(1 1)

Return the radius

radius(cbuffer) → float

SELECT radius(cbuffer 'Cbuffer(Point(1 1), 0.3)');
-- 0.3

Transformations

Round the point and the radius of the circular buffer to the number of decimal places

round(cbuffer,integer=0) → cbuffer

SELECT asText(round(cbuffer(ST_Point(1.123456789,1.123456789), 0.123456789), 6));
-- Cbuffer(POINT(1.123457 1.123457),0.123457)

Spatial Operations

Return or set the spatial reference identifier

SRID(cbuffer) → integer

setSRID(cbuffer) → cbuffer

SELECT SRID(cbuffer 'Cbuffer(SRID=5676;Point(1 1), 0.3)');
-- 5676
SELECT asEWKT(setSRID(cbuffer 'Cbuffer(Point(0 0),1)', 4326));
-- SRID=4326;Cbuffer(POINT(0 0),1)

Transform to a spatial reference identifier
transform(cbuffer,integer) → cbuffer
transformPipeline(cbuffer,pipeline text,to_srid integer,is_forward bool=true) →
cbuffer
The transform function specifies the transformation with a target SRID. An error is raised when the input circular buffer has an unknown SRID (represented by 0).
The transformPipeline function specifies the transformation with a defined coordinate transformation pipeline represented with the following string format:
urn:ogc:def:coordinateOperation:AUTHORITY::CODE
The SRID of the input circular buffer is ignored, and the SRID of the output circular buffer will be set to zero unless a value is provided via the optional to_srid parameter. As stated by the last parameter, the pipeline is executed by default in a forward direction; by setting the parameter to false, the pipeline is executed in the inverse direction.
```
SELECT asEWKT(transform(cbuffer 'SRID=4326;Cbuffer(Point(4.35 50.85),1)', 3812));
-- SRID=3812;Cbuffer(POINT(648679.0180353033 671067.0556381135),1)
```
```
WITH test(cbuffer, pipeline) AS (
  SELECT cbuffer 'Cbuffer(SRID=4326;Point(4.3525 50.846667),1)',
    text 'urn:ogc:def:coordinateOperation:EPSG::16031' )
SELECT asEWKT(transformPipeline(transformPipeline(cbuffer, pipeline, 4326), pipeline,
  4326, false), 6)
FROM test;
-- SRID=4326;Cbuffer(POINT(4.3525 50.846667),1)
```

Comparisons

The comparison operators (=, <, and so on) are available for circular buffers. They compare first the points and then the radius of the arguments. Excepted the equality and inequality, the other comparison operators are not useful in the real world but allow B-tree indexes to be constructed on circular buffers.

Traditional comparisons

cbuffer {=, <>, <, >, <=, >=} cbuffer

SELECT cbuffer 'Cbuffer(Point(3 3), 0.5)' = cbuffer 'Cbuffer(Point(3 3), 0.5)';
-- true
SELECT cbuffer 'Cbuffer(Point(3 3), 0.5)' <> cbuffer 'Cbuffer(Point(3 3), 0.6)';
-- true
SELECT cbuffer 'Cbuffer(Point(3 3), 0.5)' < cbuffer 'Cbuffer(Point(3 3), 0.6)';
-- true
SELECT cbuffer 'Cbuffer(Point(3 3), 0.6)' > cbuffer 'Cbuffer(Point(2 2), 0.6)';
-- true
SELECT cbuffer 'Cbuffer(Point(1 1), 0.5)' <= cbuffer 'Cbuffer(Point(2 2), 0.5)';
-- true
SELECT cbuffer 'Cbuffer(Point(1 1), 0.6)' >= cbuffer 'Cbuffer(Point(1 1), 0.5)';
-- true