# Bounding Box Types

We present next the functions and operators for bounding box types. These functions and operators are polimorhic, that is, their argumentos can be of various types and their result type may depend on the type of the arguments. To express this in the signature of the operators, we use the following notation:

- `box` represents any bounding box type, that is, `tbox` or `stbox`.

## Input and Output

MobilityDB generalizes Open Geospatial Consortium's Well-Known Text (WKT) and Well-Known Binary (WKB) input and output format for all temporal types. We present next the functions for input and output box types.

A `tbox` is composed of a numeric and/or time dimensions. For each dimension, a span given, that is, either an `intspan` or a `floatspan` for the value dimension and a `tstzspan` for the time dimension. Examples of input of `tbox` values are as follows:

    -- Both value and time dimensions
    SELECT tbox 'TBOXINT XT([1,3),[2001-01-01,2001-01-02])';
    SELECT tbox 'TBOXFLOAT XT([1.5,2.5],[2001-01-01,2001-01-02])';
    -- Only value dimension
    SELECT tbox 'TBOXINT X([1,3))';
    SELECT tbox 'TBOXFLOAT X((1.5,2.5))';
    -- Only time dimension
    SELECT tbox 'TBOX T((2001-01-01,2001-01-02))';

An `stbox` is composed of a spatial and/or time dimensions, where the coordinates of the spatial dimension may be 2D or 3D. For the time dimension a `tstzspan` is given and for the spatial dimension minimum and maximum coordinate values are given, where the latter may be Cartesian (planar) or geodetic (spherical). The SRID of the coordinates may be specified; if it is not the case, a value of 0 (unknown) and 4326 (corresponding to WGS84) is assumed, respectively, for planar and geodetic boxes. Geodetic boxes always have a Z dimension to account for the curvature of the underlying sphere or spheroid. Examples of input of `stbox` values are as follows:

    -- Only value dimension with X and Y coordinates
    SELECT stbox 'STBOX X((1.0,2.0),(1.0,2.0))';
    -- Only value dimension with X, Y, and Z coordinates
    SELECT stbox 'STBOX Z((1.0,2.0,3.0),(1.0,2.0,3.0))';
    -- Both value (with X and Y coordinates) and time dimensions
    SELECT stbox 'STBOX XT(((1.0,2.0),(1.0,2.0)),[2001-01-03,2001-01-03])';
    -- Both value (with X, Y, and Z coordinates) and time dimensions
    SELECT stbox 'STBOX ZT(((1.0,2.0,3.0),(1.0,2.0,3.0)),[2001-01-01,2001-01-03])';
    -- Only time dimension
    SELECT stbox 'STBOX T([2001-01-03,2001-01-03])';
    -- Only value dimension with X, Y, and Z geodetic coordinates
    SELECT stbox 'GEODSTBOX Z((1.0,2.0,3.0),(1.0,2.0,3.0))';
    -- Both value (with X, Y and Z geodetic coordinates) and time dimension
    SELECT stbox 'GEODSTBOX ZT(((1.0,2.0,3.0),(1.0,2.0,3.0)),[2001-01-04,2001-01-04])';
    -- Only time dimension for geodetic box
    SELECT stbox 'GEODSTBOX T([2001-01-03,2001-01-03])';
    -- SRID is given
    SELECT stbox 'SRID=5676;STBOX XT(((1.0,2.0),(1.0,2.0)),[2001-01-04,2001-01-04])';
    SELECT stbox 'SRID=4326;GEODSTBOX Z((1.0,2.0,3.0),(1.0,2.0,3.0))';

We give next the functions for input and output of box types in Well-Known Text and Well-Known Binary format.

- Return the Well-Known Text (WKT) representation

  `asText(box,maxdecdigits=15) → text`

  The `maxdecdigits` argument can be used to set the maximum number of decimal places in the output of floating point values (default 15).

      SELECT asText(tbox 'TBOXFLOAT XT([1.123456789,2.123456789),[2001-01-01,2001-01-02))', 3);
      -- TBOXFLOAT XT([1.123, 2.123),[2001-01-01 00:00:00+01, 2001-01-02 00:00:00+01))
      SELECT asText(stbox 'STBOX Z((1.55,1.55,1.55),(2.55,2.55,2.55))', 0);
      -- STBOX Z((2,2,2),(3,3,3))

