28 SDO_PC_PKG Package (Point Clouds)

This chapter contains descriptions of the point cloud subprograms shown in Table 28-1.

Table 28-1 Point Cloud Subprograms

Subprogram	Description
SDO_PC_PKG.CLIP_PC	Performs a clip operation on a point cloud.
SDO_PC_PKG.CREATE_PC	Creates a point cloud using the points specified in the `inptable` parameter.
SDO_PC_PKG.DROP_DEPENDENCIES	Drops the dependencies between a point cloud block table and a specified base table and column.
SDO_PC_PKG.INIT	Initializes a point cloud.
SDO_PC_PKG.TO_GEOMETRY	Returns a geometry object representing all or part of a point cloud.

To use the subprograms in this package, you must understand the main concepts related to three-dimensional geometries, including the use of point clouds to model solids. Section 1.11 describes support for three-dimensional geometries, Section 1.11.2 describes the use of p[oint clouds to model solids, and Section 2.6 describes data types related to point clouds.

SDO_PC_PKG.CLIP_PC

Format

SDO_PC_PKG.CLIP_PC(

inp IN SDO_PC,

ind_dimqry IN SDO_GEOMETRY,

other_dimqry IN SDO_MBR,

qry_min_res IN NUMBER,

qry_max_res IN NUMBER,

blkno IN NUMBER DEFAULT NULL

) RETURN SDO_PC_BLK_TYPE;

Description

Performs a clip operation on a point cloud.

Parameters

inp

Point cloud on which to perform the clip operation.

ind_dimqry

For querying the indexed dimensions of the point cloud: window from which to select objects to be returned; typically a polygon for two-dimensional geometries or a frustum for three-dimensional geometries.

other_dimqry

For querying the nonindexed dimensions of the point cloud: window from which to select objects to be returned; typically a polygon for two-dimensional geometries or a frustum for three-dimensional geometries. The nonindexed dimensions are those that are included in the total dimensionality but are not indexed. For an explanation of index dimensionality and total dimensionality, see the explanation of the pc_tot_dimensions parameter of the SDO_PC_PKG.INIT function.

The SDO_MBR type is defined as (LOWER_LEFT SDO_VPOINT_TYPE, UPPER_RIGHT SDO_VPOINT_TYPE) and SDO_V_POINT_TYPE is defined as VARRAY(64) OF NUMBER.

qry_min_res

Minimum resolution value. Objects in qry with resolutions equal to or greater than qry_min_res and less than or equal to qry_max_res are returned by the clip operation.

qry_max_res

Maximum resolution value. Objects in qry with resolutions equal to or greater than qry_min_res and less than or equal to qry_max_res are returned by the clip operation.

blkid

Block ID number of the block to which to restrict the objects returned by the clip operation. If this parameter is null, all objects that satisfy the other parameters are returned.

Usage Notes

This function returns points from a point cloud that are within a specified query window and that satisfy any other requirements specified by the parameters. A common use of this function is to perform queries on point clouds. You can maximize the performance of a point cloud query by minimizing the number of objects that the function needs to consider for the operation.

The SDO_PC and SDO_PC_BLK_TYPE data types are described in Section 2.6.

Section 1.11.2 describes how to use point clouds to model solids.

Examples

The following example performs a clip operation on a point cloud. It is taken from the sdo_pc.sql example program, which is under $ORACLE_HOME/md/demo/examples/PointCloud/plsql/ if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).

. . .
declare
  inp  sdo_pc;
begin
  select pc INTO inp  from base where rownum=1;
  insert into restst
    select * from
      table(sdo_pc_pkg.clip_pc
           (
            inp,  -- Input point cloud object
            sdo_geometry(2003, 8307, null,
              sdo_elem_info_array(1, 1003, 3),
              sdo_ordinate_array(-175.86157, -14.60521, 0,0)), -- Query 
              null, null, null));
end;
/
. . .

SDO_PC_PKG.CREATE_PC

Format

