Temporal Point Cloud Patches

A tpcpatch is the lifting of pcpatch. It mirrors tpcpoint in every regard, same subtypes, same accessors, same casts and operators, except that each instant carries an entire compressed batch of points instead of a single point. The bounding box is again a tpcbox, whose X and Y extent per instant is the patch's embedded PCBOUNDS and whose Z extent, where the schema holds a Z dimension, is the one the points of the patch state.

Operations on a tpcpatch come at two granularities, because the points of a patch sit in a compressed payload that the bounding box layer cannot inspect. At patch level each instant's patch is kept or dropped as a whole, read from its extent and the instant's timestamp alone: this is the granularity of atTpcbox / minusTpcbox, of the bounding box operators and of the extent aggregate. The X and Y extent is the 4-double PCBOUNDS header (xmin / xmax / ymin / ymax), read without decompressing the payload; PCBOUNDS being 2D, the Z extent, which a tpcbox with Z tests, is the one the points of the patch state.

At point level every point of every instant is walked in C. points emits one row per instant timestamp and point, while atTpcboxFine / minusTpcboxFine, atGeometry / minusGeometry and eIntersects(tpcpatch,geometry) apply their predicate to the actual coordinates and rebuild each surviving instant from the points that passed, dropping the instants that keep none. Prune at patch level first, with atTpcbox or a GiST / SP-GiST index scan, and refine the survivors when point-level fidelity is needed.

Input and Output

  • Return the text representation of a tpcpatch, or of an array of them, with or without its SRID, and cast a tpcpatch to text

    asText(tpcpatch) → text
    asText(tpcpatch[]) → text[]
    asEWKT(tpcpatch) → text
    asEWKT(tpcpatch[]) → text[]
    tpcpatch::text → text
    

    As for a tpcpoint, asEWKT prefixes the SRID the schema of the pcid declares, and writes the text form alone under a schema declaring none.

    -- The pcpatch payload renders as hex-encoded WKB.
    SELECT left(asText(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz)), 24);
    -- EC0100000100000000000000
    SELECT left(asEWKT(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz)), 24);
    -- EC0100000100000000000000
    
  • Return the binary or hexadecimal well-known binary representation of a tpcpatch, with or without its SRID

    asBinary(tpcpatch,endian text='') → bytea
    asEWKB(tpcpatch,endian text='') → bytea
    asHexWKB(tpcpatch,endian text='') → text
    asHexEWKB(tpcpatch,endian text='') → text
    
    SELECT tpcpatchFromHexEWKB(asHexEWKB(t)) = t
    FROM (SELECT tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)),
      '2001-01-01'::timestamptz) AS t) s;
    -- t
    
  • Return a tpcpatch from its text, binary, or hexadecimal well-known binary representation, with or without its SRID

    tpcpatchFromText(text) → tpcpatch
    tpcpatchFromEWKT(text) → tpcpatch
    tpcpatchFromBinary(bytea) → tpcpatch
    tpcpatchFromEWKB(bytea) → tpcpatch
    tpcpatchFromHexWKB(text) → tpcpatch
    tpcpatchFromHexEWKB(text) → tpcpatch
    

    The pcid each patch carries names its schema, so the text form reads back as the binary one does, and an SRID the input states must be the one that schema declares.

    SELECT tpcpatchFromText(asText(t)) = t
    FROM (SELECT tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)),
      '2001-01-01'::timestamptz) AS t) s;
    -- t
    SELECT tpcpatchFromEWKT('SRID=4326;' || asText(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz)));
    -- ERROR:  The SRID of a pcpatch is the one its schema declares and cannot be set
    
  • Return the Moving Features JSON (MF-JSON) representation of a tpcpatch and read it back; the round trip is lossless

    asMFJSON(tpcpatch,options integer=0,flags integer=0,maxdecimaldigits integer=15) → text
    tpcpatchFromMFJSON(text) → tpcpatch
    

    A tpcpatch is emitted under the type tag "MovingPCPatch", each instant stating the object {"pcid":N, "npoints":N, "bounds":[xmin,xmax,ymin,ymax], "pts":[[…], …]}. The points are pgPointCloud's text form of the patch, every dimension of each point in the order its schema states them and in the shortest decimal form that reads back as the same double, whatever maxdecimaldigits states. tpcpatchFromMFJSON rebuilds each patch from its points in the compression its schema states, and refuses a point that does not state every dimension of the schema.

    SELECT asMFJSON(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz));
    /* {"type":"MovingPCPatch","values":[{"pcid":1,"npoints":2,"bounds":[1,2,1,2],
       "pts":[[1,1,1],[2,2,2]]}],"datetimes":["2001-01-01T00:00:00"],"interpolation":"None"} */
    SELECT tpcpatchFromMFJSON(asMFJSON(t)) = t
    FROM (SELECT tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)),
      '2001-01-01'::timestamptz) AS t) s;
    -- t
    