- Return the Well-Known Binary (WKB) or the Hexadecimal Well-Known Binary (HexWKB) representation

  `asBinary(box,endian text='') → bytea`

  `asHexWKB(box,endian text='') → text`

  The result is encoded using either the little-endian (NDR) or the big-endian (XDR) encoding. If no encoding is specified, then the encoding of the machine is used.

      SELECT asBinary(tbox 'TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))');
      -- \x0103270001009c57d3c11c000000fc2ef1d51c00000d0001000000000000f03f0000000000000040
      SELECT asBinary(tbox 'TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))', 'XDR');
      -- \x000300270100001cc1d3579c0000001cd5f12efc00000d013ff00000000000004000000000000000
      SELECT asBinary(stbox 'STBOX X((1,1),(2,2))');
      -- \x0101000000000000f03f0000000000000040000000000000f03f0000000000000040
      SELECT asHexWKB(tbox 'TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))');
      -- 0103270001009C57D3C11C000000FC2EF1D51C00000D0001000000000000F03F0000000000000040
      SELECT asHexWKB(tbox 'TBOXFLOAT XT([1,2)[2001-01-01,2001-01-02))', 'XDR');
      -- 000300270100001CC1D3579C0000001CD5F12EFC00000D013FF00000000000004000000000000000
      SELECT asHexWKB(stbox 'STBOX X((1,1),(2,2))');
      -- 0101000000000000F03F0000000000000040000000000000F03F0000000000000040

- Input from the Well-Known Binary (WKB) or from the Hexadecimal Well-Known Binary (HexWKB) representation

  `boxFromBinary(bytea) → box`

  `boxFromHexWKB(text) → box`

  In the signatures above, `box` replaces any box type, that is, `tbox` or `stbox`.

      SELECT tboxFromBinary(
        '\x0103270001009c57d3c11c000000fc2ef1d51c00000d0001000000000000f03f0000000000000040');
      -- TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02))
      SELECT stboxFromBinary(
        '\x0101000000000000f03f0000000000000040000000000000f03f0000000000000040');
      --  STBOX X((1,1),(2,2))
      SELECT tboxFromHexWKB(
        '0103270001009C57D3C11C000000FC2EF1D51C00000D0001000000000000F03F0000000000000040');
      -- TBOXFLOAT XT([1,2),[2001-01-01,2001-01-02)))
      SELECT stboxFromHexWKB(
        '0101000000000000F03F0000000000000040000000000000F03F0000000000000040');
      -- STBOX X((1,1),(2,2))

## Constructors

Type `tbox` has several constructor functions depending on whether the value and/or the time extent are given. The value extent can be specified by a number or a span, while the time extent can be specified by a time type.

- Constructor for `tbox`

  `tbox({number,numspan}) → tbox`

  `tbox({timestamptz,tstzspan}) → tbox`

  `tbox({number,numspan},{timestamptz,tstzspan}) → tbox`

      -- Both value and time dimensions
      SELECT tbox(1.0, timestamptz '2001-01-01');
      SELECT tbox(floatspan '[1.0, 2.0)', tstzspan '[2001-01-01,2001-01-02)');
      -- Only value dimension
      SELECT tbox(floatspan '[1.0,2.0)');
      -- Only time dimension
      SELECT tbox(tstzspan '[2001-01-01,2001-01-02)');

Type `stbox` has several constructor functions depending on whether the space and/or the time extent are given. The coordinates for the spatial extent can be 2D or 3D and can be either Cartesian or geodetic. The spatial extent can be specified by the minimum and maximum coordinate values. The SRID can be specified in an optional last argument. If not given, a value 0 (respectively 4326) is assumed by default for planar (respectively geodetic) boxes. The spatial extent can also be specified by a geometry or a geography. The temporal extent can be specified by a time type.

- Constructor for `stbox`

  `stboxX(float,float,float,float,srid=0) → stbox`

  `stboxZ(float,float,float,float,float,float,srid=0) → stbox`

  `stboxT({timestamptz,tstzspan}) → stbox`

  `stboxXT(float,float,float,float,{timestamptz,tstzspan},srid=0) → stbox`

  `stboxZT(float,float,float,float,float,float,{timestamptz,tstzspan},srid=0) → stbox`

  `geodstboxZ(float,float,float,float,float,float,srid=4326) → stbox`

  `geodstboxT({timestamptz,tstzspan}) → stbox`

  `geodstboxZT(float,float,float,float,float,float,{timestamptz,tstzspan},srid=4326)`

  `→ stbox`

  `stbox(geo) → stbox`

  `stbox(geo,{timestamptz,tstzspan}) → stbox`

      -- Only value dimension with X and Y coordinates
      SELECT stboxX(1.0,2.0,1.0,2.0);
      -- Only value dimension with X, Y, and Z coordinates
      SELECT stboxZ(1.0,2.0,3.0,1.0,2.0,3.0);
      -- Only value dimension with X, Y, and Z coordinates and SRID
      SELECT stboxZ(1.0,2.0,3.0,1.0,2.0,3.0,5676);
      -- Only time dimension
      SELECT stboxT(tstzspan '[2001-01-03,2001-01-03]');
      -- Both value (with X and Y coordinates) and time dimensions
      SELECT stboxXT(1.0,2.0, 1.0,2.0, tstzspan '[2001-01-03,2001-01-03]');
      -- Both value (with X, Y, and Z coordinates) and time dimensions
      SELECT stboxZT(1.0,2.0,3.0, 1.0,2.0,3.0, tstzspan '[2001-01-03,2001-01-03]');
      -- Only value dimension with X, Y, and Z geodetic coordinates
      SELECT geodstboxZ(1.0,2.0,3.0,1.0,2.0,3.0);
      -- Only time dimension for geodetic box
      SELECT geodstboxT(tstzspan '[2001-01-03,2001-01-03]');
      --  Both value (with X, Y, and Z geodetic coordinates) and time dimensions
      SELECT geodstboxZT(1.0,2.0,3.0, 1.0,2.0,3.0, tstzspan '[2001-01-03,2001-01-04]');
      -- Geometry and time dimension
      SELECT stbox(geometry 'Linestring(1 1 1,2 2 2)', tstzspan '[2001-01-03,2001-01-05]');
      -- Geography and time dimension
      SELECT stbox(geography 'Linestring(1 1 1,2 2 2)', tstzspan '[2001-01-03,2001-01-05]');