SDO_PC_PKG.CREATE_PC(

inp IN SDO_PC,

inptable IN VARCHAR2,

clstPcdataTbl IN VARCHAR2 DEFAULT NULL);

Description

Creates a point cloud using the points specified in the inptable parameter.

Parameters

inp

SDO_PC object to be used. This object must have been created by the SDO_PC_PKG.INIT function.

inptable

Name of the table or view containing the input point cloud data. This table or view should have the following columns:

RID (VARCHAR2(24)): Unique ID for each point
VAL_D1 (NUMBER): Ordinate in dimension 1
VAL_D2 (NUMBER): Ordinate in dimension 2
. . .
VAL_Dn (NUMBER): Ordinate in dimension n, where n is the highest-numbered dimension. n should match the pc_tot_dimensions parameter value in the call to the SDO_PC_PKG.INIT function when the point cloud was initialized.

clstPcdataTbl

Name of the table for storing the resulting point data. If you do not specify a value, this table is not created. For more information about the table, see the Usage Notes.

Usage Notes

The first few dimensions of the point cloud are indexed and can later be searched using the SDO_PC_PKG.CLIP_PC function. The exact number of dimensions to index is determined by the dimensionality of the point cloud extent in the initialized point cloud object, specifically: inp.pc_extent.sdo_gtype/1000

If you specify a view name in the inptable parameter, the query SELECT ROWID FROM <view-name> must not return any errors.

If you specify a table name in the clstPcdataTbl parameter, the table must exist and have the following columns:

PTN_ID (NUMBER)
POINT_ID (NUMBER)
RID (VARCHAR2(24): Unique ID for each point
VAL_D1 (NUMBER): Ordinate in dimension 1
VAL_D2 (NUMBER): Ordinate in dimension 2
. . .
VAL_Dn (NUMBER): Ordinate in dimension n, where n is the highest-numbered dimension. n should match the pc_tot_dimensions parameter value in the call to the SDO_PC_PKG.INIT function when the point cloud was initialized.

If a value is specified for the clstPcdataTbl parameter, this function populates the table by assigning appropriate values for PTN_ID and POINT_ID and by copying the values from the inptable table or view for other attributes. This table can be created as an index organized table. It can be used in applications for searching using SQL queries on dimensions other than those reflected in the index dimensionality. (For an explanation of index dimensionality and total dimensionality, see the explanation of the pc_tot_dimensions parameter of the SDO_PC_PKG.INIT function.)

The SDO_PC and SDO_PC_BLK_TYPE data types are described in Section 2.6.

Section 1.11.2 describes how to use point clouds to model solids.

Examples

The following example creates a point cloud. It is taken from the sdo_pc.sql example program, which is under $ORACLE_HOME/md/demo/examples/PointCloud/plsql/ if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).

. . .
-- Create the blocks for the point cloud.
sdo_pc_pkg.create_pc(
  pc,       -- Initialized PointCloud object
  'INPTAB', -- Name of input table to ingest into the pointcloud
  'RES'     -- Name of output table that stores the points (with ptn_id,pt_id)
  );
. . .

SDO_PC_PKG.DROP_DEPENDENCIES

Format

SDO_PC_PKG.DROP_DEPENDENCIES(

basetable IN VARCHAR2,

col IN VARCHAR2);

Description

Drops the dependencies between a point cloud block table and a specified base table and column.

Parameters

basetable: Name of a base table that was specified (in the basetable parameter of the SDO_PC_PKG.INIT function) when the point cloud was initialized.
col: Name of a column in base table that was specified in the basecol parameter of the SDO_PC_PKG.INIT function.

Usage Notes

This procedure truncates the point cloud block table and removes the association between the block table and the base table and column combination.

After you execute this procedure, you can drop the point cloud block table or associate the table with another base table and column combination. For more information, see the Usage Notes for the SDO_PC_PKG.INIT function.

Examples

The following example drops the dependencies between a point cloud block table and a base table and column named BASE and PC, respectively.

. . .
declare
begin
  mdsys.sdo_pc_pkg.drop_dependencies('BASE', 'PC');