As for a tpcpoint, asText takes no maxdecimaldigits argument.

Constructors

  • Constructor for temporal point cloud patches having a constant value

    tpcpatch(pcpatch,timestamptz) → tpcpatchInst
    tpcpatch(pcpatch,tstzset) → tpcpatchDiscSeq
    tpcpatch(pcpatch,tstzspan) → tpcpatchContSeq
    tpcpatch(pcpatch,tstzspanset) → tpcpatchSeqSet
    
    SELECT tempSubtype(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz));
    -- Instant
    SELECT tempSubtype(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), tstzspan '[2001-01-01, 2001-01-02]'));
    -- Sequence
    
  • Construct a temporal pcpatch of sequence subtype

    tpcpatchSeq(tpcpatch[]) → tpcpatch
    tpcpatchSeq(tpcpatch[],text) → tpcpatch
    
    SELECT numInstants(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)])), interp(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]));
    -- 2 | Step
    
  • Construct a temporal pcpatch of sequence-set subtype

    tpcpatchSeqSet(tpcpatch[]) → tpcpatch
    
    SELECT numSequences(tpcpatchSeqSet(ARRAY[tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3),
      pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)])]));
    -- 1
    

Conversions

  • Convert a temporal patch into the temporal geometry of the multipoints its patches occupy

    tgeometry(tpcpatch) → tgeometry
    tgeography(tpcpatch) → tgeography
    

    Each instant's patch becomes the multipoint of the positions its points occupy, read through the schema its pcid names

    SELECT asText(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz)::tgeometry);
    -- MULTIPOINT Z ((1 1 1),(2 2 2))@2001-01-01
    
  • Convert a temporal point cloud patch to its bounding box

    tpcbox(tpcpatch) → tpcbox
    tpcpatch::tpcbox
    

    The box is the one the extent of the value answers: the spatial extent of its points, its time span, the SRID its schema states and its pcid.

    SELECT tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz)::tpcbox;
    -- TPCBOX(ZT(((1,1,1),(2,2,2)),[2001-01-01, 2001-01-01]), 1)
    

Accessors

  • Return the number of points in the patch carried by the first or last instant

    startNumPoints(tpcpatch) → integer
    endNumPoints(tpcpatch) → integer
    
    SELECT startNumPoints(tpcpatch(pcpatch(pcpoint(1, 10.0, 20.0, 30.0)),
      '2024-02-01'::timestamptz));
    -- 1
    
  • Return the total number of points across every instant's patch

    numPoints(tpcpatch) → bigint
    

    Read directly from each patch's header, no decompression.

    SELECT numPoints(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1.0, 1.0, 1.0),
      pcpoint(1, 2.0, 2.0, 2.0)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3.0, 3.0, 3.0)), '2024-01-02'::timestamptz)]));
    -- 3
    
  • Set-returning function: emits one row per (instant timestamp, point) by walking each instant's patch and decomposing it through pgPointCloud's in-memory C API

    points(tpcpatch) → setof (t timestamptz,point pcpoint)
    

    Useful for joining a tpcpatch column against per-point predicates that the bbox-level operators can't express. Cost is O(total points), one per-instant decompression plus one row emission per point.

    SELECT t,
      point FROM points(tpcpatch(pcpatch(pcpoint(1, 1.0, 1.0, 1.0),
      pcpoint(1, 2.0, 2.0, 2.0)), '2024-01-01'::timestamptz));
    -- ('2024-01-01',
    -- '0101000000640000006400000064000000'::pcpoint)
    -- ('2024-01-01',
    -- '0101000000C8000000C8000000C8000000'::pcpoint)
    

