Cul-De-Sac Masks (Cartography)

Summary

Creates a feature class of polygon masks from a symbolized input line layer.

Usage

  • This tool only creates masks at the unconnected ends of lines (also called culs-de-sac). A line end is considered connected if it shares its endpoint with the endpoint of another line. This tool only accepts line layers as input.

  • This tool is designed to provide line end masks in cases in which lines have been symbolized using a rounded end cap to smooth the transition of line connections. Rather than having lines end with a rounded end cap, the end of the line can be masked using the polygon feature class created with this tool.

  • 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 line layer contains multipart line geometries, cul-de-sac masks are created for all unconnected line ends, including the ends of parts within multipart lines.

  • When creating masks, it is important to know that 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. An increase in the number of masks, having more complex masks, and masking against marker or polygon fill symbols will result in slower drawing on your screen. In addition, printing and exporting performance can be poor and even fail to produce valid output. This is because of the large amount of processing required to print and export maps with masks, and because of known limitations in how graphic file formats store map export results that have many complicated masks.

  • Margin values are specified in either page units or map units. Most of the time, you will specify your margin distance value in page units.

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

    If you choose any other units for your margin, masks are created using the margin distance as calculated in map space (you can 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.

Parameters

LabelExplanationData Type
Input Layer

The input line 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 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 are specified in either page units or map units. Most of the time, you will specify your margin distance value in page units.

The margin cannot be negative.

Linear Unit
Transfer Attributes
(Optional)

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

  • Only feature IDsOnly the FID field from the input features will be transferred to the output features. This is the default.
  • All attributes except feature IDsAll 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.CulDeSacMasks(input_layer, output_fc, reference_scale, spatial_reference, margin, {attributes})
NameExplanationData Type
input_layer

The input line 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 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 are specified in either page units or map units. Most of the time, you will specify your margin distance value in page units.

The margin cannot be negative.

Linear Unit
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

CulDeSacMasks example 1 (Python window)

The following Python window script demonstrates how to use the CulDeSacMasks tool in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.CulDeSacMasks_cartography("C:/data/cartography.gdb/transportation/roads",
                                "C:/data/cartography.gdb/transportation/cds_polys",
                                "25000", "", "5 meters", "ALL")
CulDeSacMasks example 2 (stand-alone script)

This stand-alone script shows an example of using the CulDeSacMasks tool.

# Name: CulDeSacMasks_standalone_script.py
# Description: Creates masks at the unconnected ends of lines in the input layer. 
 
# Import system modules
import arcpy

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

# Set local variables
input_layer = "cartography.gdb/transportation/roads"
outpuf_fc = "cartography.gdb/transportation/cds_polys"
reference_scale = "25000"
spatial_reference = arcpy.Describe(input_layer).spatialReference
margin = "5 meters"
attributes = "ALL"

# Execute Cul De Sac Masks
arcpy.CulDeSacMasks_cartography(input_layer, output_fc, reference_scale, 
                                spatial_reference, margin, attributes)

Licensing information

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

Related topics