## Conversions

- Convert a `tbox` to another type

  `tbox::{intspan,floatspan,tstzspan}`

  `intspan(tbox) → tbox`

  `floatspan(tbox) → tbox`

  `tstzspan(tbox) → tbox`

      SELECT tbox 'TBOXINT XT([1,4),[2001-01-01,2001-01-02))'::intspan;
      -- [1,4)
      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02))'::floatspan;
      -- (1, 2)
      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02))'::tstzspan;
      -- [2001-01-01, 2001-01-02)

- Convert another type to a `tbox`

  `{numbers,times,tnumber}::tbox`

  `tbox({numbers,times,tnumber}) → tbox`

      SELECT intset '{1,2}'::tbox;
      -- TBOXINT X([1, 3))
      SELECT intspan '[1,3)'::tbox;
      -- TBOXINT X([1, 3))
      SELECT floatspan '(1.0,2.0)'::tbox;
      -- TBOXFLOAT X((1, 2))
      SELECT tstzspanset '{(2001-01-01,2001-01-02),(2001-01-03,2001-01-04)}'::tbox;
      -- TBOX T((2001-01-01,2001-01-04))

- Convert an `stbox` to a another type

  `stbox::{box2d,box3d,geo,tstzspan}`

  `box2d(stbox) → box2d`

  `box3d(stbox) → box2d`

  `geometry(stbox) → geometry`

  `geography(stbox) → geography`

  `tstzspan(stbox) → tstzspan`

      SELECT stbox 'STBOX XT(((1.0,2.0),(3.0,4.0)),[2001-01-01,2001-01-03])'::box2d;
      -- BOX(1 2,3 4)
      SELECT ST_AsEWKT(stbox 'SRID=4326;STBOX XT(((1,1),(5,5)),[2001-01-01,2001-01-05])'::
        geometry);
      -- SRID=4326;POLYGON((1 1,1 5,5 5,5 1,1 1))
      SELECT ST_AsEWKT(stbox 'STBOX XT(((1,1),(1,5)),[2001-01-01,2001-01-05])'::geometry);
      -- LINESTRING(1 1,1 5)
      SELECT ST_AsEWKT(stbox 'GEODSTBOX XT(((1,1),(1,1)),[2001-01-01,2001-01-05])'::geography);
      -- SRID=4326;POINT(1 1)
      SELECT ST_AsEWKT(stbox 'STBOX ZT(((1,1,1),(5,5,5)),[2001-01-01,2001-01-05])'::
        geometry);
      /* POLYHEDRALSURFACE(((1 1 1,1 5 1,5 5 1,5 1 1,1 1 1)),
         ((1 1 5,5 1 5,5 5 5,1 5 5,1 1 5)),((1 1 1,1 1 5,1 5 5,1 5 1,1 1 1)),
         ((5 1 1,5 5 1,5 5 5,5 1 5,5 1 1)),((1 1 1,5 1 1,5 1 5,1 1 5,1 1 1)),
         ((1 5 1,1 5 5,5 5 5,5 5 1,1 5 1))) */
      SELECT stbox 'STBOX XT(((1.0,2.0),(3.0,4.0)),[2001-01-01,2001-01-03])'::tstzspan;
      -- [2001-01-01, 2001-01-03]

- Convert another type to an `stbox`

  `{box2d,box3d,geo,time,tgeo}::stbox`

  `stbox({box2d,box3d,geo,time,tgeo}) → stbox`

      SELECT geometry 'Linestring(1 1 1,2 2 2)'::box3d::stbox;
      -- STBOX Z((1,1,1),(2,2,2))
      SELECT geography 'Linestring(1 1,2 2)'::stbox;
      -- SRID=4326;GEODSTBOX X((1,1),(2,2))
      SELECT tstzspanset '{(2001-01-01,2001-01-02),(2001-01-03,2001-01-04)}'::stbox;
      -- STBOX T((2001-01-01,2001-01-04))