Transformations

  • Transform a tpcpatch to another subtype

    tpcpatchInst(tpcpatch) → tpcpatch
    tpcpatchSeq(tpcpatch,interp text='step') → tpcpatch
    tpcpatchSeqSet(tpcpatch) → tpcpatch
    
    SELECT tempSubtype(tpcpatchSeq(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz)));
    -- Sequence
    
  • Transform a tpcpatch to another interpolation

    setInterp(tpcpatch,interp text) → tpcpatch
    
    SELECT interp(setInterp(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)],
      'discrete'), 'step'));
    -- Step
    

Modifications

  • Insert a tpcpatch into another one, or update another one with it

    insert(tpcpatch,tpcpatch,connect boolean=true) → tpcpatch
    update(tpcpatch,tpcpatch,connect boolean=true) → tpcpatch
    
    SELECT numInstants(insert(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]), tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5)), '2001-01-03'::timestamptz)])));
    -- 3
    
  • Delete a time selector (timestamp, set, period, or spanset) from a tpcpatch

    deleteTime(tpcpatch,times,connect boolean=true) → tpcpatch
    
    -- Deleting the middle instant splits the sequence into {[2001-01-01, 2001-01-02),
    -- (2001-01-02, 2001-01-03]}; each half stores its bound at the deleted timestamp, giving
    -- four instants.
    SELECT numInstants(deleteTime(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5)), '2001-01-03'::timestamptz)]),
      timestamptz '2001-01-02'));
    -- 4
    
  • Append an instant or a sequence to a tpcpatch

    appendInstant(tpcpatch,tpcpatch) → tpcpatch
    appendSequence(tpcpatch,tpcpatch) → tpcpatch
    
    SELECT numInstants(appendInstant(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3),
      pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)]),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5)), '2001-01-03'::timestamptz)));
    -- 3
    
  • Merge the temporal values

    merge(tpcpatch,tpcpatch) → tpcpatch
    merge(tpcpatch[]) → tpcpatch
    
    SELECT numInstants(merge(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 2, 2, 2)), '2001-01-02'::timestamptz)]),
      tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 2, 2, 2)), '2001-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3)), '2001-01-03'::timestamptz)])));
    -- 3
    SELECT numInstants(merge(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3)), '2001-01-03'::timestamptz)]));
    -- 2
    

