Intersecting Layers Masks (Cartography)

Summary

Creates masking polygons at a specified shape and size at the intersection of two symbolized input layers: the masking layer and the masked 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.

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

  • 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.

  • Margin values can be specified in either page units or map units. Typically, margin distance values are specified in page units.

    Margin value units are interpreted differently depending on the units you choose. If you choose points, inches, millimeters, or centimeters, masks will be created using the margin distance as calculated in page space (think of the margin as a distance measured on the paper). The Reference Scale parameter value is taken into account for this calculation.

    If you choose any other units for the margin value, masks will be created using the margin distance as calculated in map space (think of the margin as a real-world distance measure on the earth). Also, in this case, the Reference Scale parameter value is not used as part of the calculation.

  • If one of the input layers 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. If two annotation layers are being intersected, they must have the same reference scale.

  • 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.

  • Processing large datasets together may exceed memory limitations. In this case, consider processing input data by partition by identifying a relevant polygon feature class in the Cartographic Partitions environment setting. Portions of the data, defined by partition boundaries, will be processed sequentially. The output feature class will be seamless and consistent at partition edges.

  • 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
Masking Layer

The symbolized input layer that will intersect the masked layer to create masking polygons. This is the layer that will be displayed when masking is applied to the masked layer.

Layer
Masked Layer

The symbolized input layer that will be masked. This is the layer that will be obscured by the masking polygons.

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. Most of the time margin distance values are specified in page 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 the attributes except the FID from the input features will be transferred to the output features.
  • All attributesAll the attributes from the input features will be transferred to the output features.
String

arcpy.cartography.IntersectingLayersMasks(masking_layer, masked_layer, output_fc, reference_scale, spatial_reference, margin, method, mask_for_non_placed_anno, {attributes})
NameExplanationData Type
masking_layer

The symbolized input layer that will intersect the masked layer to create masking polygons. This is the layer that will be displayed when masking is applied to the masked layer.

Layer
masked_layer

The symbolized input layer that will be masked. This is the layer that will be obscured by the masking polygons.

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. Most of the time margin distance values are specified in page 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 the attributes except the FID from the input features will be transferred to the output features.
  • ALLAll the attributes from the input features will be transferred to the output features.
String

Code sample

IntersectingLayersMasks example 1 (Python window)

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

import arcpy
arcpy.cartography.IntersectingLayersMasks("C:/data/cartography.gdb/transportation/roads",
                                          "C:/data/cartography.gdb/transportation/railroads",
                                          "C:/data/cartography.gdb/transportation/ilm_polys",
                                          "25000", "", "5 meters", "EXACT_SIMPLIFIED", "", "ALL")
IntersectingLayersMasks example 2 (stand-alone script)

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

# Name: IntersectingLayersMasks_standalone_script.py
# Description: Creates masking polygons at a specified
#              shape and size at the intersections of symbolized features. 
 
# Import system modules
import arcpy

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

# Set local variables
masking_layer = "roads.lyrx"
masked_layer = "buildings_poly.lyrx"
outpuf_fc = "cartography.gdb/transportation/ilm_polys"
reference_scale = "25000"
spatial_reference = arcpy.Describe(masking_layer).spatialReference
margin = "5 Points"
method = "CONVEX_HULL"
mask_for_non_placed_anno = "ALL_FEATURES"
attributes = "ALL"

# Execute Intersecting Layers Masks
arcpy.IntersectingLayersMasks_cartography(masking_layer,
                                          masked_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