ProConcepts Dimensions

Functionality that uses the fine-grained Dimension API. Dimension API functionality is found in ArcGIS.Core.dll. The Dimension API is commonly used in conjunction with geodatabase, map authoring, and editing.

ArcGIS.Core.dll

Language:      C#
Subject:       Dimensions
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          10/06/2024
ArcGIS Pro:    3.4
Visual Studio: 2022

In this topic

• Architecture
• Dimension feature class
  • Dimension feature class definition
• Dimension feature
• Additional References

Architecture

• The ArcGIS.Core.Data.Mapping API for dimensions builds upon the ArcGIS.Core.Data API and a solid understanding of ArcGIS.Core.Data API concepts is recommended.
• Schema creation and modification operations such as creating tables and feature classes, creating and modifying fields, enabling attachments, and so on are not currently supported in the ArcGIS.Core.Data.DLL API for dimensions. This means that all these operations need to be performed using the Geoprocessing API or the user interface of ArcGIS Pro.
• Almost all of the methods in the ArcGIS.Core.Data.Mapping API should be called on the MCT. The triple-slash documentation on the methods that need to run on the MCT are specified as such. These method calls should be wrapped inside the QueuedTask.Run call. Failure to do so will result in ConstructedOnWrongThreadException being thrown.

Dimension feature class

Dimension feature classes are collections of text features with a common set of attribute columns and class level properties. The class level properties store draw related information like the reference scale and assist in minimizing data size by offering a shared collection of dimension styles that features may reference. In ArcGIS Pro, the dimension API is designed for use with dimension feature classes that have been upgraded to the new dimension model introduced for ArcGIS Pro.

In the ArcGIS.Core.Data.Mapping API, the DimensionFeatureClass class inherits from the FeatureClass class. Obtaining DimensionFeatureClass objects is similar to obtaining FeatureClass objects as shown in the following examples:

• From the Geodatabase object:

using (DimensionFeatureClass dimFeatureClass = 
        geodatabase.OpenDataset<DimensionFeatureClass>("DimensionFeatureClassName"))
{
}

In the case of a Geodatabase object representing a FeatureService, the OpenDataset can be called with the string representation of the ID for the dimension feature class.

using (DimensionFeatureClass dimFeatureClass = 
                    geodatabase.OpenDataset<DimensionFeatureClass>("1"))
{
}

• From the DimensionLayer object:

ArcGIS.Desktop.Mapping.Layer selectedLayer = MapView.Active.GetSelectedLayers().FirstOrDefault();
if (selectedLayer is ArcGIS.Desktop.Mapping.DimensionLayer)
{
  using (Table table = (selectedLayer as DimensionLayer).GetTable())
  {
    if (table is DimensionFeatureClass)
    {
      DimensionFeatureClass dimFeatureClass = table as DimensionFeatureClass;
    }
  }
}

• From the DimensionFeature object:

ArcGIS.Desktop.Editing.Events.RowChangedEvent.Subscribe(args =>
{
  Row row = args.Row;

  if (row is DimensionFeature)
  {
    using (DimensionFeatureClass dimFeatureClass = row.GetTable() as DimensionFeatureClass)
    {
    }
  }
}

Opening DimensionFeatureClass as a table

You can open a DimensionFeatureClass object using the following code:

using (Table table = geodatabase.OpenDataset<Table>("FeatureClassName"))
{
}

The table is an ArcGIS.Core.Data.Table reference, but in reality, it's an ArcGIS.Core.Data.Mapping.DimensionFeatureClass object. You could cast the table reference as an DimensionFeatureClass, and the cast would work as expected.

Opening DimensionFeatureClass as a feature class

You can open a DimensionFeatureClass object using the following code:

using (FeatureClass featureClass = geodatabase.OpenDataset<FeatureClass>("FeatureClassName"))
{
}

The featureClass is an ArcGIS.Core.Data.FeatureClass reference, but in reality, it's an ArcGIS.Core.Data.Mapping.DimensionFeatureClass object. You could cast the featureClass reference as an DimensionFeatureClass, and the cast would work as expected.

Dimension feature class definition

Dimension feature classes have their own Definition object, DimensionFeatureClassDefinition, which provides access to properties unique to the DimensionFeatureClass. DimensionFeatureClassDefinition inherits from FeatureClassDefinition to provide access to general properties of the feature class but adds the dimension specific properties. The additional dimension specific properties include reference scale, reference scale unit, and the dimension styles.

• Opening an DimensionFeatureClassDefinition from a Geodatabase. A definition object contains metadata information about the dataset and is typically used when it is not anticipated that the dataset will be opened.

DimensionFeatureClassDefinition definition = geodatabase.GetDefinition<DimensionFeatureClassDefinition>("DimensionFeatureClassName");

• Opening the DimensionFeatureClassDefinition from the dataset. Use this when the dataset is already open and the reference is accessible.

ArcGIS.Desktop.Mapping.Layer selectedLayer = MapView.Active.GetSelectedLayers().FirstOrDefault();
if (selectedLayer is ArcGIS.Desktop.Mapping.DimensionLayer)
{
  using (DimensionFeatureClass dimFC = (selectedLayer as DimensionLayer).GetTable() as DimensionFeatureClass)
  {
    DimensionFeatureClassDefinition definition = dimFC.GetDefinition();
  }
}

Dimension feature

When working with an dimension feature class, the features returned via queries are of type DimensionFeature. DimensionFeature extends the capabilities of Feature with dimension-specific functionality. Primarily, it provides access to the CIMDimensionShape and additional display related options in the dimension feature. Unlike a regular Feature, the Shape of an DimensionFeature is not routinely updated via GetShape and SetShape. Instead, the DimensionFeature manages the shape when the CIMDimensionShape and other display properties of the dimension feature are updated. The Shape is set to be a polygon derived from the drawn Dimension. The CIMDimensionShape defines the location of the dimension feature via the BeginDimensionPoint, EndDimensionPoint, the DimensionLinePoint, and optionally the TextPoint. Any changes to the position of the dimension feature are done by modifying the CIMDimensionShape.

Additionally the DimensionFeature provides Set and Get methods for the DimensionExtensionOption, DimensionLineOption, DimensionsMarkerOption, DimensionType, StyleID, CustomLength, and UseCustomLength. These properties, along with the values in the DimensionShape are stored in field values in the DimensionFeature. It is important to keep the field schema in mind when dealing with dimensions. Dimension feature classes are created with a series of fields that are used to persist the feature information. These field are created for new dimension feature classes and are required. These fields are DIMLENGTH, BEGINX, BEGINY, ENDX, ENDY, DIMX, DIMY, TEXTX, TEXTY, EXTANGLE, STYLEID, USECUSTOMLENGTH, CUSTOMLENGTH, DIMDISPLAY, EXTDISPLAY, MARKERDISPLAY, TEXTANGLE along with the system ObjectID and Shape fields. Updating the DimensionFeature via CIMDimensionShape or other dimension specific properties will update a field in the row corresponding to the property. Likewise, updating the field value will update the DimensionFeature, but the API provides an easier type safe approach for updating the values. Note that coordinate positions stored in these fields are all in the native coordinate system of the feature class.

Opening a cursor on a DimensionFeatureClass and making updates to the DimensionFeature is demonstrated below. Note that this example changes the DimensionExtensionOption using the DimensionPartOptions enumeration.

QueryFilter qf = new QueryFilter();
qf.WhereClause = "OBJECTID < 100";
//Note: this is a non-recycling cursor off the Table, ~not~ the layer
using (RowCursor rowCursor = featureClass.Search(qf, false))
{
  geodatabase.ApplyEdits(() =>
  {
    while (rowCursor.MoveNext())
    {
      using (DimensionFeature dimFeat = rowCursor.Current as DimensionFeature)
      {
        dimFeat.SetDimensionExtensionOption(DimensionPartOptions.None);
        dimFeat.Store();
      }
    }
  });
}

Using a RowBuffer and creating a new DimensionFeature in a DimensionFeatureClass is demonstrated below. The CIMDimensionShape is created from three points for position and initialization of other properties. The dimension style is referenced by ID. Additional properties may be set on the DimensionFeature as needed to customize the appearance such as a custom text point or Dimension line, marker, or extension options.

static void InsertDimensions(MapPoint beginPoint, MapPoint linePoint, MapPoint endPoint, int styleID, DimensionFeatureClass featureClass)
{
  //Create the row buffer
  using (RowBuffer rowBuffer = featureClass.CreateRowBuffer())
  {
    Feature feature = featureClass.CreateRow(rowBuffer) as Feature;

    DimensionFeature dimFeat = feature as DimensionFeature;

    var dimensionShape = new CIMDimensionShape();
    dimensionShape.BeginDimensionPoint = beginPoint;
    dimensionShape.DimensionLinePoint = linePoint;
    dimensionShape.EndDimensionPoint = endPoint;
    dimensionShape.TextPoint = MapPointBuilderEx.CreateMapPoint(); //empty point
    dimensionShape.ExtensionLineAngle = Math.PI * 90 / 180.0; //90 degrees in radians

    dimFeat.SetDimensionType(DimensionType.Aligned);
    dimFeat.SetStyleID(styleID);
    dimFeat.SetDimensionShape(dimensionShape);
    feature.Store();
  }
}

Additional References

Refer to ProConcepts Editing Dimensions for additional reference information relevant for dimension editing customizations.