Rule files for masking

Available with an ArcGIS Topographic Mapping license.

Predefined XML masking rule files that can be used for cartographic production are included in a product data file installer for ArcGIS Topographic Mapping product files.

The XML files define the rules that decide how polygon masks are created based on matching colors.

The following XML example demonstrates the basic structure of a rule file:

<?xml version="1.0" encoding="utf-8"?>
<ColorRules>
 <MaskFeatureClasses>
  <SourceFields>
   <Field type="esriFieldTypeString" length="255">MapId_Txt</Field>
  </SourceFields>
  <TargetFields>
   <Field type="esriFieldTypeString" length="255">F_CODE</Field>
  </TargetFields>
  <MaskFeatureClass>
   <Name>AnnoMasks_NonBlack</Name>
   <LayerName>NonBlack Masks</LayerName>
   <OverwriteOutput>DeleteAndAppend</OverwriteOutput>
   <AddToMap>False</AddToMap>
  </MaskFeatureClass>
 </MaskFeatureClasses>
 <RuleGroup>
  <Mask Size=".2" Units="Millimeters" Type="Exact_Simplified" Simplify=".05"/>
  <Source SymbolPart="Text_Only" LayerType="AnnotationLayer" ColorSpace="CMYK"/>
  <Target SymbolPart="Outline_Only" LayerType="FeatureLayer" ColorSpace="CMYK"/>
  <TargetExclusions></TargetExclusions>
  <SourceExclusions></SourceExclusions>
  <Rules>
   <Rule Name="NonBlack_2mm">
    <MaskFeatureClass>
     AnnoMasks_NonBlack
    </MaskFeatureClass>
    <Source Color="100,20,30,0"/>
    <Targets GeometryType="line,polygon">
     <Target Color="100,20,30,0"/>
     <Target Color="0,0,0,100" />
    </Targets>
    <TargetExclusions>
     ContourL,SEG*
    </TargetExclusions>
   </Rule>
  </Rules>
 </RuleGroup>
</ColorRules>

MaskFeatureClasses element

The optional MaskFeatureClasses element is a child element of the ColorRules element. Using the MaskFeatureClasses element, you can define properties for the feature classes that contain the mask polygons. If MaskFeatureClasses is not defined, you can use the Make Masks From Rules tool to create mask feature classes using the default schema.

The following table contains details for the MaskFeatureClasses element:

MaskFeatureClasses

Element	Details
SourceFields	Specifies attributes from the source feature found by a given rule that will be included in the final mask feature class.
TargetFields	Specifies attributes from the target feature found by a given rule that will be included in the final mask feature class.
Field	This element has a type attribute that takes the string value of the esriFieldType enumeration. If a string field is used, the length attribute should match the length of the geodatabase field. Note: The length attribute is only for a string field.
MaskFeatureClass	The section below contains details about the MaskFeatureClass element.

Note:

The fields specified in SourceFields and TargetFields should exist on all layers in the map. The field name is prefixed with Source_ or Target_ in the final mask feature class. If the rule file is configured to append masks to an existing feature class, SourceFields and TargetFields must already exist on the feature class. The Make Masks From Rules tool does not modify the schema of an existing feature class.

MaskFeatureClass element

The MaskFeatureClass child element defines a feature class that contains mask polygons. You can define as many of the MaskFeatureClass elements as necessary. The SourceFields and TargetFields elements apply to all MaskFeatureClass elements defined in MaskFeatureClasses.

The following table contains details for the MaskFeatureClass element:

MaskFeatureClass

Element	Details
Name	The name of the feature class. Use this name to reference the feature class in a Rule element.
LayerName	The layer name that will be used when adding the mask feature class to the map as a layer. If you don't provide a name, <Name> will be used as the layer name.
OverwriteOutput	Specifies whether the output will be overwritten. The options are as follows: GPEnvironment—The Overwrite output datasets option will be honored. Overwrite—Mask feature classes will be overwritten. This is the default. Append—Data will be appended to the mask feature class output. DeleteAndAppend—Features based on the layers, selection, or definition query of the layer of the mask feature class on the map will be deleted, and new masks will be appended to the output mask feature class.
AddToMap	Specifies whether the mask feature class will be added to the map as a layer. The options are as follows: GPEnvironment—The Add output to map option will be honored. True—The mask feature class will be added as a layer to the map. False—The mask feature class will not be added as a layer to the map. Replace—If the layer exists on the map, it will be replaced. This is the default. IfNotExists—If the layer does not exist on the map, the mask feature class will be added as a layer.

RuleGroup element

Elements defined at the RuleGroup level apply to all Rule elements in the RuleGroup element unless a Rule element overrides it by specifying a different value.

The following RuleGroup example defines an Exact Simplified mask with a size of .2 millimeters. It defines the common Source and Target element attributes of SymbolPart, LayerType and ColorSpace that likely apply to most Rule elements in the group.

<RuleGroup>
 <Mask Size=".2" Units="Millimeters" Type="Exact_Simplified" Simplify=".05"/>
 <Source SymbolPart="Text_Only" LayerType="AnnotationLayer" ColorSpace="CMYK"/>
 <Target SymbolPart="Outline_Only" LayerType="FeatureLayer" ColorSpace="CMYK"/>
</RuleGroup>

Rule element