Restrictions

  • Restrict a tpcpatch to (the complement of) a pcpatch value or a set of pcpatch values

    atValue(tpcpatch,pcpatch) → tpcpatch
    minusValue(tpcpatch,pcpatch) → tpcpatch
    atValues(tpcpatch,pcpatchset) → tpcpatch
    minusValues(tpcpatch,pcpatchset) → tpcpatch
    
    -- The matching value is held up to the next instant; the closing bound is stored as a
    -- second instant.
    SELECT numInstants(atValue(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]), pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2))));
    -- 2
    SELECT numInstants(minusValue(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]), pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2))));
    -- 1
    
  • Restrict a tpcpatch to the instants whose patch extent overlaps the tpcbox, or remove them

    atTpcbox(tpcpatch,tpcbox,border_inc boolean=true) → tpcpatch
    minusTpcbox(tpcpatch,tpcbox,border_inc boolean=true) → tpcpatch
    

    Granularity is patch-level: each surviving instant keeps its pcpatch payload verbatim. The X and Y extent of a patch is pgPointCloud's 2D PCBOUNDS; when the box has Z, the Z extent of the patch is the one its points state, and a patch of a schema without Z fails the box. A tpcbox of another schema, reference system or kind of coordinate raises an error, as the operators of the boxes do.

    SELECT numInstants(atTpcbox(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3),
      pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)]),
      tpcboxXT(0, 0, 2, 2, tstzspan '[2001-01-01, 2001-01-03]', 1)));
    -- 1
    -- The dropped patch stays present on the open interval before its instant,
    -- so the complement keeps two instants.
    SELECT numInstants(minusTpcbox(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3),
      pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)]),
      tpcboxXT(0, 0, 2, 2, tstzspan '[2001-01-01, 2001-01-03]', 1)));
    -- 2
    
  • Restrict a tpcpatch to the points of each instant that the tpcbox holds, or remove them

    atTpcboxFine(tpcpatch,tpcbox,border_inc boolean=true) → tpcpatch
    minusTpcboxFine(tpcpatch,tpcbox,border_inc boolean=true) → tpcpatch
    

    Each surviving instant carries a freshly built pcpatch holding only the points inside, or outside for the minus form, the tpcbox in two dimensions, and in three when the box has a Z dimension. Instants whose patch filters to zero points are dropped, an instant outside the period of the box having no point in it, and a box without X dimension holds every point of an instant in its period. A tpcbox of another schema, reference system or kind of coordinate raises an error, as the operators of the boxes do. Slower than the coarse variant because every patch is decompressed and rebuilt; use when you need point-level fidelity.

    SELECT numInstants(atTpcboxFine(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3),
      pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)]),
      tpcboxXT(0, 0, 1, 1, tstzspan '[2001-01-01, 2001-01-03]', 1)));
    -- 1
    
  • Restrict a tpcpatch to the points whose XY projection intersects (or does not intersect, for minus) a 2D geometry

    atGeometry(tpcpatch,geometry) → tpcpatch
    minusGeometry(tpcpatch,geometry) → tpcpatch
    

    Z is ignored. SRID compatibility between the patch schema and the geometry must be ensured by the caller.

    -- The polygon boundary touches the point (3 3) of the patch at 2001-01-02, so that patch
    -- survives both the at and the minus side.
    SELECT numInstants(atGeometry(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]), geometry 'POLYGON((0 0, 0 3, 3 3, 3 0, 0 0))'));
    -- 2
    SELECT numInstants(minusGeometry(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]), geometry 'POLYGON((0 0, 0 3, 3 3, 3 0, 0 0))'));
    -- 1
    
  • Restrict a tpcpatch to the instants before or after a timestamp

    beforeTimestamp(tpcpatch,timestamptz,strict boolean=true) → tpcpatch
    afterTimestamp(tpcpatch,timestamptz,strict boolean=true) → tpcpatch
    

    The strict flag excludes the instant at the timestamp itself

    SELECT timeSpan(beforeTimestamp(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5)), '2001-01-03'::timestamptz)]),
      timestamptz '2001-01-02'));
    -- [2001-01-01, 2001-01-02)
    SELECT timeSpan(afterTimestamp(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5)), '2001-01-03'::timestamptz)]),
      timestamptz '2001-01-02'));
    -- (2001-01-02, 2001-01-03]
    

