Static Point Clouds

The static types come from pgPointCloud. MobilityDB exposes the schema-aware coordinate accessors needed to project pgPointCloud values into the rest of the temporal-types ecosystem.

Input and Output

The text of a pcpoint and of a pcpatch is the hex of its pgPointCloud Well-Known Binary (WKB), the text the type input and output functions of pgPointCloud read and write, and every engine reads and writes it with the functions below.

  • Return the Well-Known Binary (WKB) or the Hexadecimal Well-Known Binary (HexWKB) representation of a pcpoint or a pcpatch

    asBinary({pcpoint,pcpatch},endian text='') → bytea
    asHexWKB({pcpoint,pcpatch},endian text='') → text
    

    The WKB is the one of pgPointCloud: the endian flag, the pcid and the data under the schema of the pcid, which for a pcpatch are the compression, the number of points and the points or, dimensionally compressed, the bytes of each dimension in its own compression. 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, and the HexWKB is the text the type output function of pgPointCloud writes. The big-endian encoding of a dimensionally compressed pcpatch keeps the compression of each dimension. A set and a temporal value carry the WKB of each of their pcpoints or pcpatches, preceded by its size, in their own encoding.

    SELECT asBinary(pcpoint(1, 1.0, 2.0, 3.0));
    -- \x010100000064000000c80000002c010000
    SELECT asHexWKB(pcpoint(1, 1.0, 2.0, 3.0));
    -- 010100000064000000C80000002C010000
    SELECT asHexWKB(pcpoint(1, 1.0, 2.0, 3.0), 'XDR');
    -- 000000000100000064000000C80000012C
    SELECT asHexWKB(pcpatch(pcpoint(1, 1.0, 1.0, 1.0), pcpoint(1, 2.0, 2.0, 2.0)));
    -- 01010000000000000002000000640000006400000064000000C8000000C8000000C8000000
    SELECT asHexWKB(pcpatch(pcpoint(1, 1.0, 1.0, 1.0), pcpoint(1, 2.0, 2.0, 2.0)), 'XDR');
    -- 00000000010000000000000002000000640000006400000064000000C8000000C8000000C8
    
  • Input of a pcpoint or a pcpatch from its Well-Known Binary (WKB) or its Hexadecimal Well-Known Binary (HexWKB) representation

    pcpointFromBinary(bytea) → pcpoint
    pcpatchFromBinary(bytea) → pcpatch
    pcpointFromHexWKB(text) → pcpoint
    pcpatchFromHexWKB(text) → pcpatch
    

    The input is read as the type input function of pgPointCloud reads it, in either byte order, under the schema of its pcid.

    SELECT getZ(pcpointFromBinary('\x000000000100000064000000c80000012c'));
    -- 3
    SELECT numPoints(pcpatchFromBinary(
      '\x00000000010000000000000002000000640000006400000064000000c8000000c8000000c8'));
    -- 2
    SELECT getZ(pcpointFromHexWKB('010100000064000000C80000002C010000'));
    -- 3
    SELECT numPoints(pcpatchFromHexWKB('01010000000000000002000000640000006400000064000000C8000000C8000000C8000000'));
    -- 2
    

Constructors

pgPointCloud's pcpoint_in only accepts hex-WKB, so the canonical builder is PC_MakePoint(pcid, ARRAY[…]::float[]). MobilityDB ships two thin SQL overloads on top of it for shorter test literals and ad-hoc queries; the underlying schema-dimension validation still happens inside PC_MakePoint.

  • Build a 2D or 3D pcpoint directly from x/y(/z) coordinates

    pcpoint(pcid integer,x float,y float) → pcpoint
    pcpoint(pcid integer,x float,y float,z float) → pcpoint
    
    SELECT pcpoint(1, 10.0, 20.0, 30.0);
    -- Equivalent to pcpoint(1, 10.0, 20.0, 30.0)
    
  • Build a pcpoint from the coordinates of every dimension of the schema

    pcpoint(pcid integer,coordinates float[]) → pcpoint
    

    The layout of the schema states every dimension, inactive ones included, which is how a schema of more dimensions than the overloads above reach is given its values. That count is the one PC_MakePoint takes and is NOT the count of active dimensions that pointCloudSchemaNDims reports

    SELECT pcpoint(1, ARRAY[10.0, 20.0, 30.0]::float[]);
    
  • Build a pcpatch from the coordinates of its points, one point after another

    pcpatch(pcid integer,coordinates float[]) → pcpatch
    

    Every dimension of the layout of the schema is given for each point, inactive ones included. That count is the one PC_MakePatch takes and is NOT the count of active dimensions that pointCloudSchemaNDims reports; a count that divides evenly by the wrong one of the two builds a patch of the wrong points rather than reporting an error. A patch built this way states the schema itself, there being no point to read it from

    SELECT pcpatch(1, ARRAY[1.0, 1.0, 1.0, 2.0, 2.0, 2.0]::float[]);
    
  • Build a pcpatch from a variadic list of pcpoints sharing the same pcid

    pcpatch(VARIADIC points pcpoint[]) → pcpatch
    
    SELECT pcpatch(pcpoint(1, 1.0, 1.0, 1.0), pcpoint(1, 2.0, 2.0, 2.0));
    -- Equivalent to pcpatch(pcpoint(1, 1.0, 1.0, 1.0), pcpoint(1, 2.0, 2.0, 2.0))
    

