Dimensions and Constraints

The Dimension class represents permanent dimensions and dimension related constraint elements. Temporary dimensions created while editing an element in the UI are not accessible. Spot elevation and spot coordinate are represented by the SpotDimension class.

The following code sample illustrates, near the end, how to distinguish permanent dimensions from constraint elements.

Code Region 16-1: Distinguishing permanent dimensions from constraints

public void GetInfo_Dimension(Dimension dimension)
{
    string message = "Dimension : ";
    // Get Dimension name
    message += "\nDimension name is : " + dimension.Name;

    // Get Dimension Curve
    Autodesk.Revit.DB.Curve curve = dimension.Curve;
    if (curve != null && curve.IsBound)
    {
        // Get curve start point
        message += "\nCurve start point:(" + curve.GetEndPoint(0).X + ", "
                + curve.GetEndPoint(0).Y + ", " + curve.GetEndPoint(0).Z + ")";
        // Get curve end point
        message += "; Curve end point:(" + curve.GetEndPoint(1).X + ", "
                + curve.GetEndPoint(1).Y + ", " + curve.GetEndPoint(1).Z + ")";
    }

    // Get Dimension type name
    message += "\nDimension type name is : " + dimension.DimensionType.Name;

    // Get Dimension view name
    message += "\nDimension view name is : " + dimension.View.Name;

    // Get Dimension reference count
    message += "\nDimension references count is " + dimension.References.Size;

    if ((int)BuiltInCategory.OST_Dimensions == dimension.Category.Id.IntegerValue)
    {
        message += "\nDimension is a permanent dimension.";
    }
    else if ((int)BuiltInCategory.OST_Constraints == dimension.Category.Id.IntegerValue)
    {
        message += "\nDimension is a constraint element.";
    }


    TaskDialog.Show("Revit",message);
}

Dimensions

There are five kinds of permanent dimensions:

Linear dimension
Radial dimension
Diameter Dimension
Angular dimension
Arc length dimension

Figure 66: Permanent dimensions

The BuiltInCategory for all permanent dimensions is OST_Dimensions. There is not an easy way to distinguish the four dimensions using the API.

Except for radial and diameter dimensions, every dimension has one dimension line. Dimension lines are available from the Dimension.Curve property which is always unbound. In other words, the dimension line does not have a start-point or end-point. Based on the previous picture:

A Line object is returned for a linear dimension.
An arc object is returned for a radial dimension or angular dimension.
A radial dimension returns null.
A diamter diimension returns null.

Figure 67: Dimension references

A dimension is created by selecting geometric references as the previous picture shows. Geometric references are represented as a Reference class in the API. The following dimension references are available from the References property. For more information about Reference, please see Reference in the Geometry section.

Radial and diameter dimensions - One Reference object for the curve is returned
Angular and arc length dimensions - Two Reference objects are returned.
Linear dimensions - Two or more Reference objects are returned. In the following picture, the linear dimension has five Reference objects.

Figure 68: Linear dimension references

Dimensions, like other Annotation Elements, are view-specific. They display only in the view where they are added. The Dimension.View property returns the specific view.

Constraint Elements

Dimension objects with Category Constraints (BuitInCategory.OST_Constraints) represent two kinds of dimension-related constraints:

Linear and radial dimension constraints
Equality constraints

In the following picture, two kinds of locked constraints correspond to linear and radial dimension. In the application, they appear as padlocks with green dashed lines. (The green dashed line is available from the Dimension.Curve property.) Both linear and radial dimension constraints return two Reference objects from the Dimension.References property.

Figure 69: Linear and Radial dimension constraints

Constraint elements are not view-specific and can display in different views. Therefore, the View property always returns null. In the following picture, the constraint elements in the previous picture are also visible in the 3D view.

Figure 70: Linear and Radial dimension constraints in 3D view

Although equality constraints are based on dimensions, they are also represented by the Dimension class. There is no direct way to distinguish linear dimension constraints from equality constraints in the API using a category or DimensionType. Equality constraints return three or more References while linear dimension constraints return two or more References.

Figure 71: Equality constraints

Note: Not all constraint elements are represented by the Dimension class but all belong to a Constraints (OST_Constraints) category such as alignment constraint.

Spot Dimensions

Spot coordinates and spot elevations are represented by the SpotDimension class and are distinguished by category. Like the permanent dimension, spot dimensions are view-specific. The type and category for each spot dimension are listed in the following table:

Table 35: Spot dimension Type and Category

Type	Category
Spot Coordinates	OST_SpotCoordinates
Spot Elevations	OST_SpotElevations

Figure 72: SpotCoordinates and SpotElevations

The SpotDimension Location can be downcast to LocationPoint so that the point coordinate that the spot dimension points to is available from the LocationPoint.Point property.

SpotDimensions have no dimension curve so their Curve property always returns null.
The SpotDimension References property returns one Reference representing the point or the edge referenced by the spot dimension.
To control the text and tag display style, modify the SpotDimension and SpotDimensionType Parameters.

Comparison

The following table compares different kinds of dimensions and constraints in the API:

Table 36: Dimension Category Comparison

Dimension or Constraint	Dimension or Constraint	API Class	*BuiltInCategory*	*Curve*	*Reference*	*View*	*Location*
Permanent Dimension	linear dimension	Dimension	OST_Dimensions	A Line	=2	Specific view	null
Permanent Dimension	radial dimension	Dimension	OST_Dimensions	Null	1	Specific view	null
Permanent Dimension	diameter dimension	Dimension	OST_Dimensions	Null	1	Specific view	null
Permanent Dimension	angular dimension	Dimension	OST_Dimensions	An Arc	2	Specific view	null
Permanent Dimension	arc length dimension	Dimension	OST_Dimensions	An Arc	2	Specific view	null
Dimension Constraint	linear dimension constraint	Dimension	OST_Constraints	An Arc	2		null
Dimension Constraint	angular dimension	Dimension	OST_Constraints	An Arc	2		null
Equality Constraint	Equality Constraint	Dimension	OST_Constraints	A Line	=3		null

Create and Delete

The NewDimension() method is available in the Creation.Document class. This method can create a linear dimension only.

Code Region 16-2: NewDimension()

public Dimension NewDimension (View view, Line line, ReferenceArray references)

public Dimension NewDimension (View view, Line line, ReferenceArray references, 
DimensionType dimensionType)

Using the NewDimension() method input parameters, you can define the visible View, dimension line, and References (two or more). However, there is no easy way to distinguish a linear dimension DimensionType from other types. The overloaded NewDimension() method with the DimensionType parameter is rarely used.

The following code illustrates how to use the NewDimension() method to duplicate a dimension.

Code Region 16-3: Duplicating a dimension with NewDimension()

public void DuplicateDimension(Document document, Dimension dimension)
{
        Line line = dimension.Curve as Line;
        if (null != line)
        {
                Autodesk.Revit.DB.View view = dimension.View;
                ReferenceArray references = dimension.References;
                Dimension newDimension = document.Create.NewDimension(view, line, references);
        }
}

Though only linear dimensions are created, you can delete all dimensions and constraints represented by Dimension and SpotDimension using the Document.Delete() method.