end;
/

SDO_PC_PKG.GET_PT_IDS

Format

SDO_PC_PKG.GET_PT_IDS(

pts IN BLOB,

num_pts IN NUMBER,

pc_tot_dim IN NUMBER,

blk_domain IN SDO_ORGSCL_TYPE DEFAULT NULL,

) RETURN SDO_NUMBER_ARRAY;

Description

Returns the block ID and point ID values of the points in a block in a point cloud.

Parameters

pts: Binary large object (BLOB) containing the point cloud block.
num_pts: Number of points in the point cloud block. For a point cloud block, the number of points is stored in the NUM_POINTS column of the point cloud block table, which is described in Table 2-7 in Section 2.6.1.
pc_tot_dim: Number of dimensions for the points in the point cloud block.
blk_domain: (Not currently used.)

Usage Notes

This function returns an SDO_NUMBER_ARRAY object. The array contains multiple pairs of numbers, with each pair identifying the block ID and point ID of a point. For any specific call to this function, the block ID values associated with all points in the returned array will be the same. The SDO_NUMBER_ARRAY type is defined as VARRAY(1048576) OF NUMBER.

Section 1.11.2 describes how to use point clouds to model solids.

Examples

The following example returns the block ID and point ID values of points in a point cloud block. It is taken from the sdo_pc.sql example program, which is under $ORACLE_HOME/md/demo/examples/PointCloud/plsql/ if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).

SELECT SDO_PC_PKG.GET_PT_IDS(
    a.points,   -- LOB containing the points
    a.num_points, -- # of points in the LOB
    3 -- Total dimensionality of the points in the LOB
) FROM restst a WHERE num_points >0;

SDO_PC_PKG.INIT

Format

SDO_PC_PKG.INIT(

basetable IN VARCHAR2,

basecol IN VARCHAR2,

blktable IN VARCHAR2,

ptn_params IN VARCHAR2,

pc_extent IN VARCHAR2,

pc_tol IN NUMBER DEFAULT 0.0000000000005,

pc_tot_dimensions IN NUMBER DEFAULT 2,

pc_domain IN SDO_ORGSCL_TYPE DEFAULT NULL,

pc_val_attr_tables IN SDO_STRING_ARRAY DEFAULT NULL,

pc_other_attrs IN XMLTYPE DEFAULT NULL,

) RETURN SDO_PC;

Description

Initializes a point cloud by creating an SDO_PC object.

Parameters

basetable

Name of the base table containing a column of type SDO_PC.

basecol

Name of the column of type SDO_PC in the base table.

blktable

Name of the point cloud block table, which is used for storing the blocks of point cloud. This table must exist, and must have been created by a statement in the following form: CREATE TABLE <table-name> AS select * from mdsys.sdo_pc_blk_table;

Each point cloud block table can only be associated with only one basetable and basecol combination.

ptn_params

Parameters for partitioning the point cloud, specified as a quoted string with keywords delimited by commas. For example: 'blk_capacity=1000,work_tablespace=my_work_ts'. If this parameter is null, the point cloud is not partitioned. The following keywords are permitted:

blk_capacity=n, where n is the maximum number of rows in each partition. The default value is 5000. If specified, must be a number greater than or equal to 50.
work_tablespace=x, where x is the name of the tablespace in which to create temporary tables during the partitioning operations.

pc_extent

SDO_GEOMETRY object representing the spatial extent of the point cloud (the minimum bounding object enclosing all objects in the point cloud). This parameter must not be null.

For geodetic data, this geometry must have two dimensions; otherwise, it can have up to four dimensions. The dimensionality of this geometry is used as the minimum value permitted for the pc_tot_dimensions parameter, as explained in the description of that parameter.

pc_tol

Tolerance value for objects in the point cloud. (For information about spatial tolerance, see Section 1.5.5.) If this parameter is null, the default value is 0.0000000000005.

pc_tot_dimensions

A number specifying the total dimensionality of the point cloud object. For each point in the point cloud blocks, pc_tot_dimensions ordinates (values) are stored.