## Accessors

- Has X/Z/T dimension?

  `hasX(box) → boolean`

  `hasZ(stbox) → boolean`

  `hasT(box) → boolean`

      SELECT hasX(tbox 'TBOX T([2001-01-01,2001-01-03))');
      -- false
      SELECT hasX(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
      -- true
      SELECT hasZ(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
      -- false
      SELECT hasT(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03])');
      -- true
      SELECT hasT(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
      -- false

- Is geodetic?

  `isGeodetic(stbox) → boolean`

      SELECT isGeodetic(stbox 'GEODSTBOX Z((1.0,1.0,0.0),(3.0,3.0,1.0))');
      -- true
      SELECT isGeodetic(stbox 'STBOX XT(((1.0,2.0),(3.0,4.0)),[2001-01-01,2001-01-02])');
      -- false

- Return the minimum X/Y/Z/T value

  `xMin(box) → float`

  `yMin(stbox) → float`

  `zMin(stbox) → float`

  `tMin(box) → timestamptz`

      SELECT xMin(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03))');
      -- 1
      SELECT yMin(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
      -- 2
      SELECT zMin(stbox 'STBOX Z((1.0,2.0,3.0),(4.0,5.0,6.0))');
      -- 3
      SELECT tMin(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
      -- 2001-01-01

  Notice that for `tbox` the result value for `xMin` and `xMin` is converted to a `float` for the temporal boxes with an integer span.

- Return the maximum X/Y/Z/T value

  `xMax(box) → float`

  `yMax(stbox) → float`

  `zMax(stbox) → float`

  `tMax(box) → timestamptz`

      SELECT xMax(tbox 'TBOXINT X([1,4))');
      -- 3
      SELECT yMax(stbox 'STBOX X((1.0,2.0),(3.0,4.0))');
      -- 4
      SELECT zMax(stbox 'STBOX Z((1.0,2.0,3.0),(4.0,5.0,6.0))');
      -- 6
      SELECT tMax(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
      -- 2001-01-03

  Notice that for `tbox` the result value for `xMin` and `xMin` is converted to a `float` for the temporal boxes with an integer span.

- Is the minimum X/T value inclusive?

  `xMinInc(tbox) → bool`

  `tMinInc(box) → bool`

      SELECT xMinInc(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03))');
      -- false
      SELECT tMinInc(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
      -- true

- Is the maximum X/T value inclusive?

  `xMaxInc(tbox) → bool`

  `tMaxInc(box) → bool`

      SELECT xMaxInc(tbox 'TBOXFLOAT XT((1.0,3.0),[2001-01-01,2001-01-03))');
      -- false
      SELECT tMaxInc(stbox 'GEODSTBOX T([2001-01-01,2001-01-03))');
      -- true

- Area, volume, perimeter

  `area(stbox, spheroid bool=true) → float`

  `volume(stbox) → float`

  `perimeter(stbox, spheroid bool=true) → float`

  For geodetic boxes, the computation is done on the WGS 84 spheroid by default. If the last argument is false, a faster spherical calculation is used. The `volume` function do not accept geodetic boxes.

      SELECT area(stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))');
      -- 4
      SELECT volume(stbox 'STBOX ZT(((1,1,1),(3,3,3)),[2001-01-01,2001-01-03))');
      -- 8
      SELECT perimeter(stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))');
      -- 8
      SELECT area(stbox 'GEODSTBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))');
      -- 49209676328.36632
      SELECT perimeter(stbox 'GEODSTBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03))', false);
      -- 889221.9544681838

## Transformations

- Shift and/or scale the span of a bounding box by one or two values

  `shiftValue(box,{integer,float}) → box`

  `scaleValue(box,{integer,float}) → box`

  `shiftScaleValue(tbox,{integer,float},{integer,float}) → box`

      SELECT shiftValue(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])', 1.0);
      -- TBOXFLOAT XT([2.5, 3.5],[2001-01-01, 2001-01-02])
      SELECT scaleValue(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])', 2.0);
      -- TBOXFLOAT XT([1.5, 3.5],[2001-01-01, 2001-01-02])
      SELECT shiftScaleValue(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])', 2.0, 3.0);
      -- TBOXFLOAT XT([3.5, 6.5],[2001-01-01, 2001-01-02])