Splitting Operations

  • Return the distinct values of a tpcpatch with the span set on which each of them is taken

    unnest(tpcpatch) → {(value,time)}
    
    SELECT (un).time FROM (SELECT unnest(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)])) AS un) t;
    -- {[2024-01-02, 2024-01-03)}
    -- {[2024-01-01, 2024-01-02), [2024-01-03, 2024-01-03]}
    
  • Split a tpcpatch into fragments, one per time bin

    timeSplit(tpcpatch,duration interval,
      torigin timestamptz='2000-01-03',borderInc boolean=true) → {(time,tpcpatch)}
    

    The optional argument borderInc states whether the upper border of the extent is included and thus, the fragment starting at that border and holding only it is generated.

    SELECT (ts).time, numInstants((ts).temp) FROM (SELECT timeSplit(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)),
      '2024-01-03'::timestamptz)]),
      interval '1 day', '2024-01-01'::timestamptz) AS ts) t;
    -- 2024-01-01 | 2
    -- 2024-01-02 | 2
    -- 2024-01-03 | 1
    
  • Return the array of time spans of a tpcpatch's segments

    spans(tpcpatch) → tstzspan[]
    
    SELECT spans(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]));
    -- {"[2024-01-01, 2024-01-02]","[2024-01-02, 2024-01-03]"}
    
  • Return the array of point cloud boxes of the instants or segments of a tpcpatch

    tpcboxes(tpcpatch) → tpcbox[]
    
    SELECT tpcboxes(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]));
    -- {"TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-01, 2024-01-02]), 1)","TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-02, 2024-01-03]), 1)"}
    
  • Return the time spans of a tpcpatch split into a given number of bins, or with a given number of segments per bin

    splitNSpans(tpcpatch,integer) → tstzspan[]
    splitEachNSpans(tpcpatch,integer) → tstzspan[]
    
    SELECT splitNSpans(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]), 2);
    -- {"[2024-01-01, 2024-01-02]","[2024-01-02, 2024-01-03]"}
    
  • Return the time spans of a tpcpatch merged into a given number of spans, or until a span holds on average a given number of segments, each time the consecutive pair whose union adds the least size to theirs

    mergeNSpans(tpcpatch,integer) → tstzspan[]
    mergeEachNSpans(tpcpatch,integer) → tstzspan[]
    
    SELECT mergeNSpans(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]), 2);
    -- {"[2024-01-01, 2024-01-02]","[2024-01-02, 2024-01-03]"}
    
  • Return the point cloud boxes of a tpcpatch split into a given number of bins, or with a given number of instants or segments per bin

    splitNTpcboxes(tpcpatch,integer) → tpcbox[]
    splitEachNTpcboxes(tpcpatch,integer) → tpcbox[]
    
    SELECT splitNTpcboxes(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]), 2);
    -- {"TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-01, 2024-01-02]), 1)","TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-02, 2024-01-03]), 1)"}
    SELECT splitEachNTpcboxes(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]), 2);
    -- {"TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-01, 2024-01-03]), 1)"}
    
  • Return the point cloud boxes of a tpcpatch merged into a given number of boxes, or until a box holds on average a given number of instants or segments, each time the consecutive pair whose union adds the least size to theirs

    mergeNTpcboxes(tpcpatch,integer) → tpcbox[]
    mergeEachNTpcboxes(tpcpatch,integer) → tpcbox[]
    
    SELECT mergeNTpcboxes(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]), 2);
    /* {"TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-01, 2024-01-02]), 1)",
       "TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-02, 2024-01-03]), 1)"} */
    SELECT mergeEachNTpcboxes(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 5, 5, 5), pcpoint(1, 6, 6, 6)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-03'::timestamptz)]), 2);
    -- {"TPCBOX(ZT(((1,1,1),(6,6,6)),[2024-01-01, 2024-01-03]), 1)"}
    
  • Return the point cloud boxes or the time spans of a tpcpatch merged into those a query of the extents of a query box is expected to read least: the widths of the query box are the extents of a query, its position is not read, and a dimension it lacks restricts no query

    mergeQueryTpcboxes(tpcpatch,tpcbox) → tpcbox[]
    mergeQuerySpans(tpcpatch,tstzspan) → tstzspan[]
    
    SELECT mergeQueryTpcboxes(tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2024-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 2, 2, 2), pcpoint(1, 3, 3, 3)), '2024-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 9, 9, 9), pcpoint(1, 10, 10, 10)), '2024-01-03'::timestamptz)]),
      tpcbox(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2))));
    /* {"TPCBOX(ZT(((1,1,1),(3,3,3)),[2024-01-01, 2024-01-02]), 1)",
       "TPCBOX(ZT(((2,2,2),(10,10,10)),[2024-01-02, 2024-01-03]), 1)"} */
    

