Dimensions and Constraints

Permanent dimensions and dimension related constraints.

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.

Manipulating Dimension Text

Dimension and DimensionSegment classes provide similar properties and methods for querying and adjusting the position of the text relative to the dimension curve.

Dimension.Origin returns the XYZ value of the midpoint of the dimension curve, with DimensionSegment.Origin will return the midpoint of the line that makes up the segment.

Determine if text position of a Dimension or DimensionSegment is adjustable by calling the method IsTextPositionAdjustable() which will indicate whether the text and leader positions may be set.

Query or modify the position of text or the leader (of a dimension or dimension segment) by using the properties TextPosition and LeaderEndPosition.

Reset the text to its default position on a dimension by calling the method ResetTextPosition().

Note: TextPosition and LeaderEndPosition are not necessarily applicable to all dimensions (e.g., spot dimensions, multi-segment dimensions using the equality constraint, when dimension style is ordinate). If these values are not applicable they will return Null and not allow setting a value.

Code Region: Reposition dimension text 

// Moves all of the text in this dimension one unit in the Y direction
public bool DimensionTextReposition(Dimension dimToModify)
{
    bool modified = false;
    if (dimToModify == null)
        return false;

    // Check to see if we have a non-multisegment dimension and if text position is adjustable
    if (dimToModify.NumberOfSegments == 0 && dimToModify.IsTextPositionAdjustable())
    {
        // Get the current text XYZ position
        XYZ currentTextPosition = dimToModify.TextPosition;
        // Calculate a new XYZ position by transforming the current text position
        XYZ newTextPosition = Transform.CreateTranslation(new XYZ(0.0, 1.0, 0.0)).OfPoint(currentTextPosition);
        // Set the new text position
        dimToModify.TextPosition = newTextPosition;

        modified = true;
    }
    else if (dimToModify.NumberOfSegments > 0)
    {
        foreach (DimensionSegment currentSegment in dimToModify.Segments)
        {
            if (currentSegment != null && currentSegment.IsTextPositionAdjustable())
            {
                modified = true;
                // Get the current text XYZ position
                XYZ currentTextPosition = currentSegment.TextPosition;
                // Calculate a new XYZ position by transforming the current text position
                XYZ newTextPosition = Transform.CreateTranslation(new XYZ(0, 1, 0)).OfPoint(currentTextPosition);
                // Set the new text position for the segment's text
                currentSegment.TextPosition = newTextPosition;
            }
        }
    }
    return modified;
}
Parent topic: Annotation Elements