The attributes in the following Rule element example override values specified in attributes defined in a RuleGroup element. This example overrides mask size and mask type attribute values in the aforementioned RuleGroup example. The source also matches feature layers instead of annotation layers, and the fill symbol in the RGB color space is now targeted.

<Rule>
 <Mask Size=".5" Units="Millimeters" Type="Convex_Hull" Style="BufferFeature"/>
 <Source Color="100,20,30,0 LayerType=”FeatureLayer"/>
 <Targets>
  <Target Color="198,59,59" ColorSpace=”RGB” SymbolPart=”Fill_Only”/>
 </Targets>
</Rule>

Mask element attributes

The following table contains details for the Mask element attributes:

Mask element attributes

Attribute	Details
Size	The size of the mask that will be created.
Units	Specifies the size units. The following values are valid: Centimeters, Decimal degrees, Decimeters, Feet, Inches, Kilometers, Meters, Miles, Millimeters, Nautical Miles, Points, and Yards.
Type	Specifies the type of mask. The following values are valid: Convex_Hull, Box, Exact_Simplified, and Exact.
Simplify	The simplification tolerance on the resulting masks. This attribute is not required.
Style	Specifies whether source and target features will be buffered or intersection masks will be buffered. This can help improve performance, particularly in scenarios with dense features. Values: BufferMask—Intersection mask polygons will be buffered. Source and target features will not be buffered. BufferFeature—Source and target features will be buffered, and intersections will be identified. Note: The Style attribute can be added at the parent level in the RuleGroup element or at the child level in the Rule element.

The following table contains details for the elements and attributes of a Rule element:

Element attributes

Element or attribute	Details
Color	The color that will be used to match in the layer symbol. This is a comma-separated set of numbers that correspond to the ColorSpace value. For example, if the RGB value is used for ColorSpace, 255, 0, 0 would be used to match a red symbol. Alternatively, when an asterisk is placed in the Color attribute (<Source Color="*"/>), colors are ignored and other attributes, such as SymbolPart and LayerNames, are honored.
ColorSpace	The color model that will be used. You can define this at the RuleGroup level and apply it to all of the rules in the group. The following values are valid: CMYK, RBG, HSV, HSL, LAB, Gray, and SPOT.
SymbolPart	Specifies the symbol part in the symbolized layer that will be used when matching the color. The following values are valid: All_Parts, Outline_Only, Fill_Only, and Text_Only.
LayerType	Specifies the types of layers that will be included when matching a color. The following values are valid: Annotationlayer and FeatureLayer.
GeometryType	Specifies the comma-delimited list of geometry types to which a layer applies. If no value is specified, all geometry types will match. The following values are valid: point, line, and polygon. This attribute can be an applied to the Source, Target, or Targets elements.
LayerNames	The comma-delimited list of layer names that will be matched. The source or target color only matches using these layers. If no value is specified, all layers will match. This attribute can be applied to the Source, Target, or Targets elements.
Query	The Where clause that further refines which features the Source or Target elements match. The following is an example: <Source LayerNames="ATSRoute_C_A" Query="ANNOTATIONCLASSID IN (0, 3, 4,8, 9, 10, 11, 12, 13)"/>
Targets	The Target elements that the Source element will match.
TargetExclusions	The target layers that will be excluded when matching source layers to target layers. Layers that you provide will not have a mask created or applied. A comma-delimited list of layer names is valid. This attribute is optional.
SourceExclusions	The source layers that will be excluded from the masking rule. Layers that you provide will not have a mask created or applied. A comma-delimited list of layer names is valid.
AltColor	The alternate color that will be used to match in the layer symbol. This is a comma-separated set of numbers that correspond to the value set by the AltColorSpace value. For example, if the CYMK value is used for AltColorSpace, 100, 100, 0, 0 would be used to match a blue symbol.
ColorName	The name of the color in the feature's symbology.
OutlineOptions	Specifies how marker fill within a polygon is masked. For example, RemoveMarkerInside helps reduce the amount of features and vertices that need to be created by masking inner markers as a group rather than individually. Other options include: None—No marker fill mask will be applied. RemoveDashes—Dashes will be modified with an empty pattern. MarkerAlongAsThickStroke—If a marker is placed along a stroke or line, they are replaced with a stroke or line.

Wildcards

Wildcards can be used in the following elements and attributes: LayerNames, TargetExclusions, and SourceExclusions. The following table provides details for the wildcard symbols:

Symbol	Name	Details
*	Asterisk	Including an asterisk in a value matches any number of characters. For example, wh* matches values such as what, white, and why, but not awhile or watch.
?	Question mark	Including a question mark in a value matches any single character in the position of the question mark. For example, b?ll matches values such as ball, bell, and bill.
[ ]	Brackets	Including brackets in a value matches the same characters specified between the brackets. For example, b[ae]ll matches values such as ball and bell, but not bill. You can use a hyphen to specify a character range such as [a-z].
^	Caret	Using a caret inside of brackets excludes characters. For example, b[^ae]ll matches bill and bull, but not ball or bell. You can combine wildcard symbols. For example, [^a]* matches all items that do not begin with the letter a.
#	Pound	Including a pound symbol in a value matches a single numeric character in the position of the pound symbol. For example, 1#3 matches values such as 103, 113, and 123.