TagLayer()

Summary

Fills a field in a layer with information about the nearest feature in another layer.

 

Changes

In Version 2015 the fourth argument can be a layer|set. In version 2022, NearestToAreaEdge option added.

 

Syntax

TagLayer(string mode, string dest_layer_set, string dest_field_name, string source_layer_set, string source_field_name [, array options])

 

Argument	Contents
mode	One of two values: - "Distance": to tag with the distance to the nearest item in the source layer - "Value": to tag with the value of a field from the nearest item in the source layer
dest_layer_set	The layer and selection set into which values are written
dest_field_name	The full field spec of the field in the destination layer where the results are stored; in Distance mode, this field must be numeric
source_layer_set	The layer or layer and selection set on which to search for the nearest record
source_field_name	The full field spec of the field to read in Value mode; ignored if in Distance mode

 

Options	Type	Contents
NearestToAreaEdge	Boolean	"False" (the default) to measure distances and get values based on the centroids closest to each target feature.. "True" to measure distances and get values based on the nearest area edge to each target feature

 

Notes

• source_layer_set can be just a layer name or a layer + "|" + set.

• Source layer and target layer must be different.

• Option NearestToAreaEdge only applies when tagging points to the nearest area edge.  

• source_layer_set can be just a layer name or a layer + "|" + set.

• If the source layer is an area layer, then each destination record is tagged with the source area record that encloses it. If no area record encloses a destination record, then that destination record gets no value. Depending on the destination layer's type, this means the matching source area must enclose either the destination point, the destination area centroid, or the center of the bounding box of the destination line.

• If the source layer is not an area layer, the distance measurements are:

• • point-to-point or point-to-area-centroid distances if neither layer is a line layer

  • perpendicular distances if at least one layer is a line layer – in this case, either from a point to a line, from the area centroid to a line, or from any shape-point of one line to the other line.

Example

// Compute distance to nearest highway and place the result in the HWYDIST field in the

// Airports layer

TagLayer("Distance", "Airports|","Airports.HWYDIST", "Highways", null)

 

// Place the name of the nearest highway in the HWYNAME field in the airport layer

TagLayer("Value", "Airports|","Airports.HWYNAME", "Highways", "Highways.ROUTENAME")

 

Error Codes

Error Type

Meaning

Error

The destination layer, source layer, destination field, or destination set (if specified) does not exist; or the destination layer or source layer is not geographic (e.g., an image layer); or the destination layer or field is read-only; or Distance mode and the destination field is not real-typed; or Value mode and the source field does not exist; or the source and destination area layer are the same

 

See Also

Function	Summary
LocateNearestRecord()	Finds the map feature nearest a point location
LocateRecord()	Locates a record based on the value of a field
LocateNearestRecords()	Finds the map features nearest a point location
SelectNearestFeatures()	Selects a feature in the current layer nearest to each feature in another layer or selection set