Spatial Operations

  • Return the swath of a temporal patch, the region of the plane its patches sweep

    swath(tpcpatch,maxt interval=NULL) → geometry
    

    The footprint of an instant is the convex hull of the positions of the points of its patch, read through the schema its pcid names and projected on the plane. The footprints of two consecutive instants are joined by the convex hull of both, and the swath is the union of these strips, together with the footprint of every instant joined to neither of its neighbours. Consecutive instants are joined unless they are more than maxt apart, so that a pause in the acquisition splits the swath; every gap is joined when maxt is not given. A patch is the set of points one acquisition captures, such as a ping of a multibeam echosounder, and the swath is then the strip of the seabed the pings of a survey line sound. Whereas the traversed area of the conversion to tgeometry is the soundings themselves, whose area is zero, the swath covers the seabed between them. The union is computed exactly.

    SELECT ST_AsText(swath(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 0, 0, 0), pcpoint(1, 1, 0, 0), pcpoint(1, 2, 0, 0)),
        '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 0, 1, 0), pcpoint(1, 1, 1, 0), pcpoint(1, 2, 1, 0)),
        '2001-01-02'::timestamptz)])));
    -- POLYGON((0 0,0 1,2 1,2 0,0 0))
    SELECT ST_NumGeometries(swath(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 0, 0, 0), pcpoint(1, 2, 0, 0)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 0, 1, 0), pcpoint(1, 2, 1, 0)), '2001-01-02'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 0, 5, 0), pcpoint(1, 2, 5, 0)), '2001-01-05'::timestamptz)]),
      interval '1 day'));
    -- 2
    

Bounding Box Operations

The same bbox operator surface as the section called “Bounding Box Operations” applies to tpcpatch. The predicate evaluates against the value's tpcbox, whose X and Y extent per instant is the patch's embedded PCBOUNDS and whose Z extent is the one the points of the patch state.

  • Topological operators

    {tstzspan,tpcbox,tpcpatch} {&&, @>, <@, ~=, -|-} {tstzspan,tpcbox,tpcpatch} → boolean
    
    SELECT tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)])
      && tstzspan '[2001-01-01, 2001-01-03]';
    -- true
    
  • Position operators

    {tpcbox,tpcpatch} {<<, >>, <<|, |>>, <</, />>} {tpcbox,tpcpatch} → boolean
    {tstzspan,tpcbox,tpcpatch} {<<#, #>>} {tstzspan,tpcbox,tpcpatch} → boolean
    
    SELECT tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)])
      <<# tstzspan '[2001-01-05, 2001-01-06]';
    -- true
    

Distance Operations

  • Return the smallest distance ever

    nearestApproachDistance(tpcpatch,{tpcbox,tpcpatch}) → float
    
    SELECT round(nearestApproachDistance(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 8, 8, 8), pcpoint(1, 9, 9, 9)),
      '2001-01-01'::timestamptz))::numeric, 4);
    -- 8.4853
    

Ever and Always Relationships

  • Return true iff at least one point in any of the tpcpatch's instants intersects the geometry (XY only)

    eIntersects(tpcpatch,geometry) → boolean
    

    A patch is a set of points, so it neither contains nor covers a geometry and two patches do not touch: eContains, eCovers and their always twins take the geometry first only, eTouches and aTouches read either order but not two patches, and eDisjoint, eIntersects, eDwithin and their always twins read the three argument orders. eIntersects(tpcpatch,geometry) is the one the type answers natively, walking the points of each instant and stopping at the first hit; the rest convert the patch to the temporal geometry of its multipoints.

    SELECT eIntersects(tpcpatchSeq(ARRAY[ tpcpatch(pcpatch(pcpoint(1, 1, 1, 1),
      pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3),
      pcpoint(1, 4, 4, 4)), '2001-01-02'::timestamptz)]), geometry 'POINT(1 1)');
    -- t
    

Spatiotemporal Relationships

