Label | Explanation | Data 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.
| 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.
| String |
Transfer Attributes (Optional) | Specifies the attributes that will be transferred from the input features to the output features.
| String |
Preserve small-sized features
(Optional) | Specifies whether small mask features will be included in the output feature class.
| Boolean |
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
arcpy.cartography.FeatureOutlineMasks(input_layer, output_fc, reference_scale, spatial_reference, margin, method, mask_for_non_placed_anno, {attributes}, {preserve_small_sized_features})
Name | Explanation | Data 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.
| 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.
| String |
attributes (Optional) | Specifies the attributes that will be transferred from the input features to the output features.
| String |
preserve_small_sized_features (Optional) | Specifies whether small mask features will be included in the output feature class.
| Boolean |
Code sample
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")
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)
Environments
Licensing information
- Basic: No
- Standard: No
- Advanced: Yes