Show Navigation | Hide Navigation

You are here:
Geoprocessing tool reference > Cartography toolbox > Masking toolset > Tools

Feature Outline Masks (Cartography) (ArcInfo only)
Release 9.2 Last modified July 13, 2007	Print all topics in : "Tools"

Related Topics

Creates mask polygons at a specified distance and shape around the symbolized features in the input layer. This tool accepts point, line, and polygon feature layers as well as geodatabase annotation layers as input.

Usage tips

This tool accepts point, line, and polygon feature layers as well as geodatabase annotation layers as input.
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: (1) the number of masks, (2) the complexity of the masks, and (3) 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/or 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, first, because of the large amount of processing required to print and export maps with masks, and second, because of known limitations in how graphic file formats store map export results that have many complicated masks.
When seeking to improve drawing performance as well as printing and exporting performance and reliability, the most important guideline to follow is to use the simplest masks necessary for the purposes of your map. In particular, when masking annotation text, you will find that CONVEX_HULL type masks are sufficient for many map purposes. If you need more detailed text masks, then use the EXACT_SIMPLIFIED type. Generally, when masking much text on a relatively large map, avoid using the EXACT type mask because it will create too many complicated masks to produce valid output efficiently.
Margin values are specified in either page units or map units. Most of the time you will want to specify your margin distance value in page units.

Margin value units are interpreted differently depending on which units you choose. If you choose points, inches, millimeters, or centimeters, then 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 accounted for in this calculation.

If you choose any other units for your margin, then 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.
Masks will be created if the margin distance is 0 or negative. A margin size of 0 will create a polygon that represents the exact shape of the symbolized feature. A negative margin will result in a polygon smaller than the symbolized feature. Generally, a margin value larger than 0 will be specified to produce the desired masking effect.
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, masks should be created using the map's spatial reference by properly setting it in the spatial reference 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, it is important to ensure that the same font is used onscreen as in the output. To do this, choose to embed fonts in vector output or download SoftFonts to printers or plotters.

Command line syntax
An overview of the Command Line window
FeatureOutlineMasks_cartography <input_layer> <output_fc> <reference_scale> <spatial_reference> <margin> <CONVEX_HULL | BOX | EXACT_SIMPLIFIED | EXACT> <ALL_FEATURES | ONLY_PLACED> {ONLY_FID | NO_FID | ALL}

Parameter	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 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 for 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 polygon. 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 want to specify your margin distance value in page units. Margin value units are interpreted differently depending on which units you choose. If you choose points, inches, millimeters, or centimeters, then 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 accounted for in this calculation. If you choose any other units for your margin, then 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.	Linear unit
<CONVEX_HULL \| BOX \| EXACT_SIMPLIFIED \| EXACT>	The type of masking geometry created. There are four types: BOX — A polygon representing the extent of the symbolized feature. CONVEX_HULL — The convex hull of the symbolized geometry of the feature. This is the default. EXACT_SIMPLIFIED — A generalized polygon representing the exact shape of the symbolized feature. Polygons created with this method will have a significantly smaller number of vertices compared to polygons created with the EXACT method. EXACT — A polygon representing the exact shape of the symbolized feature.	String
<ALL_FEATURES \| ONLY_PLACED>	Specifies whether to create masks for unplaced annotation. This option is only used when masking geodatabase annotation layers. ALL_FEATURES: Creates masks for all the annotation features. ONLY_PLACED: Only creates masks for features with a status of placed.	Boolean
{ONLY_FID \| NO_FID \| ALL}	Determines which attributes will be transferred from the input features to the output features. ONLY_FID: Only the FID field from the input features will be transferred to the output features. This is the default. NO_FID: All the attributes except the FID from the input features will be transferred to the output features. ALL: All the attributes from the input features will be transferred to the output features.	String

Data types for geoprocessing tool parameters

Command line example

FeatureOutlineMasks_cartography d:\parcelsanno.lyr d:\parcelsannomasks.shp 1200 d:\utm17n.prj "2.0 Points" BOX ALL_FEATURES ONLY_FID

Scripting syntax
About getting started with writing geoprocessing scripts
FeatureOutlineMasks_cartography (input_layer, output_fc, reference_scale, spatial_reference, margin, method, mask_for_non_placed_anno, attributes)

Parameter	Explanation	Data Type
input_layer (Required)	The symbolized input layer from which the masks will be created.	Layer
output_fc (Required)	The feature class that will contain the mask features.	Feature Class
reference_scale (Required)	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 (Required)	The spatial reference for 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 (Required)	The space in page units surrounding the symbolized input features used to create the mask polygon. 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 want to specify your margin distance value in page units. Margin value units are interpreted differently depending on which units you choose. If you choose points, inches, millimeters, or centimeters, then 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 accounted for in this calculation. If you choose any other units for your margin, then 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.	Linear unit
method (Required)	The type of masking geometry created. There are four types: BOX — A polygon representing the extent of the symbolized feature. CONVEX_HULL — The convex hull of the symbolized geometry of the feature. This is the default. EXACT_SIMPLIFIED — A generalized polygon representing the exact shape of the symbolized feature. Polygons created with this method will have a significantly smaller number of vertices compared to polygons created with the EXACT method. EXACT — A polygon representing the exact shape of the symbolized feature.	String
mask_for_non_placed_anno (Required)	Specifies whether to create masks for unplaced annotation. This option is only used when masking geodatabase annotation layers. ALL_FEATURES: Creates masks for all the annotation features. ONLY_PLACED: Only creates masks for features with a status of placed.	Boolean
attributes (Optional)	Determines which attributes will be transferred from the input features to the output features. ONLY_FID: Only the FID field from the input features will be transferred to the output features. This is the default. NO_FID: All the attributes except the FID from the input features will be transferred to the output features. ALL: All the attributes from the input features will be transferred to the output features.	String

Data types for geoprocessing tool parameters

Script example

import arcgisscripting
gp = arcgisscripting.create()

gp.workspace = "d:/"
gp.toolbox = "cartography"
gp.FeatureOutlineMasks("ParcelsAnno.lyr", "ParcelsAnnoMasks.shp", "1200", "utm17N.prj", "2.000000 Points", "EXACT", "ALL_FEATURES", "ONLY_FID")</scriptExample>

Feature Outline Masks (Cartography) (ArcInfo only)

Command line example

Script example