Feature Outline Masks (Cartography)

Summary

Creates mask polygons at a specified distance and shape around the symbolized features in the input layer.

Learn more about how Feature Outline Masks and Intersecting Layers Masks work

Usage

  • This tool accepts point, line, and polygon feature layers, as well as geodatabase annotation layers as input.

  • Adding masks to maps adds complexity that will slow map drawing and affect map printing and exporting. Generally, there are three things to consider when creating masks for a map: the number of masks, the complexity of the masks, and whether the masks will be used to mask polygon features filled with marker or line symbols. All of these things result in slower drawing on your screen. In addition, printing and exporting performance may be poor or fail to produce valid output. This is due to the processing required to print and export maps with masks, and the known limitations in how graphic file formats store map export results that have many complicated masks.

  • To improve drawing performance as well as printing and exporting performance and reliability, use the simplest masks necessary for the purposes of the map. In particular, when using the Mask Kind parameter to mask annotation text, the Convex hull option is sufficient for many map purposes. For more detailed text masks, use the Exact simplified option. When masking a large amount of text on a relatively large map, avoid using the Exact option, because it will create too many complicated masks to produce valid output efficiently.

  • This tool filters out very small mask features from the output by default. Small masks that may not be visible at the map's reference scale are removed to create a manageable and efficient output feature class. If your workflow requires very small masks, check the Preserve small-sized features parameter to preserve all masks in the output feature class regardless of size. Many small masks may add complexity to the map and map output.

  • Margin values are typically specified in page units, but map units are also accepted.

  • Typically, margins are greater than 0. A margin size of 0 creates masks that represent the exact shape of the symbolized features.

  • If the input layer is an annotation layer, the reference scale will be automatically set to the reference scale of the layer's feature class to ensure accurate calculation of the mask.

  • When masking annotation projected on the fly, create masks using the map's spatial reference by properly setting it in the Calculation Coordinate System parameter. Readability is preserved when text is projected on the fly, which is why there may be differences in the spatial area that text occupies in different projections.

  • Masks of annotation features are font specific. When using masks with text, ensure that the same font is used on screen as in the output. To do this, embed fonts in vector output or download SoftFonts to printers or plotters.

  • Masks will be created based on the current map rotation and may not be valid if the map is set to a different rotation after mask creation.

Parameters

LabelExplanationData Type
Input Layer

The symbolized input layer from which the masks will be created.

Layer
Output Feature Class

The feature class that will contain the mask features.

Feature Class
Reference Scale

The reference scale that will be used for calculating the masking geometry when masks are specified in page units. This is typically the reference scale of the map.

Double
Calculation Coordinate System

The spatial reference of the map in which the masking polygons will be created. This is not the spatial reference that will be assigned to the output feature class. It is the spatial reference of the map in which the masking polygons will be used, since the position of symbology may change when features are projected.

Spatial Reference
Margin

The space in page units surrounding the symbolized input features used to create the mask polygons. Typically, masking polygons are created with a small margin around the symbol to improve visual appearance. Margin values can be specified in either page units or map units.

The margin cannot be negative.

Linear Unit
Mask Kind

Specifies the type of masking geometry that will be created.

  • BoxA polygon representing the extent of the symbolized feature will be created.
  • Convex hullThe convex hull of the symbolized geometry of the feature will be created. This is the default.
  • Exact simplifiedA generalized polygon representing the exact shape of the symbolized feature will be created. Polygons created with this method will have a significantly smaller number of vertices compared to polygons created with the Exact option.
  • ExactA polygon representing the exact shape of the symbolized feature will be created.
  • BoxA polygon representing the extent of the symbolized feature will be created.
  • Convex hullThe convex hull of the symbolized geometry of the feature will be created. This is the default.
  • Exact simplifiedA generalized polygon representing the exact shape of the symbolized feature will be created. Polygons created with this method will have a significantly smaller number of vertices compared to polygons created with the EXACT option.
  • ExactA polygon representing the exact shape of the symbolized feature will be created.
String
Create masks for unplaced annotation

Specifies whether masks for unplaced annotation will be created. This parameter is only used when masking geodatabase annotation layers.

  • All annotation featuresMasks will be created for all annotation features. This is the default.
  • Only placed annotation featuresMasks will only be created for features with a status of placed.
String
Transfer Attributes
(Optional)

