ZVALTRNS

Description

Transfers the z-values of an input vector segment from a shape to its attribute, or from an attribute to its shape. If you have a z-value as an attribute for a shape on an Unstructured, Line, Point, Whole Polygon, or Topological Line vector layer, you can transfer that value to the shape's vertices. Conversely, you can also convert the Z-values from the shape's vertices into an attribute.

Parameters

zvaltrns(file, dbvs, ztrnsdir, ztrnsfld, ztrnstyp, aggrtype, fldtoshp)

Name	Type	Caption	Length	Value range
FILE *	str	Input file name	1 -
DBVS *	List[int]	Input vector segment	1 - 1
ZTRNSDIR	str	Z-value transfer direction	0 - 9	SHPTOATTR \| ATTRTOSHP Default: SHPTOATTR
ZTRNSFLD	str	Name of destination field	0 - 64
ZTRNSTYP	str	Date type for new attribute field	0 - 7	Default: INTEGER
AGGRTYPE	str	Aggregation method for z-values	0 - 6	Default: MEAN
FLDTOSHP	str	Attribute field to shape	0 - 64

* Required parameter

Parameter descriptions

FILE

Specifies the name of the PCIDSK database file containing the vector segment to process.

DBVS

Specifies the vector segment to process.

ZTRNSDIR

Specifies whether the z-value is transferred from the shape to the attribute, or from the attribute to shape vertices.

Options are:

SHPTOATTR (Shape to attribute)
ATTRTOSHP (Attribute to shape)

ZTRNSFLD

Specifies the name of the destination field to receive the z-value from the shape vertices.

The field can be any existing numeric field or a non-existing field which will be created.

This parameter is used only when the transfer direction (ZTRNSDIR) is set to 'Shape to attribute' (SHPTOATTR).

ZTRNSTYP

Specifies the data type to apply if a new field is created for the destination field.

Supported data types are:

Integer: defines the field for positive or negative whole numbers
Float: defines the field for single-precision real numbers
Double: defines the field for double-precision real numbers

This parameter is used only when a new destination field is created (ZTRNSFLD="newfieldname"). If the destination field already exists, the data type of the existing field is maintained.

AGGRTYPE

Specifies the method used to combine z-values of shapes.

Available options are:

First: transfer shape first vertex z-value to attribute
Last: transfer shape last vertex z-value to attribute
Sum: transfer sum of shape z-values to attribute
Mean: transfer mean of shape z-values to attribute (default value)
Min: transfer shape minimum vertex z-value to attribute
Max: transfer shape maximum vertex z-value to attribute
Mode: transfer mode of shape z-values to attribute
Median: transfer median of shape z-values to attribute
StdDev: transfer standard deviation of shape z-values to attribute

FLDTOSHP

Specifies the numeric attribute field to supply the z-value to update the shape vertices.

This parameter is used only when the transfer direction (ZTRNSDIR) is 'Attribute to shape' (ATTRTOSHP).

Details

ZVALTRANS is used to transfer the z-value of an input vector segment from a shape to its attribute, or from an attribute to its shape.

If the transfer direction is "shape to attribute", the z-value of a shape's vertices is transferred to an existing attribute field or to a new attribute field. If the function creates a new field, the user must specify the data type of this new field.

The available data types are:

Integer: defines the field for positive or negative whole numbers
Float: defines the field for single-precision real numbers
Double: defines the field for double-precision real numbers

If the specified field exists, the transfer type (ZTRNSTYP) parameter is not used; instead, the z-value is converted to the data type of the existing field.

Z-values are written to the destination field in the data type defined by that field. For example, if the z-value is a real and the destination field is defined as an integer, the z-value is truncated to an integer.

Where the shape has variable z-values for its vertices, the z-value aggregation sets the method for determining what z-value will be transferred to the shapes attribute. Each shape 'destination field' can only store one value for the z-value. Aggregation options are:

First: transfer shape first vertex z-value to attribute
Last: transfer shape last vertex z-value to attribute
Sum: transfer sum of shape z-values to attribute
Mean: transfer mean of shape z-values to attribute
Min: transfer shape minimum vertex z-value to attribute
Max: transfer shape maximum vertex z-value to attribute
Mode: transfer mode of shape z-values to attribute
Median: transfer median of shape z-values to attribute
StdDev: transfer standard deviation of shape z-values to attribute

If the transfer direction is from 'Attribute to shape', the attribute field must exist in the input vectorlayers attribute table. The field must be a numeric data type.

ZVALTRNS does not deal with an input layer of Topo Area or Table.

Example

The Input and output layer is segment 25 from file irvine.pix. The z-value will be transferred from shapes to a new attribute field named "New Field 1". The type of new field is "Double" and the transfer method is First.

from pci.zvaltrns import zvaltrns

file	=	"irvine.pix"
dbvs	=	[25]
ztrnsdir	=	"SHPTOATTR"
ztrnsfld	=	"New Field 1"
ztrnstyp	=	"Double"
aggrtype	=	"First"
fldtoshp	=	""

zvaltrns( file, dbvs, ztrnsdir, ztrnsfld, ztrnstyp, aggrtype, fldtoshp )