Overlays two topologies.
int
tpm_anaoverlay(
ade_id overlay_id,
struct resbuf *overlay_data,
ade_id source_id,
struct resbuf *source_data,
int oper,
ade_id var_id,
char *obj-table,
char *obj_tabledesc,
char *result_name,
char *result_desc);
Returns RTNORM or an error code
| overlay_id | Overlay topology ID of topology 1. Must be a polygon topology. |
| overlay_data | Overlay data expression composed of AutoCAD Map expressions and output object data columns or nil. See the Overlay Data Expressions section below. |
| source_id | Source topology ID of topology 2. Must be a polygon topology. |
| source_data | Overlay data expression composed of AutoCAD Map expressions and output object data columns or nil. See the Overlay Data Expressions section below. |
| oper | Overlay operation. See the Overlay Operations table below. |
| var_id | ID of topology variables for building the result topology. |
| obj_table | Name of the new object data table that will contain the final data (created by the function). Cannot be an existing table. |
| obj_tabledesc | Object data table description. |
| result_name | Result topology name. Omit if function results produces AutoCAD objects instead of a topology. |
| result_desc | Result topology description. |
| overlay_data | Pointer to result buffer of overlay attributes. |
| source_data | Pointer to result buffer of source attributes. |
See the Visual LISP description of tpm_anaoverlay for information about the list elements in the expr1 resbuf.
If the result_name argument is NULL, the result is a collection of AutoCAD objects. Otherwise it is a new topology that is loaded but not open. The last four parameters have the same mutual dependencies in the ADSRX function as they do in the Visual LISP equivalent, except that you cannot omit any of them. You must use NULL.
The source topology must be of polygon type for union and paste operations. For all other operations, it can be of any topology type, such as node, network, and polygon.
The topology variables ID references a set of topology variables.
Overlay Data Expressions
The overlay_data and source_data arguments are resbufs that are constructed as follows:
struct resbuf *list1;
list1 = acutBuildList(
RTLB
RTSTR expr1
RTSTR colname1
RTSTR coldsc1
RTSHORT coltype1
RTLE
RTLB
RTSTR expr2
. . .
RTLE
. . .
0);
Overlay Data Expression Arguments
| expr1 | AutoCAD Map expression (RTSTR). |
| col_name1 | Object data column name (RTSTR). |
| col_desc1 | Object data column description (RTSTR). |
| col_type1 | Object data column type (RTSHORT): 1 through 4, where 1 = integer, 2 = real, 3 = character, and 4 = point. |
| 1 | Intersect |
| 2 | Union |
| 3 | Identity |
| 4 | Erase |
| 5 | Clip |
| 6 | Paste |
Result Topology
If the result_name argument is omitted or nil, the result is a collection of AutoCAD objects. Otherwise, it is a new topology that is loaded but not open.
You must specify the list of data values to come from each input topology and the specific data for each.
Additionally, you must specify the name of the result object data table in the objTable parameter to contain the final data. If you do not specify a result table, no data is attached to the resulting topology elements. The function creates this table. If the result table you specify already exists, the function returns an error and cancels the overlay process.
Data derived by the overlay process is also attached to the result object data table. This data is written for each topology element in the resulting topology. It is written for each polygon if the source is a polygon topology, for each link if it is a network topology, or for each node if it is a node topology. The table always includes the following fields:
| TOPO_ID | Element ID of the new element in the result topology |
| T1_ID | Element ID of the parent polygon in the overlay topology |
| T1_PERCENTAREA | Area of the new polygon in the result topology compared to the area of the parent polygon in the overlay topology. Written only if both overlay and result are polygon topologies |
| T2_ID | Element ID of parent element in the source topology. The parent element can be a node, link, or polygon. |
| T2_PERCENTAREA | Area of the new polygon in the resulting topology compared to the area of the parent polygon in the source topology. Written only if both source and result are polygon topologies |
The result table includes these fields along with the fields that you specify in the arguments you supply for the overlay_data and source_data parameters. Each field name is prefixed with T1_ or T2_ to indicate which topology its data comes from.
For example, if you specify FIELD1, FIELD2 and FIELD3 from table SOIL for the first topology and FIELD1, FIELD4 and FIELD5 from table WATER for the second, the result table has the following fields:
T1_SOIL_FIELD1 T1_SOIL_FIELD2 T1_SOIL_FIELD3 T1_WATER_FIELD1 T1_WATER_FIELD4 T1_WATER_FIELD5
The following sample overlays two polygon topologies which are opened and loaded using tpm_acload() and tpm_acopen() respectively. A resbuf is created which contains data expressions associated with object data attached to the source topology. tpm_anaoverlay() is called with all required parameters. The resulting topology and object data table contains information about the percentage of the source polygons consumed by the overlay, (buffer topology), the median household income and the population density per square mile among others. The input topologies are closed and then unloaded using tpm_acclose() and tpm_acunload() respectively. The resbufs are then released as required.
char* pszOverlayTopoName = "I-95_Buffer";
int topoWriteAccess = 0;
int returnCode = tpm_acload(pszOverlayTopoName, 0);
ade_id topoForOverlayId = tpm_acopen(pszOverlayTopoName, topoWriteAccess);
struct resbuf* pOverlayDataRb = NULL;
char* pszSourceTopoName = "blkgrp";
returnCode = tpm_acload(pszSourceTopoName, 0);
ade_id sourceTopoId = tpm_acopen(pszSourceTopoName, topoWriteAccess);
struct resbuf* pSourceDataRb = acutBuildList(
RTLB,
RTSTR, ":MEDIAN_VAL@RIBLKGRP", // Data Extension expression
RTSTR, "MEDIAN_VAL", // Object data column name
RTSTR, "", // Object data column description
RTSHORT, 2, // Object data column type
RTLE,
RTLB,
RTSTR, ":POP90_SQMI@RIBLKGRP",
RTSTR, "POP90_SQMI",
RTSTR, "",
RTSHORT, 1,
RTLE,
0);
int overlayOperation = 1;
ade_id topoConfigVarId = tpm_varalloc();
char* pszODTable = "BufferOverlayBlkGrp";
char* pszODTableDesc = "BufferOverlayBlkGrp-Desc";
char* pszResultTopoName = "BuffrOverBlkGrp";
char* pszResultTopoDesc = "BuffrOverBlkGrp-Desc";
returnCode = tpm_anaoverlay(
topoForOverlayId,
pOverlayDataRb,
sourceTopoId,
pSourceDataRb,
overlayOperation,
topoConfigVarId,
pszODTable,
pszODTableDesc,
pszResultTopoName,
pszResultTopoDesc
);
if (RTNORM == returnCode){
acutPrintf(
"\nThe overlay operation was successfully completed.");
}
else {
acutPrintf(
"\nThe overlay operation could not be performed.");
}
tpm_acclose(topoForOverlayId);
tpm_acunload(pszOverlayTopoName);
tpm_acclose(sourceTopoId);
tpm_acunload(pszSourceTopoName);
acutRelRb(pOverlayDataRb);
acutRelRb(pSourceDataRb);