Skip to main content

Annotation

Summary

An Annotation object allows access to the text graphic of an annotation feature.

Discussion

Annotation objects can be accessed by cursor or by obtaining them from a row defined using the ANNO@ token. They can be created for use with an InsertCursor when the value of an ANNO@ token field is defined before passing into the insertRow method.

Methods

getGraphic(cim_version)

Gets an annotation object's CIM text graphic.

For more information about working with the CIM and samples, see Python CIM access.

Name Explanation Data type

cim_version

A string that represents the major version of the CIM.

  • V2—The 2.x version of the CIM will be used.

  • V3—The 3.x version of the CIM will be used.

When you return an object's CIM definition, you must specify a cim_version parameter value. Esri follows the semantic versioning specification. This means that at major releases (for example, 3.0), breaking API changes are allowed. The cim_version parameter provides control over the version of the CIM that is used, in the possible event of a breaking change in a future version. If you are authoring scripts for ArcGIS Pro 2.x, specify the cim_version as V2. If you are authoring scripts for ArcGIS Pro 3.x, specify the cim_version as V3. Scripts with a + value of V2 will continue to work in ArcGIS Pro 3.x.

String

Return value

Data type Explanation

Object

Returns the CIM graphic of the annotation feature.

setGraphic(definition_object)

Sets an annotation object's CIM text graphic.

For more information about working with the CIM and samples, see Python CIM access.

Name Explanation Data type

definition_object

A modified CIM graphic object originally retrieved using the getGraphic method or created using the arcpy.cim.CreateCIMObjectFromClassName function.

Object

Code sample

Annotation example 1

Use SearchCursor to report information from the text graphic.

import arcpy

infc = "c:/data/fgdb.gdb/anno_fc"

# Enter a for loop for each feature
with arcpy.da.SearchCursor(infc, ['OID@','ANNO@']) as cursor:
    for row in cursor:
        # Access the current annotation feature's object and access the text
        # graphic
        annoObj = row[1]
        cimTextGraphic = annoObj.getGraphic("V3")

        # Print if a text graphic has a leader line
        print(f'Feature {row[0]} has leader: {len(cimTextGraphic.leaders) > 0}')
Annotation example 2

Use UpdateCursor to update a value in the text graphic.

import arcpy

infc = "c:/data/fgdb.gdb/anno_fc_1"

# Enter a for loop for each feature
with arcpy.da.UpdateCursor(infc, ['OID@', 'ANNO@']) as cursor:
    for row in cursor:
        # Access the current annotation feature's object and access the text
        # graphic
        annoObj = row[1]
        cimTextGraphic = annoObj.getGraphic("V3")
        cimTextGraphic.symbol.symbol.underline = True
        annoObj.setGraphic(cimTextGraphic)

        row[1] = annoObj
        cursor.updateRow(row)
Annotation example 3

Use InsertCursor to add a new annotation feature.

import arcpy

# Create components for text symbol
fillRGBColor = arcpy.cim.CreateCIMObjectFromClassName('CIMRGBColor', 'V3')
fillRGBColor.values = [0, 0, 0, 50]

symLyr1 = arcpy.cim.CreateCIMObjectFromClassName('CIMSolidFill', 'V3')
symLyr1.color = fillRGBColor

polySym = arcpy.cim.CreateCIMObjectFromClassName('CIMPolygonSymbol', 'V3')
polySym.symbolLayers = [symLyr1]

# Create the text symbol itself and assign values
textSym = arcpy.cim.CreateCIMObjectFromClassName('CIMTextSymbol', 'V3')
textSym.symbol = polySym
textSym.fontFamilyName = "Arial"
textSym.fontStyleName = "Regular"
textSym.height = 10

infc = "c:/data/fgdb.gdb/anno_fc_1"

flds2ins = ["ANNO@"]
with arcpy.da.InsertCursor(infc, flds2ins) as cursor:
    cimSymbolRef = arcpy.cim.CreateCIMObjectFromClassName('CIMSymbolReference', 'V3')
    cimSymbolRef.symbol = textSym

    # Reference symbol 0, this will allow the symbol to be stored as symbol
    # reference + overrides
    cimSymbolRef.symbolName = "0"
    cimTextGraphic = arcpy.cim.CreateCIMObjectFromClassName('CIMTextGraphic', 'V3')
    cimTextGraphic.symbol = cimSymbolRef
    cimTextGraphic.text = "Test Graphic"

    array = arcpy.Array([arcpy.Point(500000.0, -25.0), arcpy.Point(500000.0, -10.5)])
    spatial_reference = arcpy.SpatialReference(26917)
    cimTextGraphic.shape = arcpy.Polyline(array, spatial_reference)

    annoObj = arcpy.Annotation()
    annoObj.setGraphic(cimTextGraphic)
    cursor.insertRow([annoObj])