Accessors

  • Return the schema id of a pcpoint or pcpatch

    pcid({pcpoint,pcpatch}) → integer
    
    SELECT pcid(pcpoint(1, 10.0, 20.0, 30.0));
    -- 1
    
  • Return a coordinate of a pcpoint, NULL if the dimension is absent from the schema

    getX(pcpoint) → float
    getY(pcpoint) → float
    getZ(pcpoint) → float
    
    WITH pt AS (SELECT pcpoint(1, 10.0, 20.0, 30.0) p)
      SELECT getX(p), getY(p), getZ(p) FROM pt;
    -- 10 | 20 | 30
    
  • Return any named dimension of a pcpoint

    getDim(pcpoint,text) → float
    

    The name is read without regard to case, and a name the schema of the point does not state raises an error, as pgPointCloud's PC_Get raises it.

    SELECT getDim(pcpoint(1, 10.0, 20.0, 30.0), 'X');
    -- 10
    
  • Return the spatial reference identifier (inherited from the schema)

    SRID({pcpoint,pcpatch}) → integer
    
    SELECT SRID(pcpoint(1, 10.0, 20.0, 30.0));
    -- 0
    SELECT SRID(pcpatch(pcpoint(1, 10.0, 20.0, 30.0), pcpoint(1, 11.0, 21.0, 31.0)));
    -- 0
    
  • Transform to the schema of another pcid

    transform({pcpoint,pcpatch,pcpointset,pcpatchset},pcid integer) →
      {pcpoint,pcpatch,pcpointset,pcpatchset}
    

    A point cloud value takes its SRID from the schema its pcid names, so it is transformed into the schema of another pcid, which states the target SRID and how the transformed coordinates are stored. The X, Y and Z dimensions are reprojected from the SRID of the source schema to the SRID of the target schema; the other dimensions are matched by name, and a dimension of the target schema that the source schema lacks takes 0, as in the PC_Transform function of pgPointCloud. When both schemas state the same SRID, the coordinates are only stored again under the target schema. A patch and a set transform each of their points.

    An error is raised when the target pcid names no schema, when either schema states no SRID, and when a transformed coordinate does not fit its dimension in the target schema at its scale and offset, rather than being clamped into it.

    -- pcid 101 names a schema in SRID 4326 with X, Y and Z, and pcid 102 a schema
    -- in SRID 3857 with X, Y, Z and Intensity
    WITH p AS (SELECT transform(pcpoint(101, 4.35, 50.85, 10), 102) AS p)
    SELECT round(getX(p)::numeric, 3), round(getY(p)::numeric, 3), getZ(p),
      getDim(p, 'Intensity'), pcid(p), SRID(p) FROM p;
    -- 484239.785 | 6594803.227 | 10 | 0 | 102 | 3857
    SELECT ST_AsText(geometry(transform(pcpatch(pcpoint(101, 4.35, 50.85, 10),
      pcpoint(101, 3.72, 51.05, 5)), 102)), 3);
    -- MULTIPOINT Z ((484239.785 6594803.227 10),(414108.506 6630142.914 5))
    
  • Return the number of points of a pcpatch

    numPoints(pcpatch) → integer
    
    SELECT numPoints(pcpatch(pcpoint(1, 1.0, 1.0, 1.0), pcpoint(1, 2.0, 2.0, 2.0)));
    -- 2
    
  • Return the n-th point of a pcpatch

    pointN(pcpatch,integer) → pcpoint
    

    Points are numbered from one, a negative integer counts from the end of the patch, and an integer addressing no point returns NULL.

    SELECT pointN(pcpatch(pcpoint(1, 1.0, 1.0, 1.0), pcpoint(1, 2.0, 2.0, 2.0)), 2)
      = pcpoint(1, 2.0, 2.0, 2.0);
    -- true
    SELECT pointN(pcpatch(pcpoint(1, 1.0, 1.0, 1.0), pcpoint(1, 2.0, 2.0, 2.0)), 3)
      IS NULL;
    -- true
    
  • Return the multipoint of the positions the points of a patch occupy

    geometry(pcpatch) → geometry
    geography(pcpatch) → geography
    

    The schema the pcid names decides the SRID and whether the result carries a Z dimension

    SELECT ST_AsText(geometry(pcpatch(pcpoint(1, 1, 1, 1), pcpoint(1, 2, 2, 2))));
    -- MULTIPOINT Z ((1 1 1),(2 2 2))