Rule files for masking

Available with Production Mapping license.

Predefined XML masking rule files that can be used for cartographic production and are included in a product file installer available for ArcGIS Production Mapping and ArcGIS Defense Mapping.

Learn more about Defense Mapping product files and Production Mapping product files.

The XML files define the rules that determine 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, then the Masks From Rules tool creates mask feature classes using the default schema.

The following table contains additional details on the MaskFeatureClasses element.

MaskFeatureClasses

Element	Details
SourceFields	You can specify attributes from the source feature found by a given rule that should be included in the final mask feature class.
TargetFields	You can specify attributes from the target feature found by a given rule that should be included in the final mask feature class.
Field	This element has a type attribute that takes the string value of 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.

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 into an existing feature class, SourceFields and TargetFields must already exist on the feature class. The Masks From Rules tool does not modify the schema of an existing feature class.

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 apply to all MaskFeatureClass elements defined in MaskFeatureClasses.

The following table contains more details on 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	This element specifies what layer name to use when adding the mask feature class to the map as a layer. If you don't specify a name, then <Name> is used as the layer name.
OverwriteOutput	This element can have these values: GPEnvironment—Indicates that the tool should honor the Overwrite output datasets option. Overwrite—Indicates that the tool should always overwrite mask feature classes. This is the default. Append—Indicates that the tool should append data to the mask feature class output. DeleteAndAppend—Indicates that the tool should search for the layer of the mask feature class on the map and delete features based on the layers, selection or definition query. Then it should append new masks to the output mask feature class.
AddToMap	This element indicates if the mask feature class should be added to the map as a layer. The following are options for this element: GPEnvironment—Indicates that the tools should honor the Add output to map option. True—Indicates that the tool should add the mask feature class as a layer to the map. False—Indicates that the tool should not add the mask feature class as a layer to the map. Replace—Indicates that the tool should replace the layer on the map if it exists. This is the default. IfNotExists—Indicates that the tool should add the mask feature class as a layer if one does not already exist.

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 would override values specified in attributes defined in a RuleGroup element. This example would override 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 are now targeted.

<Rule>
 <Mask Size=".5" Units="Millimeters" Type="Convex_Hull"/>
 <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 further details on Mask element attributes.

Mask element attributes

Attribute	Details
Size	The size of the mask that will be created.
Units	The following values are valid: Centimeters, Decimal degrees, Decimeters, Feet, Inches, Kilometers, Meters, Miles, Millimeters, Nautical Miles, Points, Yards
Type	The following values are valid: Convex_Hull, Box, Exact_Simplified, Exact
Simplify	Defines the simplification tolerance on the resulting masks. This attribute is not required.

The following table contains further details on the elements and attributes of a Rule element.

Element attributes

Element / Attribute	Details
Color	The color to match in the layer symbol. This is a comma-separated set of numbers that are defined by the ColorSpace value specified. For example, if RGB is defined, then to match a red symbol the values 255, 0, 0 would be used. 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 used. You can define this at the RuleGroup level and have it apply to all of the rules in the group. The following values are valid: CMYK, RBG, HSV, HSL, LAB, Gray, SPOT.
SymbolPart	Specifies the symbol part in the symbolized layer to use when matching the color. The following values are valid: All_Parts, Outline_Only, Fill_Only, Text_Only.
LayerType	Specifies the types of layers to include when matching a color. The following values are valid: Annotationlayer, FeatureLayer.
GeometryType	The comma delimited list of geometry types to which a layer applies. If it is not specified, all geometry types will match. The following values are valid: point, line, polygon. This attribute can be an applied to the Source, Target, or Targets elements.
LayerNames	The comma delimited list of layer names to match. The source or target color only matches against these layers. If it is not specified, all layers will match. This attribute can be an applied to the Source, Target, or Targets elements.
Query	An attribute that allows a Where clause that further refines which features the Source or Target match. The following is an example: <Source LayerNames="ATSRoute_C_A" Query="ANNOTATIONCLASSID IN (0, 3, 4,8, 9, 10, 11, 12, 13)"/>
Targets	Identifies all of the Target elements that the Source should match.
TargetExclusions	Optionally, specifies the target layers to exclude when matching source layers to target layers. Layers that you include here will not have a mask created or applied. A comma delimited list of layer names is valid.
SourceExclusions	This attribute specifies the source layers to exclude from the masking rule. Layers that you include here will not have a mask created or applied. A comma delimited list of layer names is valid.

Wildcards

Wildcards can be used in the following elements and attributes: LayerNames, TargetExclusions, SourceExclusions. The following table provides additional details on 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 you specify between the brackets. For example, b[ae]ll matches values such as ball and bell, but not bill. A hyphen can be used 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.