The temporal relationships compute the topological or distance relationship at each instant and result in a tbool. A patch reaches the geometry engine through the tgeometry conversion above, so one point of a patch inside the argument is enough for the patch to intersect it. A tpcpatch carries the Z its schema declares, and tContains, tCovers and tTouches are planar relationships that refuse a Z dimension, so the type answers the three that a Z-carrying value can.

  • Temporal spatial relationships

    tDisjoint({geometry,tpcpatch},{geometry,tpcpatch}) → tbool
    tDwithin({geometry,tpcpatch},{geometry,tpcpatch},float) → tbool
    tIntersects({geometry,tpcpatch},{geometry,tpcpatch}) → tbool
    tContains(geometry,tpcpatch) → tbool
    tCovers(geometry,tpcpatch) → tbool
    tTouches(geometry,tpcpatch) → tbool
    tTouches(tpcpatch,geometry) → tbool
    

    A patch reaches the geometry engine as the multipoint of the positions its points occupy, and as a set of points it declares the matrix of a temporal point: tContains and tCovers take the geometry first only, tTouches reads either order but not two patches, and the others read the three argument orders. The planar ones answer for a schema whose dimensions do not include Z, and a schema carrying Z meets the refusal The tgeometry cannot have Z dimension.

    SELECT tIntersects(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 9, 9, 9)),
      '2001-01-01'::timestamptz), geometry 'Polygon((0 0,0 2,2 2,2 0,0 0))');
    -- t@2001-01-01
    SELECT tDisjoint(tpcpatch(pcpatch(pcpoint(1, 9, 9, 9)), '2001-01-02'::timestamptz),
      geometry 'Polygon((0 0,0 2,2 2,2 0,0 0))');
    -- t@2001-01-02
    SELECT tDwithin(tpcpatch(pcpatch(pcpoint(1, 1, 1, 1)), '2001-01-01'::timestamptz),
      geometry 'Point(1 5)', 2.0);
    -- f@2001-01-01
    SELECT tIntersects(tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 9, 9, 9)), '2001-01-02'::timestamptz)]),
      geometry 'Polygon((0 0,0 2,2 2,2 0,0 0))');
    -- [t@2001-01-01, f@2001-01-02]
    

Comparisons

  • Ever and always comparisons

    {pcpatch,tpcpatch} {?=, %=, ?<>, %<>} {pcpatch,tpcpatch} → boolean
    
    SELECT pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)) ?= tpcpatchSeq(ARRAY[
      tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)), '2001-01-01'::timestamptz),
      tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]);
    -- t
    SELECT tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)),
      '2001-01-01'::timestamptz), tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]) %= pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2));
    -- f
    
  • Ever and always overlaps

    tpcpatch {?&&, %&&} tpcbox → boolean
    tpcbox {?&&, %&&} tpcpatch → boolean
    

    Whether the patch of the value lies in a point cloud box at some instant, or at every instant at which it is defined, at the granularity of atTpcbox: the extent of a patch is compared with the box. A box of another schema or reference system raises an error, as the operators of the boxes do.

    SELECT tpcpatch(PC_Patch(ARRAY[PC_MakePoint(1, ARRAY[1.0, 1.0, 1.0]::float[]),
      PC_MakePoint(1, ARRAY[2.0, 2.0, 2.0]::float[])]), '2024-01-01'::timestamptz) ?&&
      tpcbox 'TPCBOX(XT(((0,0),(5,5)),[2024-01-01, 2024-01-02]), 1)';
    -- t
    SELECT tpcbox 'TPCBOX(XT(((3,3),(5,5)),[2024-01-01, 2024-01-02]), 1)' ?&&
      tpcpatch(PC_Patch(ARRAY[PC_MakePoint(1, ARRAY[1.0, 1.0, 1.0]::float[]),
      PC_MakePoint(1, ARRAY[2.0, 2.0, 2.0]::float[])]), '2024-01-01'::timestamptz);
    -- f
    
  • Temporal comparisons

    {pcpatch,tpcpatch} {#=, #<>} {pcpatch,tpcpatch} → tbool
    
    SELECT tpcpatchSeq(ARRAY[tpcpatch(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2)),
      '2001-01-01'::timestamptz), tpcpatch(pcpatch(pcpoint(1, 3, 3, 3), pcpoint(1, 4, 4, 4)),
      '2001-01-02'::timestamptz)]) #= pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2));
    -- [t@2001-01-01, f@2001-01-02]