- Shift and/or scale the span or the period of the bounding box to a value or interval

  `shiftTime(box,interval) → box`

  `scaleTime(box,interval) → box`

  `shiftScaleTime(box,interval,interval) → box`

  For scaling, if the width or the time span of the period is zero (that is, the lower and upper bound are equal), the result is the box. The given value or interval must be strictly greater than zero.

      SELECT shiftTime(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])',
        interval '1 day');
      -- TBOXFLOAT XT([1.5, 2.5],[2001-01-02, 2001-01-03])
      SELECT shiftTime(stbox 'STBOX T([2001-01-01,2001-01-02])', interval '-1 day');
      -- STBOX T([2001-12-31, 2001-01-01])
      SELECT shiftTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
        interval '1 day');
      -- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-02, 2001-01-03])
      SELECT scaleTime(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])',
        interval '2 days');
      -- TBOXFLOAT XT([1.5, 2.5],[2001-01-01, 2001-01-03])
      SELECT scaleTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
        interval '1 hour');
      -- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01 00:00:00, 2001-01-01 01:00:00])
      SELECT scaleTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
        interval '-1 day');
      -- ERROR:  The interval must be positive: -1 days
      SELECT shiftScaleTime(tbox 'TBOXFLOAT XT([1.5, 2.5],[2001-01-01,2001-01-02])',
        interval '1 day', interval '3 days');
      -- TBOXFLOAT XT([1.5, 2.5],[2001-01-02, 2001-01-05])
      SELECT shiftScaleTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])',
        interval '1 hour', interval '3 hours');
      -- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01 01:00:00, 2001-01-01 04:00:00])

- Return the spatial dimension of the bounding box, removing the temporal dimension if any

  `getSpace(stbox) → stbox`

      SELECT getSpace(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-03])');
      -- STBOX Z((1,1,1),(2,2,2))

The functions given next expand the bounding boxes on the value and the time dimension or set the precision of the value dimension. These functions raise an error if the corresponding dimension is not present.

- Expand the numeric, spatial, or temporal dimension of a bounding box by a value or an interval

  `expandValue(tbox,{integer,float}) → tbox`

  `expandSpace(stbox,float) → stbox`

  `expandTime(box,interval) → box`

  The function returns NULL if the value or interval given as second argument is negative and the span resulting from shifting the bounds with the argument is empty.

      SELECT expandValue(tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-03])', 1.0);
      -- TBOXFLOAT XT((0,3),[2001-01-01,2001-01-03])
      SELECT expandValue(tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-03])', -1.0);
      -- NULL
      SELECT expandValue(tbox 'TBOX T([2001-01-01,2001-01-03))', 1);
      -- The box must have value dimension

      SELECT expandSpace(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-03])', 1);
      -- STBOX ZT(((0,0,0),(3,3,3)),[2001-01-01,2001-01-03])
      SELECT expandSpace(stbox 'STBOX T([2001-01-01,2001-01-03))', 1);
      -- The box must have space dimension

      SELECT expandTime(tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-03])', interval '1 day');
      -- TBOXFLOAT XT((1,2),[2000-12-31,2001-01-04])
      SELECT expandTime(stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-03])',
        interval '-1 day');
      -- STBOX ZT(((1,1,1),(2,2,2)),[2001-01-02,2001-01-02])
      SELECT expandTime(tbox 'TBOX XT((1,2),[2001-01-01,2001-01-03])', interval '-2 days');
      -- NULL

- Round the value or the coordinates of the bounding box to a number of decimal places

  `round(box,integer=0) → box`

      SELECT round(tbox 'TBOXFLOAT XT((1.12345,2.12345),[2001-01-01,2001-01-02])', 2);
      -- TBOXFLOAT XT((1.12,2.12),[2001-01-01, 2001-01-02])
      SELECT round(stbox 'STBOX XT(((1.12345, 1.12345),(2.12345, 2.12345)),
        [2001-01-01,2001-01-02])', 2);
      -- STBOX XT(((1.12,1.12),(2.12,2.12)),[2001-01-01, 2001-01-02])
      SELECT round(tstzspan '[2000-01-01, 2001-01-02]'::tbox);
      -- The tbox must have X dimension

## Spatial Reference System

- Return or set the spatial reference identifier

  `SRID(stbox) → integer`

  `setSRID(stbox) → stbox`

      SELECT SRID(stbox 'STBOX ZT(((1.0,2.0,3.0),(4.0,5.0,6.0)),[2001-01-01,2001-01-02])');
      -- 0
      SELECT SRID(stbox 'SRID=5676;STBOX XT(((1.0,2.0),(4.0,5.0)),[2001-01-01,2001-01-02])');
      -- 5676
      SELECT SRID(stbox 'GEODSTBOX T([2001-01-01,2001-01-02))');
      -- ERROR:  The box must have space dimension

      SELECT setSRID(stbox 'STBOX ZT(((1.0,2.0,3.0),(4.0,5.0,6.0)),
        [2001-01-01,2001-01-02])', 5676);
      -- SRID=5676;STBOX ZT(((1,2,3),(4,5,6)),[2001-01-01,2001-01-02])

