CIMSymbol

Since

ArcGIS Maps SDK for JavaScript 4.12

CIMSymbols are high quality, scalable, multi-layer vector symbols for features and graphics. They allow the user to add more customizations to their symbols, using one or more symbol layers to create unique symbols. CIMSymbols can be created from CIMSymbolReference JSON that complies with the CIM specification by passing the JSON to the data property. Not everything in the CIM specification is currently supported in the ArcGIS Maps SDK for JavaScript. The documentation on this page details the current support in the API.

• Symbol and symbol layer types
• Primitive overrides
• Animations

Symbol and symbol layer types

The symbol property in the CIMSymbolReference can be of type CIMPointSymbol, CIMLineSymbol, or CIMPolygonSymbol. Each symbol is made up of one or more symbolLayers. Symbol layers are the building blocks of CIM symbols, they combine to make rich graphical depictions. You can configure the shape, color, texture, size, position, etc of each symbol layer, and combine multiple symbol layers to create your desired symbol. The Symbol Builder provides a simple user interface to experiment with symbol layers and their properties.

All CIMSymbols have at least one symbol layer, but can have more, as outlined in the following table:

Primitive overrides

Primitive overrides allow you to use Arcade expressions to dynamically change many symbol layer properties from attribute values in your data. Primitive overrides are defined on the primitiveOverrides property in the CIMSymbolReference - this property takes in an array of objects, each object representing a primitive override on a specific symbol layer.

const symbol = new CIMSymbol({
 data: {
  type: "CIMSymbolReference",
  primitiveOverrides: [{
    type: "CIMPrimitiveOverride",
    // primitiveName matches the primitiveName on the symbol layer
    primitiveName: "symbol-layer-1",
    propertyName: "Color", // property to be overridden
    valueExpressionInfo: {
      type: "CIMExpressionInfo",
      // colors the symbol layer red if the DailyTraffic is greater than 10,000, orange otherwise
      expression: `IIF($feature.DailyTraffic > 10000, "rgba(255,0,0,1)", "rgba(255,165,0,1)")`,
      returnType: "Default"
    }
  }],
  symbol: {
    type: "CIMLineSymbol",
    symbolLayers: [
     {
       type: "CIMSolidStroke",
       // primitiveName matches the primitiveName on the primitive override
       primitiveName: "symbol-layer-1",
       enable: true,
       // the property to be overridden
       color: [0, 0, 0, 255],
       width: 2
     },
     // other symbol layers
   ]
  }
 }
});

See Primitive overrides for more information.

Animations

Since 4.31

Symbol animations can be used to highlight freshness of data or draw attention to specific features. In CIMSymbol, animations can be defined on the symbol level (global animations) or on the symbol layer level. Global animations are applied to the entire symbol, while symbol layer animations are applied to a specific symbol layer in the symbol. Similar to other symbol properties, animation properties can be overridden based on attribute values using primitive overrides.

The following animation types are supported:

• Color
• Offset
• Rotation
• Scale
• Size
• Transparency

Global animations

Global animations are currently only supported on CIMPointSymbols. They are defined on the animations property of the CIMPointSymbol and are applied to the entire symbol.

const symbol = new CIMSymbol({
 data: {
  type: "CIMSymbolReference",
  symbol: {
    type: "CIMPointSymbol",
    animations: [{ ... }], // global animation applied to the entire symbol
    symbolLayers: [{ ... }],
  }
 }
});

Symbol layer animations

Symbol layer animations are defined on the animations property of the symbol layer and only apply to a specific symbol layer in the symbol. All symbol layer animations are supported on CIMVectorMarker and CIMPictureMarker symbol layers. Color and transparency animations are also supported on CIMSolidFill and CIMSolidStroke symbol layers.

const symbol = new CIMSymbol({
 data: {
  type: "CIMSymbolReference",
  symbol: {
    type: "CIMPointSymbol",
    symbolLayers: [{
     type: "CIMVectorMarker",
     enable: true,
     animations: [{ ... }], // animation applied to this symbol layer
     // other props for the symbol layer
    }]
  }
 }
});

Utility functions for working with CIMSymbol

To get or set the values for color, rotation, and size on the CIMSymbol, use the utility functions found in [cimSymbolUtils](https://developers.arcgis.com/javascript/latest/references/core/symbols/support/cimSymbolUtils/).

The symbolService can be used to create a CIMSymbol from SVG.

See also

• Sample - CIMSymbol

• Sample - CIMSymbol lines and polygons

• Sample - Symbol animations

• Sample - Arrows along a line

• Sample - Adjust marker placement in polygon symbols

• Sample - WebStyleSymbols (2D)

• Symbol Builder

• Guide - WebStyleSymbol reference list

• ArcGIS Blog - Create points, lines, and polygons using CIMSymbols

• ArcGIS Blog - Visualize electoral swing using composite symbols

• Presentation - ArcGIS Maps SDK for JavaScript: Dynamic Vector Symbology

• WebStyleSymbol

• cimSymbolUtils

• symbolService