What is arcpy.cim?

GraemeBrowning

In the help for ArcGIS Pro 2.4's Python CIM access there is "Example 3: Modify layer symbology" which has this code:

    # Reference a project, map, and layer using arcpy.mp
    p = arcpy.mp.ArcGISProject('current')
    m = p.listMaps('Trail Routes')[0]
    lyr = m.listLayers('Loops')[0]
   
    # Return the layer's CIM definition
    cim_lyr = lyr.getDefinition('V2')
   
    # Modify the color, width and dash template for the SolidStroke layer
    symLvl1 = cim_lyr.Renderer.Symbol.Symbol.SymbolLayers[0]
    symLvl1.Color.Values = [250, 250, 40, 50]
    symLvl1.Width = 8
    ef1 = symLvl1.Effects[0]    #Note, deeper indentation
    ef1.DashTemplate = [20, 30]
   
    # Modify the color/transparency for the SolidFill layer
    symLvl2 = cim_lyr.Renderer.Symbol.Symbol.SymbolLayers[1]
    symLvl2.Color.Values = [140, 70, 20, 20]
   
    # Push the changes back to the layer object
    lyr.setDefinition(cim_lyr)

I think the documentation was written before finalization of ArcGIS Pro 2.4, where this functionality was introduced for the first time, because it seems to contain capitalization errors, and is missing a key line that I picked up by watching a YouTube video from Esri's 2019 Developer Summit.

This code should work correctly:

    # Reference a project, map, and layer using arcpy.mp
    p = arcpy.mp.ArcGISProject('current')
    m = p.listMaps('Trail Routes')[0]
    lyr = m.listLayers('Loops')[0]
   
    # Return the layer's CIM definition
    cim_lyr = lyr.getDefinition('V2')
   
    # Modify the color, width and dash template for the SolidStroke layer
    symLvl1 = cim_lyr.renderer.symbol.symbol.symbolLayers[0]
    symLvl1.color.values = [250, 250, 40, 50]
    symLvl1.width = 8
    symLvl1.effects = [arcpy.cim.CIMGeometricEffectDashes()]
    ef1 = symLvl1.effects[0]    #Note, deeper indentation
    ef1.dashTemplate = [20, 30]
   
    # Modify the color/transparency for the SolidFill layer
    symLvl2 = cim_lyr.renderer.symbol.symbol.symbolLayers[1]
    symLvl2.color.values = [140, 70, 20, 20]
   
    # Push the changes back to the layer object
    lyr.setDefinition(cim_lyr)

The missing line (which I added in the above) is:

    symLvl1.effects = [arcpy.cim.CIMGeometricEffectDashes()]

Is `arcpy.cim` an undocumented ArcPy module, function or class, and to learn about it, is reading the ArcGIS.Core.CIM Namespace .NET SDK API Reference the only way?

I have reported what I believe to be the documentation error using the link at the bottom of that help page.  I have also asked this question on another site as symbology - What is arcpy.cim? - Geographic Information Systems Stack Exchange.

jbarrette

Thank you for reporting this!  You are correct; late in 2.4 development we changed the CamelBack format of the object members to be consistent with the managed API.  I failed to update example 3 and you caught it.  The script was corrected and will appear in the next help publication.

The missing line that you added is NOT required if the symbol already has a dashed effect.  What the line did essentially was generate the effect.  This is something you need to be very careful about doing.  The Developer Summit plenary video does show the line you added.  That particular example is a simple use case but due to the complexity of object creation where new objects have dependencies on addition objects, it is easy to create objects that may fail in the application.

The arcpy.cim module is necessary for CIM support but we intentionally did not document it.  We hope that with future builds we will provide helper functions that will make it easier and more reliable to create new objects.

Thanks again,

Jeff