- Transform to a spatial reference identifier

  `transform(stbox,to_srid integer) → stbox`

  `transformPipeline(stbox,pipeline text,to_srid integer,is_forward bool=true) → stbox`

  The `transform` function specifies the transformation with a target SRID. An error is raised when the input box 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 box is ignored, and the SRID of the output box 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 round(transform(stbox 'SRID=4326;STBOX XT(((2.340088, 49.400250),
        (6.575317, 51.553167)),[2001-01-01,2001-01-02])', 3812), 6);
      /* SRID=3812;STBOX XT(((502773.429981,511805.120402),(803028.908265,751590.742629)),
        [2001-01-01, 2001-01-02]) */
      WITH test(box, pipeline) AS (
        SELECT stbox 'SRID=4326;GEODSTBOX Z((-0.1275,50.846667,100),(4.3525,51.507222,100))',
          text 'urn:ogc:def:coordinateOperation:EPSG::16031' )
      SELECT asEWKT(transformPipeline(transformPipeline(box, pipeline, 4326),
        pipeline, 4326, false), 6)
      FROM test;
      -- SRID=4326;GEODSTBOX Z((-0.1275,50.846667,100),(4.3525,51.507222,100))

## Splitting Operations

- Split the bounding box in quadrants or octants &SRF;

  `quadSplit(stbox) → {stbox}`

  As indicated by the &SRF; symbol, this function is a set-returning function (also known as a table function) since it typically return more than one value.

      SELECT quadSplit(stbox 'STBOX XT(((0,0),(4,4)),[2001-01-01,2001-01-05])');
      /* {"STBOX XT(((0,0),(2,2)),[2001-01-01, 2001-01-05])",
         "STBOX XT(((2,0),(4,2)),[2001-01-01, 2001-01-05])",
         "STBOX XT(((0,2),(2,4)),[2001-01-01, 2001-01-05])",
         "STBOX XT(((2,2),(4,4)),[2001-01-01, 2001-01-05])"} */
      SELECT quadSplit(stbox 'STBOX Z((0,0,0),(4,4,4))');
      /* {"STBOX Z((0,0,0),(2,2,2))","STBOX Z((2,0,0),(4,2,2))","STBOX Z((0,2,0),(2,4,2))",
         "STBOX Z((2,2,0),(4,4,2))","STBOX Z((0,0,2),(2,2,4))","STBOX Z((2,0,2),(4,2,4))",
         "STBOX Z((0,2,2),(2,4,4))","STBOX Z((2,2,2),(4,4,4))"} */

This function is typically used for multiresolution grids, where the space is split in cells such that the cells have a maximum number of elements. berlinmod_grid shows an example of the result of using this function using synthetic trajectories in Brussels.

### Multiresolution grid on Brussels data obtained using the BerlinMOD generator. Each cell contains at most 10,000 (left) and 1,000 (right) instants across the entire simulation period (four days in this case). On the left, we can see the high density of the traffic in the ring around Brussels, while on the right we can see other main axes in the city.

## Set Operations

The set operators for box types are union (`+`) and intersection (`*`). In the case of union, the operands must have exactly the same dimensions, otherwise an error is raised. Furthermore, if the operands do not overlap on all the dimensions and error is raised, since in this would result in a box with disjoint values, which cannot be represented. The operator computes the union on all dimensions that are present in both arguments. In the case of intersection, the operands must have at least one common dimension, otherwise an error is raised. The operator computes the intersection on all dimensions that are present in both arguments.

- Union and intersection of two bounding boxes

  `box {+, *} box → box`

      SELECT tbox 'TBOXINT XT([1,3),[2001-01-01,2001-01-03])' +
        tbox 'TBOXINT XT([2,4),[2001-01-02,2001-01-04])';
      -- TBOXINT XT([1,4),[2001-01-01,2001-01-04])
      SELECT stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])' +
        stbox 'STBOX XT(((2,2),(3,3))),[2001-01-01,2001-01-03]';
      -- ERROR:  The arguments must be of the same dimensionality
      SELECT tbox 'TBOXFLOAT XT((1,3),[2001-01-01,2001-01-02])' +
        tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
      -- ERROR:  Result of box union would not be contiguous

      SELECT tbox 'TBOXINT XT([1,3),[2001-01-01,2001-01-03])' *
        tbox 'TBOX T([2001-01-02,2001-01-04))';
      -- TBOX T([2001-01-02,2001-01-03))
      SELECT stbox 'STBOX ZT(((1,1,1),(3,3,3)),[2001-01-01,2001-01-02])' *
        stbox 'STBOX X((2,2),(4,4))';
      -- STBOX X((2,2),(3,3))

## Bounding Box Operations

### Topological Operations

There are five topological operators: overlaps (`&&`), contains (`@>`), contained (`<@`), same (`~=`), and adjacent (`-|-`). The operators verify the topological relationship between the bounding boxes taking into account the value and/or the time dimension for as many dimensions that are present on both arguments.

- Do the bounding boxes overlap?

  `box && box → boolean`

      SELECT tbox 'TBOXFLOAT XT((1,3),[2001-01-01,2001-01-03])' &&
        tbox 'TBOXFLOAT XT((2,4),[2001-01-02,2001-01-04])';
      -- true
      SELECT stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])' &&
        stbox 'STBOX T([2001-01-02,2001-01-02])';
      -- true

