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.
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.
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
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)
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)
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
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
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]
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)"} */
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
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
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
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
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]
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]