The total dimensionality must be greater than or equal to the index dimensionality, which is the number of dimensions in the pc_extent geometry. Specifying total dimensionality greater than index dimensionality enables necessary nonspatial attributes to be retrieved in the same fetch operation with spatial data. The maximum total dimensionality value is 8. The default value for this parameter is 2.

pc_domain

(Not currently used.)

pc_val_attr_tables

SDO_STRING_ARRAY object specifying the names of any value attribute tables for the point cloud. If this parameter is null, the point cloud has no associated value attribute tables. Type SDO_STRING_ARRAY is defined as VARRAY(1048576) OF VARCHAR2(32).

pc_other_attrs

XMLTYPE object specifying any other attributes of the point cloud. If this parameter is null, the point cloud has no other attributes.

Usage Notes

After you use this function to create an SDO_PC object, you can create a point cloud by specifying this object as input to the SDO_PC_PKG.CREATE_PC procedure.

The SDO_PC data type is described in Section 2.5.

Section 1.11.2 describes how to use point clouds to model solids.

After you use this function, the blktable table is kept in synchronization with the base table. For example, if a row is deleted from the basetable, the corresponding blocks of the point cloud object in that row are also deleted from the block table; and if the base table base table is truncated, the block table is truncated also.

The block table can be dropped only after either of the following occurs: the base table is dropped, or the SDO_PC_PKG.DROP_DEPENDENCIES procedure is executed.

Examples

The following example initializes a point cloud by creating an SDO_PC object, and it displays the ID of the object. It is taken from the sdo_pc.sql example program, which is under $ORACLE_HOME/md/demo/examples/PointCloud/plsql/ if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide)a.

. . .
declare
  pc sdo_pc;
begin
  -- Initialize the point cloud object. 
  pc := sdo_pc_pkg.init(
          'BASE', -- Table that has the SDO_POINT_CLOUD column defined
          'PC',   -- Column name of the SDO_POINT_CLOUD object 
          'BLKTAB', -- Table to store blocks of the point cloud
          'blk_capacity=1000', -- max # of points per block 
          mdsys.sdo_geometry(2003, 8307, null,
              mdsys.sdo_elem_info_array(1,1003,3),
              mdsys.sdo_ordinate_array(-180, -90, 180, 90)),  -- Extent 
              0.5, -- Tolerance for point cloud
              3, -- Total number of dimensions
              null);
. . .

SDO_PC_PKG.TO_GEOMETRY

Format

SDO_PC_PKG.TO_GEOMETRY(

pts IN BLOB,

num_pts IN NUMBER,

tin_tot_dim IN NUMBER,

srid IN NUMBER DEFAULT NULL,

blk_domain IN SDO_ORGSCL_TYPE DEFAULT NULL

) RETURN SDO_GEOMETRY;

Description

Returns a geometry object representing all or part of a point cloud.

Parameters

pts: BLOB containing the points.
num_pts: Maximum number of points to be included in the resulting geometry.
tin_tot_dim: Number of spatial dimensions defined for the data.
srid: Spatial reference (coordinate system) ID associated with the data. If this parameter is null, no SRID value is associated with the data.
blk_domain: (Not currently used.)

Usage Notes

This function returns a single multipoint SDO_GEOMETRY object that represents all point geometries in the pts parameter. For example, the points could reflect the result of a clip operation or the contents of an entire block.

Section 1.11.2 describes how to use point clouds to model solids.

Examples

The following example returns a multipoint collection geometry object representing a point cloud. It is taken from the sdo_pc.sql example program, which is under $ORACLE_HOME/md/demo/examples/PointCloud/plsql/ if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).

. . .
-- Return points in blk_id of the point cloud as a multipoint collection.
select sdo_pc_pkg.to_geometry(
                    a.points,   -- point LOB
                    a.num_points, -- # of points in the LOB
                    3,  -- total dimensionality
                    8307 -- SRID
                    ) from blktab a where blk_id=0;
. . .