- Does the first bounding box contain the second one?

  `box @> box → boolean`

      SELECT tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])' @>
        tbox 'TBOXFLOAT XT((2,3),[2001-01-01,2001-01-02])';
      -- true
      SELECT stbox 'STBOX Z((1,1,1),(3,3,3))' @>
        stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])';
      -- true

- Is the first bounding box contained in the second one?

  `box <@ box → boolean`

      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' <@
        tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])';
      -- true
      SELECT stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])' <@
        stbox 'STBOX ZT(((1,1,1),(2,2,2)),[2001-01-01,2001-01-02])';
      -- true

- Are the bounding boxes equal in their common dimensions?

  `box ~= box → boolean`

      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' ~=
        tbox 'TBOXFLOAT T([2001-01-01,2001-01-02])';
      -- true
      SELECT stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03])' ~=
        stbox 'STBOX Z((1,1,1),(3,3,3))';
      -- true

- Are the bounding boxes adjacent?

  `box -|- box → boolean`

  Two boxes are adjacent if they share n dimensions and their intersection is at most of n-1 dimensions.

      SELECT tbox 'TBOXINT XT([1,2),[2001-01-01,2001-01-02])' -|-
        tbox 'TBOXINT XT([2,3),[2001-01-02,2001-01-03])';
      -- true
      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' -|-
        tbox 'TBOX T([2001-01-02,2001-01-03])';
      -- true
      SELECT stbox 'STBOX XT(((1,1),(3,3)),[2001-01-01,2001-01-03])' -|-
        stbox 'STBOX XT(((2,2),(4,4)),[2001-01-03,2001-01-04])';
      -- true

### Position Operations

The position operators consider the relative position of the bounding boxes. The operators `<<`, `>>`, `&<`, and `&>` consider the X value for the `tbox` type and the X coordinates for the `stbox` type, the operators `<<|`, `|>>`, `&<|`, and `|&>` consider the Y coordinates for the `stbox` type, the operators `<</`, `/>>`, `&</`, and `/&>` consider the Z coordinates for the `stbox` type, and the operators `<<#`, `#>>`, `#&<`, and `#&>` consider the time dimension for the `tbox` and `stbox` types. The operators raise an error if both boxes do not have the required dimension.

The operators for the numeric dimension of the `tbox` type are given next.

- Are the X/Y/Z/T values of the first bounding box strictly less than those of the second one?

  `tbox {<<, <<#} tbox → boolean`

  `stbox {<<, <<|, <</, <<#} stbox → boolean`

      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' <<
        tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
      -- true
      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' <<
        tbox 'TBOXFLOAT T([2001-01-03,2001-01-04])';
      -- ERROR:  The box must have value dimension
      SELECT stbox 'STBOX Z((1,1,1),(2,2,2))' <<| stbox 'STBOX Z((3,3,3),(4,4,4))';
      -- true
      SELECT stbox 'STBOX Z((1,1,1),(2,2,2))' <</ stbox 'STBOX Z((3,3,3),(4,4,4))';
      -- true
      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' <<#
        tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
      -- true

- Are the X/Y/Z/T values of the first bounding box strictly greater than those of the second one?

  `tbox {>>, #>>} tbox → boolean`

  `stbox {>>, |>>, />>, #>>} stbox → boolean`

      SELECT tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])' >>
        tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])';
      -- true
      SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' |>> stbox 'STBOX Z((1,1,1),(2,2,2))';
      -- true
      SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' />> stbox 'STBOX Z((1,1,1),(2,2,2))';
      -- true
      SELECT stbox 'STBOX XT(((3,3),(4,4)),[2001-01-03,2001-01-04])'  #>>
        stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])';
      -- true

- Are the X/Y/Z/T values of the first bounding box not greater than those of the second one?

  `tbox {&<, &<#} {tbox,stbox} → boolean`

  `stbox {&<, &<|, &</, &<#} stbox → boolean`

      SELECT tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])' &<
        tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
      -- true
      SELECT stbox 'STBOX Z((1,1,1),(4,4,4))' &<| stbox 'STBOX Z((3,3,3),(4,4,4))';
      -- true
      SELECT stbox 'STBOX Z((1,1,1),(4,4,4))' &</ stbox 'STBOX Z((3,3,3),(4,4,4))';
      -- true
      SELECT tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])' &<#
        tbox 'TBOXFLOAT XT((3,4),[2001-01-03,2001-01-04])';
      -- true

