VDISSOLVE

Description

Combines shapes by dissolving boundaries between vector shapes in the input segment. Typically, shapes are aggregated based on a specified attribute; for example, the input may contain U.S.A. county polygons which could be dissolved based on their StateID attribute to produce a U.S.A. states segment.

Parameters

vdissolve (fili, dbiv, attrlist, attrfunc, dissopt, filo, ftype, foptions)

Name	Type	Caption	Length	Value range
FILI *	PCI_FILE	Input file name	1 -
DBIV	List[int]	Input vector segment	0 - 1
ATTRLIST	str	Attribute name list	0 -
ATTRFUNC	str	Attribute function list	0 -
DISSOPT	str	Dissolve option	0 - 8
FILO *	str	Output file name	1 -
FTYPE	str	Output file type	0 -	Default: PIX
FOPTIONS	str	Output file options	0 -

* Required parameter

Parameter descriptions

FILI

Specifies the name of the GDB-supported file that contains the vector segment to process.

DBIV

Optionally specifies the input vector segment from FILI to process. If this parameter is not specified, the function automatically uses the first vector segment in the input file.

Most often, VDISSOLVE is performed on vector polygon segments to remove boundaries between polygons. This function can also be used to dissolve lines, in which case pseudo nodes can be removed. Points may also be processed, provided the dissolve options (DISSOPT) parameter is set to ALL, to create multi-part points.

ATTRLIST

Optionally specifies a list of fields that exist within the input vector segment.

For two shapes to be dissolved, all the fields specified in this list must have the same attribute value. If no fields are specified, the dissolving action will not be based on the attribute values at all.

Fields are specified as a comma-separated list of field names. Each field specified will also be part of the output segment.

ATTRFUNC

Optionally specifies a list of functions and the names of the fields to be aggregated.

When shapes are dissolved, this parameter specifies how to handle the existing attributes that you want transferred to the output segment. Fields specified in ATTRLIST should not be included in ATTRFUNC.

Functions are specified as a comma-separated list of one of the supported functions along with the name of the field on which to operate; for example, SUM(<numeric_field), MEAN(<numeric_field).

Supported functions are:

FIRST(<any_field>): returns the first (lowest ShapeID) value of the group
LAST(<any_field>): returns the last (highest ShapeID) value of the group
SUM(<numeric_field>): returns the additive sum of the group
MEAN(<numeric_field>): returns the mean value of the group
MIN(<numeric_field>): returns the minimum value of the group
MAX(<numeric_field>): returns the maximum value of the group
MODE(<any_field>): returns the most frequently occurring value in the group
MEDIAN(<numeric_field>): returns the median value of the group
STDDEV(<numeric_field>): returns the standard deviation value of the group
COUNT: returns the cardinality of the group

DISSOPT

Optionally specifies the dissolve options that control which shapes should be merged, based on the shape geometries. Shapes must meet the field requirements as specified in the Attribute Name List (ATTRLIST).

Available dissolve options are:

ADJACENT: (default) Only shapes that are actually adjacent to each other (touching) are dissolved
ALL: all shapes, regardless of their geometrics, are dissolved. When dissolving points, this is the only available option.

FILO

Specifies the name of the output file to receive the processed vector data.

If the specified file does not already exist, a new file is created using the the ouptut file type (FTYPE) and output file options (FOPTIONS) values. In this case, the output file will contain a single vector segment.

If the specified output file already exists, the specified file must be in a format that can be updated to accept the new vector segment. When writing to an existing file, do not specify the FTYPE and FOPTIONS parameters; otherwise, VDISSOLVE may error.

The input and output files may be the same, as long as FILI meets the criteria stated above.

FTYPE

Optionally specifies the output file format type, represented by a three- or four-letter code. The format type must be a GDB-recognized file type. If FILO specified an existing file, FTYPE should not be specified since that existing file will be updated and its type will not be changed.

Supported file format codes include, among others:

PIX: PCIDSK format (default)
SHP: Shapefile format
KML: Google Earth KML format

For a complete list of GDB-recognized file types and their codes, see GDB file formats in the Technical Reference section of the CATALYST Professional Online Help.

FOPTIONS

Optionally specifies the file creation options to be applied when creating the output file. These are specific to the file format; in each case, the default of no options is allowed. FOPTIONS can be used to specify the compression schemes, file format subtypes, and other information.

Different options are available for different file types (see the FTYPE parameter). The options are described in GDB file formats, in the Technical Reference section of the CATALYST Professional Online Help.

Return Value

Returns: New segment number

Type: PCI_INT

Parameter: LASC

This function returns the number of the newly created segment.

Details

VDISSOLVE is a function for aggregating and generalizing vector data based on different criteria. In general, portions of the input vector data are grouped then dissolved together to make larger shapes. The spatial information of the vector data, controlled by DISSOPT, can be one criteria. The other criteria for identifying sets or groups are attribute values, specified by ATTRLIST. The ATTRLIST parameter lets you specify fields that must have the same values for shapes to be grouped together. The dissolve operation is said to be based on these fields similar to "Group By" in an SQL query.

Each group of shapes will result in one shape in the output segment. When polygons are grouped, any internal boundaries are removed to form larger polygons. When lines are grouped, any lines that share a pseudo-node are combined to form longer lines. When points are grouped, their geometries cannot physically be combined, but the output will consist of multi-part points.

After the grouping is done, the remaining attributes can be manipulated through the ATTRFUNC parameter. This lets you specify which statistics to compute for attributes that are the basis of the dissolve operation. For example, if you want to dissolve county polygons to form statewide information and you have a field named POPULATION, you may want to determine the total population for each state by summing all counties being dissolved.

Example

Dissolve a U.S.A. counties layer into a U.S.A. state layer.

from pci.vdissolve import vdissolve

fili = "usCounties.shp"
dbiv = []
attrlist = "STATE_NAME"
attrfunc = "SUM(POP1990), MEAN(POP90_SQMI), COUNT"
dissopt = ""
filo = "usStates.shp"
ftype = "SHP"
foptions = ""

vdissolve( fili, dbiv, attrlist, attrfunc, dissopt, filo, ftype, foptions )

Environments	PYTHON :: EASI
Quick links	Description :: Parameters :: Parameter descriptions :: Return Value :: Details :: Example