Specifies the attributes that will be transferred from the input features to the output features.

  • Only the FID fieldOnly the FID field from the input features will be transferred to the output features. This is the default.
  • All attributes except the FID fieldAll attributes except the FID field from the input features will be transferred to the output features.
  • All attributes All attributes from the input features will be transferred to the output features.
String
Preserve small-sized features
(Optional)

Specifies whether small mask features will be included in the output feature class.

  • Unchecked—Small mask features will not be included in the output feature class. This is the default.
  • Checked—All mask features will be included in the output feature class.

Boolean

arcpy.cartography.FeatureOutlineMasks(input_layer, output_fc, reference_scale, spatial_reference, margin, method, mask_for_non_placed_anno, {attributes}, {preserve_small_sized_features})
NameExplanationData Type
input_layer

The symbolized input layer from which the masks will be created.

Layer
output_fc

The feature class that will contain the mask features.

Feature Class
reference_scale

The reference scale that will be used for calculating the masking geometry when masks are specified in page units. This is typically the reference scale of the map.

Double
spatial_reference

The spatial reference of the map in which the masking polygons will be created. This is not the spatial reference that will be assigned to the output feature class. It is the spatial reference of the map in which the masking polygons will be used, since the position of symbology may change when features are projected.

Spatial Reference
margin

The space in page units surrounding the symbolized input features used to create the mask polygons. Typically, masking polygons are created with a small margin around the symbol to improve visual appearance. Margin values can be specified in either page units or map units.

The margin cannot be negative.

Linear Unit
method

Specifies the type of masking geometry that will be created.

  • BOXA polygon representing the extent of the symbolized feature will be created.
  • CONVEX_HULLThe convex hull of the symbolized geometry of the feature will be created. This is the default.
  • EXACT_SIMPLIFIEDA generalized polygon representing the exact shape of the symbolized feature will be created. Polygons created with this method will have a significantly smaller number of vertices compared to polygons created with the EXACT option.
  • EXACTA polygon representing the exact shape of the symbolized feature will be created.
String
mask_for_non_placed_anno

Specifies whether masks for unplaced annotation will be created. This parameter is only used when masking geodatabase annotation layers.

  • ALL_FEATURESMasks will be created for all annotation features. This is the default.
  • ONLY_PLACEDMasks will only be created for features with a status of placed.
String
attributes
(Optional)

Specifies the attributes that will be transferred from the input features to the output features.

  • ONLY_FIDOnly the FID field from the input features will be transferred to the output features. This is the default.
  • NO_FIDAll attributes except the FID field from the input features will be transferred to the output features.
  • ALL All attributes from the input features will be transferred to the output features.
String
preserve_small_sized_features
(Optional)

Specifies whether small mask features will be included in the output feature class.

  • DO_NOT_PRESERVE_SMALL_SIZED_FEATURESSmall mask features will not be included in the output feature class. This is the default.
  • PRESERVE_SMALL_SIZED_FEATURESAll mask features will be included in the output feature class.
Boolean

Code sample

FeatureOutlineMasks example 1 (Python window)

The following Python window script demonstrates how to use the FeatureOutlineMasks function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data"
sr = arcpy.SpatialReference(4326)
arcpy.cartography.FeatureOutlineMasks("C:/data/cartography.gdb/transportation/roads",
                                "C:/data/cartography.gdb/transportation/fom_polys",
                                "25000", sr, "5 meters","EXACT_SIMPLIFIED", 
                                "ALL_FEATURES", "ALL")
FeatureOutlineMasks example 2 (stand-alone script)

This stand-alone script shows an example of using the FeatureOutlineMasks function.

# Name: FeatureOutlineMasks_standalone_script.py
# Description: Creates mask polygons at a specified distance and shape
#           around symbolized features. 
 
# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data"

# Set local variables
input_layer = "roads.lyrx"
output_fc = "cartography.gdb/transportation/roads_fom_polys"
reference_scale = "25000"
spatial_reference = arcpy.SpatialReference(4326) 
margin = "5 meters"
method = "EXACT_SIMPLIFIED"
mask_for_non_placed_anno = "ONLY_PLACED"
attributes = "ALL"

# Execute Feature Outline Masks
arcpy.FeatureOutlineMasks_cartography(input_layer,
                                      output_fc,
                                      reference_scale,
                                      spatial_reference,
                                      margin, method,
                                      mask_for_non_placed_anno,
                                      attributes)

Licensing information

  • Basic: No
  • Standard: No
  • Advanced: Yes

Related topics