- Are the X/Y/Z/T values of the first bounding box not less than those of the second one?

  `tbox {&>, #&>} tbox → boolean`

  `stbox {&>, |&>, /&>, #&>} stbox} → boolean`

      SELECT tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-02])' &>
        tbox 'TBOXFLOAT XT((1,4),[2001-01-01,2001-01-04])';
      -- true
      SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' |&> stbox 'STBOX Z((1,1,1),(2,2,2))';
      -- false
      SELECT stbox 'STBOX Z((3,3,3),(4,4,4))' /&> stbox 'STBOX Z((1,1,1),(2,2,2))';
      -- true
      SELECT stbox 'STBOX XT(((1,1),(2,2)),[2001-01-01,2001-01-02])' #&>
        stbox 'STBOX XT(((1,1),(4,4)),[2001-01-01,2001-01-04])';
      -- true

## Comparisons

The traditional comparison operators (`=`, `<`, and so on) can be applied to box types. Excepted equality and inequality, the other comparison operators are not useful in the real world but allow B-tree indexes to be constructed on box types. These operators compare first the timestamps and if those are equal, compare the values.

- Traditional comparisons

  `box {=, <>, <, <=, >=} box → boolean`

  `tbox_cmp(tbox,tbox) → int`

  `stbox_cmp(stbox,stbox) → int`

  Functions `tbox_cmp` and `stbox_cmp` returns -1, 0, or 1 depending on whether the first argument is, respectively, less than, equal to, or greater than the second one.

      SELECT tbox 'TBOXINT XT([1,1],[2001-01-01,2001-01-04])' =
        tbox 'TBOXINT XT([2,2],[2001-01-03,2001-01-05])';
      -- false
      SELECT tbox 'TBOXFLOAT XT([1,1],[2001-01-01,2001-01-04])' <>
        tbox 'TBOXFLOAT XT([2,2],[2001-01-03,2001-01-05])';
      -- true
      SELECT tbox 'TBOXINT XT([1,1],[2001-01-01,2001-01-04])' <
        tbox 'TBOXINT XT([1,2],[2001-01-03,2001-01-05])';
      -- true
      SELECT tbox 'TBOXFLOAT XT([1,1],[2001-01-03,2001-01-04])' >
        tbox 'TBOXFLOAT XT((1,2),[2001-01-01,2001-01-05])';
      -- true
      SELECT tbox 'TBOXINT XT([1,1],[2001-01-01,2001-01-04])' <=
        tbox 'TBOXINT XT([2,2],[2001-01-03,2001-01-05])';
      -- true
      SELECT tbox 'TBOXFLOAT XT([1,1],[2001-01-01,2001-01-04])' >=
        tbox 'TBOXFLOAT XT([2,2],[2001-01-03,2001-01-05])';
      -- false
      SELECT tbox_cmp(tbox 'TBOXFLOAT XT([1,1],[2001-01-01,2001-01-04])',
        tbox 'TBOXFLOAT XT([2,2],[2001-01-03,2001-01-05])');
      -- -1

## Aggregations

- Bounding box extent

  `extent(box) → box`

      WITH boxes(b) AS (
        SELECT tbox 'TBOXFLOAT XT((1,3),[2001-01-01,2001-01-03])' UNION
        SELECT tbox 'TBOXFLOAT XT((5,7),[2001-01-05,2001-01-07])' UNION
        SELECT tbox 'TBOXFLOAT XT((6,8),[2001-01-06,2001-01-08])' )
      SELECT extent(b) FROM boxes;
      -- TBOXFLOAT XT((1,8),[2001-01-01,2001-01-08])
      WITH boxes(b) AS (
        SELECT stbox 'STBOX Z((1,1,1),(3,3,3))' UNION
        SELECT stbox 'STBOX Z((5,5,5),(7,7,7))' UNION
        SELECT stbox 'STBOX Z((6,6,6),(8,8,8))' )
      SELECT extent(b) FROM boxes;
      -- STBOX Z((1,1,1),(8,8,8))

## Indexing

GiST and SP-GiST indexes can be created for table columns of the `tbox` and `stbox` types. The GiST index implements an R-tree and the SP-GiST index implements an n-dimensional quad-tree. An example of creation of a GiST index in a column `Box` of type `stbox` in a table `Trips` is as follows:

    CREATE TABLE Trips(TripID integer PRIMARY KEY, Trip tgeompoint, Box stbox);
    CREATE INDEX Trips_Box_Idx ON Trips USING GIST(bbox);

A GiST or SP-GiST index can accelerate queries involving the following operators: `&&`, `<@`, `@>`, `~=`, `-|-`, `<<`, `>>`, `&<`, `&>`, `<<|`, `|>>`, `&<|`, `|&>`, `<</`, `/>>`, `&</`, `/&>`, `<<#`, `#>>`, `&<#`, and `#&>`.

In addition, B-tree indexes can be created for table columns of a bounding box type. For these index types, basically the only useful operation is equality. There is a B-tree sort ordering defined for values of bounding box types, with corresponding `<` and `>` operators, but the ordering is rather arbitrary and not usually useful in the real world. The B-tree support is primarily meant to allow sorting internally in queries, rather than creation of actual indexes.