EDIT_VECTOR
The EDIT_VECTOR command selects and modifies vector data. You can choose to update area, line, and/ or point features with a single operation. You can also supply multiple COMPARE_STR parameters to apply multiple criteria, all of which must be true, in order to edit a feature.
It allows you to assign feature types (classifications), add/update attributes and display labels, and reshape or delete features based on one or more attribute or label values.
The following parameters are supported by the command:
Specify Data to Edit (By Attribute and/or Bounding Box)
- FILENAME - filename of the layer to update. If an empty value is passed in, all loaded vector layers will be updated. This parameter can be listed more than once to specify multiple input files, like FILENAME="FILENAME_1" FILENAME="FILENAME_2". When running the script in the context of the main map view (including loading a workspace) you can also pass in the value 'USER CREATED FEATURES' to have the 'User Created Features' layer updated or 'SELECTED LAYERS' to have any layers selected in the Control Center updated.
- SHAPE_TYPE - specifies the vector object type(s) (area, line, and/or point) to edit. If you don't provide a value then all available matching features will be edited. You can specify multiple different object types as a comma-delimited list of the following (like SHAPE_TYPE="AREAS,LINES"):
- AREAS - area features
- LINES - line features
- POINTS - point features
- COMPARE_STR - specifies a comparison operation to perform to see if a feature is one that needs to be updated. The format is <attr_name><operator><attr_value> where the operator can be "=", "!=", "<", "<=", ">", or ">=". For example, to get all features with CLASS attribute less than 3, use COMPARE_STR="CLASS<3".
- You can also use a wild card symbol ("*wildcard character of variable length") to match any character. For example if you have an attribute named CFCC and you want to match when the value of that attribute starts with an 'A', you can use COMPARE_STR="CFCC=A*" as your parameter. Note that when you use a wild card, only the "=" and "!=" comparison operators will result in a successful match.
- Instead of testing a specific attribute name, you can test whether any attribute in a feature has a particular value. To do this, use "<Any Attribute>" as the attribute name. For example, COMPARE_STR="<Any Attribute>=1" will match all features that have an attribute containing the value "1". You can use any operator, and the comparison value can contain wildcards.
- You can add multiple COMPARE_STR parameters to a single command to combine multiple criteria for your search. SeeAttribute Name Values details for other special allowed attribute names. Special attributes can only be used for "=" and "!=" comparisons.
- CASE_SENSITIVE - specifies whether or not text comparisons are case sensitive or not. Use CASE_SENSITIVE=YES to enable, by default comparisons are not case sensitive.
- ATTR_EXISTS and ATTR_MISSING - specialized instances of COMPARE_STR that allow you to select features based on whether or not an attribute exists. For example, use ATTR_EXISTS="CFCC" to select features that have an attribute called CFCC, or ATTR_MISSING="CFCC" to select features that do not have an attribute called CFCC. ATTR_EXISTS and ATTR_MISSING parameters can be used more than once in an EDIT_VECTOR command, and can be combined with COMPARE_STR parameters.
- COMPARE_OP - controls how multiple COMPARE_STR, ATTR_EXISTS, and ATTR_MISSING parameters are handled. The default is to require that all conditions be met to include a feature (an AND operation), but if you would like to match on a feature if at least one condition is met, use COMPARE_OP=ANY to specify that a logical OR operation should be used rather than an AND operator. You can explicitly add COMPARE_OP=ALL if you want a logical AND operation, but that is the default and it will work that way if you leave it off as well.
- COMPARE_NUM - specifies that any comparisons that are done against numeric values should be numeric rather than alphabetic. Use COMPARE_NUM=YES to enable.
Specify Layer for Output - Default is Input Layer
- COPY_TO_NEW_LAYER - specify COPY_TO_NEW_LAYER=YES to have the results (features) of the EDIT_VECTOR command copied to a new layer. If you use this parameter, but do not specify a value, then YES will be assumed.
- MOVE_TO_NEW_LAYER - specify MOVE_TO_NEW_LAYER=YES to have the results (features) of the EDIT_VECTOR command copied to a new layer, and then deleted from their original layer. If you use this parameter, but do not specify a value, then YES will be assumed.
- NEW_LAYER_NAME - Indicates the name of the layer where the features will be created, copied or moved. If a layer with this name already exists, then that layer will be used, otherwise, a new layer will be created.
- NEW_LAYER_PROJ - special Projection Specification indicating the projection to be used in the new layer. If this parameter is not specified, then the new layer will use the current global projection.
Attribute and Style Editing
See also Attribute Management and The DEFINE_LAYER_STYLE command allows you to define a layer style for the area, line, or point features in a vector layer. You can then apply this with the IMPORT or SET_LAYER_OPTIONS command later.
- AREA_TYPE - specifies the name of the Global Mapper area type to assign to matching area features.
- LINE_TYPE - specifies the name of the Global Mapper line type to assign to matching line features.
- POINT_TYPE - specifies the name of the Global Mapper point type to assign to matching point features.
- LIDAR_CLASS - specifies the name of the Lidar class to apply to all matching Lidar points. This can either be the Lidar class number or the name of the Lidar class displayed in the user interface. For example, to set all points to type 2 (ground), use LIDAR_CLASS=2 or LIDAR_CLASS="Ground". This option requires a Lidar module license.
- ATTR_VAL - specifies the attribute value to update and what value to assign to it. The format is attr_name=attr_value. For example if you want to set the value of an attribute named CFCC to A34, use ATTR_VAL="CFCC=A34". You can add multiple ATTR_VAL parameters to a single command to provide multiple attribute/value pairs (or labels) to add/ update. If you would like to update the feature label rather than an attribute, use <Feature Name> for your attribute name.
- ATTR_TO_DELETE - specifies the name of an attribute to delete from matching features. You can include multiple instances of this attribute to delete multiple values. To remove the feature label rather than an attribute, use <Feature Name> for the attribute name.
- ATTR_TO_KEEP - specifies the name of an attribute to keep from matching features. You can include multiple instances of this attribute to specify multiple attributes to keep. You can also include wildcard characters, like *wildcard character of variable length and ?, in the attribute name.
- ATTR_TO_RENAME - specifies the name of an attribute to rename from matching features and what to rename it to. You can include multiple instances of this attribute to rename multiple attributes. For example, to rename the attribute, CTY to be COUNTY, add the parameter ATTR_TO_RENAME="CTY=COUNTY" to your command.
- ATTR_TO_COPY - specifies the name of an attribute to copy the value of an existing attribute or label to. You can include multiple instances of this parameter to copy multiple attributes. For example, to create a new attribute named DISP_LABEL from the feature label, use ATTR_TO_COPY="DISP_LABEL=<Feature Name>" or to create a new attribute named DEPTH from the value of an attribute named Z, use ATTR_TO_COPY="DEPTH=Z".
- ATTR_REPLACE_STR - specifies the name of an attribute to replace text in, the text to be replace, and the new text. You can include multiple instances of this attribute to replace text in multiple attributes. For example, to replace the text 'Street' with 'St.' in an attribute named 'ROAD_NAME', use ATTR_REPLACE_STR="ROAD_NAME=Street=St." in your command. To replace text in the feature label rather than an attribute, use <Feature Name> for the attribute name. To replace a new line character, use the escape sequence \n.
- STYLE_ATTR - provides a style attribute to update. You can include multiple STYLE_ATTR parameters, one for each style attribute pair. See Field Options for a list of the supported style attributes and values. For example to set all matching lines to a solid green pen 3 pixels wide, add the following: STYLE_ATTR="LINE_STYLE=SOLID" STYLE_ATTR="LINE_WIDTH=3" STYLE_ATTR="LINE_COLOR=RGB(0,255,0)"
- ADD_COORD_ATTRS - specifies that X and Y attributes should be added with the X and Y coordinate values to the attribute list of any matching point features. For matching line features you will get attributes for the start and end points (START_X, START_Y, END_X, and END_Y).
Duplicate Feature Finding
- DELETE_DUPLICATES - specifies whether or not to mark matching features that are duplicates (i.e. same coordinates, label, attributes, type, and style) as deleted. Use DELETE_DUPLICATES=YES to enable. Note that this only removes duplicate features that are within the same layer. Duplicates in different layers will not be deleted.
- MARK_DUPLICATES - specifies whether or not to add a DUPLICATE=Y attribute to matching features that are duplicates (i.e. same coordinates, label, attributes, type, and style). Use MARK_DUPLICATES=YES to enable. Note that this only marks duplicate features that are within the same layer. Duplicates in different layers will not be marked. All features in the duplicate set will be marked with the DUPLICATE=Y attribute except the first one. All of the duplicates will also get a DUP_ID attribute that uniquely identifies the group of duplicates.
- IGNORE_ATTRS - specifies when deleting or marking duplicates that only the geometry of the features should be considered and not any attribute values. Add IGNORE_ATTRS=YES to make the attributes be ignored. You can require some particular attributes to be equal using the DUPLICATE_ATTR parameter.
- DUPLICATE_ATTR - specifies the name of an attribute to that must have the same value in both features being compared when looking for duplicates. You can include multiple instances of this attribute to require multiple attributes to be equal. Special attribute names, like <Feature Name>, are recognized for the attribute name. See Attribute Name Values. For example to require the name and an attribute named ROAD_ID to be equal, add DUPLICATE_ATTR="ROAD_ID" and DUPLICATE_ATTR="<Feature Name>" to your command. This would only be used in conjunction with IGNORE_ATTRS=YES otherwise all attributes are required to be equal.
- SUBSET_IS_DUP - specifies whether a line that is a subset of another line should be treated as a duplicate of the other line. If you add SUBSET_IS_DUP, any lines that are sub-sets of another line will have a SUBSET=Y attribute added along with the other duplicate information.
Apply Terrain Elevations to Vector Data
- APPLY_ELEVS - Enable this option is you want to apply elevation values from loaded terrain layers to vector data. Use APPLY_ELEVS=YES to enable
- CALC_ELEV_SLOPE_STATS - uses loaded elevation data to calculate elevation and slope statistics for all features that meet the selection criteria. It can be used in combination with the following parameters: IGNORE_LINE_VERTICES, INC_UNIT_SUFFIX, ELEV_ATTR, ELEV_LAYER.
- ELEV_ATTR - The name the attribute to save the elevation in when applying to point features. If not provided, the value will be stored in the ELEVATION attribute.
- ELEV_LAYER - filename or description of elevation layer(s) to get elevation values from. By default all visible terrain layers are used. You can include multiple ELEV_LAYER parameters if you have multiple masks to search. Wildcards (* and ?) are supported. Hidden layers are not considered.
- IGNORE_LINE_VERTICES - while computing statistics for a line feature, resample the feature instead of using the features vertices. This parameter works with APPLY_ELEVS or CALC_ELEV_SLOPE_STATS.
- INC_UNIT_SUFFIX - specifies whether or not the unit suffix (like 'm' or 'ft') is appended after the raw elevation value for elevations saved to attributes for point features. The default is off, use INC_UNIT_SUFFIX=YES to enable
- REPLACE_EXISTING - specifies whether we should replace existing elevation values with a new one from terrain layers. This is enabled by default. Use REPLACE_EXISTING=NO to disable replacing existing elevations.
- ADD_EXISTING_ELEV - if replacing existing elevation values, specifies whether the elevation at each location from terrain layers is added to the existing elevation value rather than directly replacing it. Use ADD_EXISTING_ELEV=YES to enable.
Buffer Creation
The following parameters control creation of buffer areas around matching features:
- BUFFER_DIST - explicit buffer radius parameter, in meters by default. e.g. BUFFER_DIST="5.0". You can also put units in string (like BUFFER_DIST="5.0 miles" or BUFFER_DIST="500 m"). Put space between distance and units.
- BUFFER_DIST_END - explicit buffer radius parameter for radius at end of tapered buffer, in meters by default. e.g. BUFFER_DIST_END="3.0". You can also put units in string (like BUFFER_DIST="5.0 miles" or BUFFER_DIST="500 m"). Put space between distance and units.
- BUFFER_ATTR - name of attribute that determines buffer radius for a feature. One of "BUFFER_ATTR" or "BUFFER_DIST" must be used. e.g. BUFFER_ATTR="BUFFERSIZE"
- BUFFER_ATTR_END - name of attribute that determines buffer radius at the end of a tapered buffer for a feature. One of "BUFFER_ATTR_END" or "BUFFER_DIST_END" must be used to get a tapered buffer
- BUFFER_ATTR_UNITS - String representing units to use to interpret value obtained by "BUFFER_ATTR". Accepts "M" (meters), "METERS", "FT", "FEET", "KM", "MILES", "NM" (nautical miles). Defaults to meters. e.g. BUFFER_ATTR_UNITS="FT"
- BUFFER_COMBINE_AREAS - boolean, whether to combine created buffers (default = NO). e.g. BUFFER_COMBINE_AREAS=YES
- BUFFER_CREATE_RECTS - boolean, whether to create rectangle buffers (default = NO). e.g. BUFFER_CREATE_RECTS="YES"
- BUFFER_Z_OFFSET - Z-offset applied to z-value of 3D features (default = 0), in meters. e.g. BUFFER_Z_OFFSET="100"
- BUFFER_ZONES - number of buffer zones to create per feature (default = 1). e.g. BUFFER_ZONES=2
Additional Vector Editing Options
- DELETE_FEATURES - specifies whether or not to mark all matching features as deleted. Use DELETE_FEATURES=YES to enable.
- DELETE_ISLANDS - use DELETE_ISLANDS=YES to specify that all islands/holes in matching area features should be marked as deleted
- COORD_OFFSET - specifies the offset to apply to any coordinates for the features that match the specified criteria. The offset should be in the units of the layer the features are being matched from. The offset should be specified as a comma-delimited list of the X and Y offsets, such as COORD_OFFSET="100000.0,200000.0".
- COORD_SCALE - specifies the scale factors to apply to any coordinates for the features that match the specified criteria. Each coordinate will be multiplied by these scale factor. The scale factors should be specified either as a single value (the most common scenario) or as separate scale factors for the X and Y values, like COORD_SCALE=1.00005 for a single value, or COORD_SCALE=1.0045,1.0052 for separate X and Y coordinate scales.
- ROTATE_ANGLE - specifies the angle in degrees by which to rotate matching features by clockwise around some point. The ROTATE_ABOUT parameter specifies what point the feature coordinates are rotated about.
- ROTATE_ABOUT - if a non-zero ROTATE_ANGLE value is specified, specifies the point that the features should be rotated about, with the default being about the center of all matching features. The following values are supported:
- COMBINED_CENTER - rotates about the combined center of all matching features. This is the default value.
- INDIVIDUAL_CENTER - rotates each feature about the center of the feature independently.
- Manually specified location - you can manually specify the X and Y coordinates to rotate about (in the projection of the layer being rotated), like ROTATE_ABOUT="45000.0,1356000.0"
- CREATE_LABEL_POINTS - specifies that a point feature should be created at the centroid/label position of each matching area feature. Use CREATE_LABEL_POINTS=YES to enable. If you only want to match areas with a non-empty label also add COMPARE_STR="<Feature Name>=*".
- CREATE_VERTEX_POINTS - specifies that a point feature should be created at each vertex of the matching area and line features. Use CREATE_VERTEX_POINTS=YES to enable.
- CONNECT_ISLANDS - specifies that any matching area features with islands should have the islands connected to the outer area boundary to form a single vertex list. This is useful if you need to export the data for use in software that doesn't support area features with holes/islands in them. Use CONNECT_ISLANDS=YES to enable.
- SIMPLIFICATION - specifies a simplification threshold to use to simplify/reduce the matching area and line features. It can contain a horizontal threshold (e.g., SIMPLIFICATION="20") or both horizontal and vertical thresholds, separated by a blank (e.g., SIMPLIFICATION="20 10").
- The horizontal threshold specifies how far off a straight line (in the units of the current projection) that a point has to be before it is kept. Vertices that are this distance or further from the straight line will be kept. Vertices that are closer than this distance from the straight line will be discarded.
- The vertical threshold applies only to 3D data, and will be applied to the vertex elevations. If the calculation exceeds the threshold, then the vertex will be kept.
- By default, the vertical threshold is treated as elevation (in the vertical unit of the data). This specifies a threshold for the elevation difference between vertices. If the elevation difference is greater than or equal to the threshold, the vertex will be kept.
- If you include the VERT_THRESH_IS_SLOPE parameter, the vertical threshold will be treated as slope, in degrees. This indicates a threshold for the slope difference between vertices. Each calculation involves three points (A, B, and C). If the difference between slope AC and slope AB exceeds the threshold, and the difference between slope AC and slope BC exceeds the threshold, then the point will be kept.
- CONVERT_AREAS_TO_LINES - specifies that any matching area features will have new line features created from them. Use CONVERT_AREAS_TO_LINES=YES to enable this functionality. By default each matching area and all islands/holes in that area will have lines created for them (the islands will get an ISLAND=Y attribute), but you can add IGNORE_ISLANDS=YES to just create lines from the parent areas.
- INSERT_VERTICES_AT_INTERSECTIONS - specifies that new vertices will be inserted at the intersection of any matching line features. Use INSERT_VERTICES_AT_INTERSECTIONS=YES to enable this functionality.
- SPLIT_AT_INTERSECTIONS - specifies that any matching line features that share an interior vertex will be split at that vertex into new lines. Use SPLIT_AT_INTERSECTIONS=YES to enable this functionality. Use this in conjunction with the INSERT_VERTICES_AT_INTERSECTIONS option to insert vertices at intersections and then split the lines there. The INSERT_VERTICES_AT_INTERSECTIONS option is enabled by default if SPLIT_AT_INTERSECTIONS is enabled (v16.1.2 and later). Add INSERT_VERTICES_AT_INTERSECTIONS=NO if you only want to split at existing vertices.
- PTS_AT_INTERSECTIONS - specifies that new point features will be created wherever two or more matching line features touch. Use PTS_AT_INTERSECTIONS=YES to enable.
- UNIQUE_ID_BASE - specifies a number to start assigning unique IDs to features that match the query. For example, using UNIQUE_ID_BASE=1 would assign ID attributes to each matching feature starting at 1 and increasing sequentially (i.e. 1, 2, 3, etc.).
- SMOOTH_FEATURES - specifies that matching area and line features should be smoothed. Use SMOOTH_FEATURES=YES to enable.
- CREATE_COVERAGE_AREAS - specifies that a new layer with coverage areas for all matching features should be created. Use CREATE_COVERAGE_AREAS=YES to enable.
- COVERAGE_SMOOTHING_FACTOR - specifies a smoothing factor to use when creating the coverage areas to control how tightly shrink-wrapped around the vector features the area is. The default value is 1.0, but any value greater than 0 is allowed, with larger values resulting in more smoothing.
- CREATE_SKELETON_LINES - specifies that skeleton lines for the matching area features should be created and added to a new layer. The layer description will be the area layer description with "Skeleton Lines" appended to it. Use CREATE_SKELETON_LINES=YES to enable.
- REMOVE_ISLANDS - specifies that any areas with islands/holes should be chopped up to remove the islands. The original area will be marked as deleted and the new island-less areas added to the same layer. Use REMOVE_ISLANDS=YES to enable this behavior.
- POINT_LAYER_TO_SPLIT_AGAINST - specifies the full path and filename or description of a loaded point layer to use to split matching line features. The closest line to each point in the layer will be found and (if closer than MAX_DIST) will be split at the location that the point snaps to.
- MAX_DIST - specifies the maximum distance (in meters) that a point from the POINT_LAYER_TO_SPLIT_AGAINST layer can be from the nearest line and still split the line.
- FIX_INVALID - specifies that invalid polygon geometries should be found and, if possible, fixed. Add FIX_INVALID=YES to enable this.
-
Specify Bounding Box for Operation
See also Specify Bounds for Operation
- GLOBAL_BOUNDS - specifies the combine bounds in units of the current global projection. There should be 4 values in a comma-delimited list following the parameter name. The values should be in order of minimum x, minimum y, maximum x, maximum y.
- GLOBAL_BOUNDS_SIZE - specifies the combine bounds in units of the current global projection. There should be 4 values in a comma-delimited list following the parameter name. The values should be in order of minimum x, minimum y, width in x, width in y.
- LAT_LON_BOUNDS - specifies the combine bounds in latitude/longitude degrees. There should be 4 values in a comma-delimited list following the parameter name. The values should be in order of west-most longitude, southern-most latitude, eastern-most longitude, northern-most latitude.
- LAYER_BOUNDS - specifies that the operation should use the bounds of the loaded layer(s) with the given filename. For example, to export to the bounds of the file "c:\test.tif", you would use LAYER_BOUNDS="c:\test.tif". Keep in mind that the file must be currently loaded.
- LAYER_BOUNDS_EXPAND - specifies that the operation should expand the used LAYER_BOUNDS bounding box by some amount. The amount to expand the bounding rectangle by should be specified in the current global projection. For example, if you have a UTM/meters projection active and want to expand the bounds retrieved from the LAYER_BOUNDS parameter by 100 meters on the left and right, and 50 meters on the top and bottom, you could use LAYER_BOUNDS_EXPAND="100.0,50.0". You can also specify a single value to apply to all 4 sides, or supply 4 separate values in the order left,top,right,bottom.
- SNAP_BOUNDS_TO_MULTIPLE - specifies that the top-left corner of the bounding box for the operation should be snapped to a multiple of the given value. For example, using SNAP_BOUNDS_TO_MULTIPLE=1 will snap the top-left corner to the nearest whole number. The values will always go smaller for X/easting/longitude and larger to Y/northing/latitude so you always get at least what is requested.
- SNAP_BOUNDS_TO_SPACING - specifies that the top-left corner of the bounding box for the operation should be snapped to a multiple of the resolution of the operation. For example, if you are exporting at 5 meter spacing, the top left corner will be snapped to the nearest multiple of 5. Use SNAP_BOUNDS_TO_SPACING=YES to enable or SNAP_BOUNDS_TO_SPACING=NO to disable. If not provided, the global setting for snapping exports to the nearest sample spacing boundary from the Advanced section of the General tab of the Configuration dialog will be used.
- USE_EXACT_BOUNDS - specifies that the exact bounds that were defined in the command should be used. Generally, when the bounds specified in a command are not the same as the data bounds, the command uses the intersection between the two. When USE_EXACT_BOUNDS=YES is specified, the command will use the bounds as specified, instead of the intersection.
SAMPLES
Here is an example illustrating how to move features with a CLASS attribute with a value of '1' to a new layer named 'Major Highways':
EDIT_VECTOR MOVE_TO_NEW_LAYER=YES NEW_LAYER_NAME="Major Highways" \ COMPARE_STR="CLASS=1"
Here is an example illustrating how to add evenly spaced points every 200 meters along the features containing a CLASS attribute with a value of '1'. Point features will also be created at the end point, and at each current vertex:
EDIT_VECTOR CREATE_POINTS_ALONG_FEATURES=200 COMPARE_STR="CLASS=1" \ KEEP_END_POINT=YES KEEP_ORIGINAL_VERTICES=YES
Here is an example illustrating how to add evenly spaced perpendicular lines, 50 meters long, every 250 meters along the features containing a CLASS attribute with a value of '2'. Line features will also be created at the end point:
EDIT_VECTOR CREATE_PERP_LINES_ALONG_FEATURES=250 PERP_LINE_LENGTH=50 COMPARE_STR="CLASS=2" \ KEEP_END_POINT=YES
Here is a sample script demonstrating applying elevations to all loaded vector data from all loaded terrain:
GLOBAL_MAPPER_SCRIPT VERSION=1.00 // Apply elevations from all loaded terrain layers to all loaded vector layer. // Do NOT add elev values to existing values and do NOT include unit suffix. // If the data already has an existing elevation, do NOT replace it // Assign elevations for points to the ELEV_1 attribute rather than ELEVATION EDIT_VECTOR APPLY_ELEVS=YES ADD_EXISTING_ELEV=NO INC_UNIT_SUFFIX=NO \ REPLACE_EXISTING=NO ELEV_ATTR="ELEV_1"
For more examples of how to use the EDIT_VECTOR command, see the sample at the bottom of this document.
Topic Overview
Tool Information