Creates empty analysis results primitive associated with a face and a transform.

Namespace: Autodesk.Revit.DB.Analysis
Assembly: RevitAPI (in RevitAPI.dll) Version: 23.0.0.0 (23.1.0.0)
Since: 2011

Syntax

C#
public int AddSpatialFieldPrimitive( Face face, Transform trf )

Visual Basic
Public Function AddSpatialFieldPrimitive ( _ face As Face, _ trf As Transform _ ) As Integer

Visual C++
public: int AddSpatialFieldPrimitive( Face^ face, Transform^ trf )

Parameters

face: Type: Autodesk.Revit.DB..::..Face
Face to be associated with the primitive

trf: Type: Autodesk.Revit.DB..::..Transform
Conformal Transform to be applied to %face%

Return Value

Unique index of primitive for future references

Remarks

This method accepts a reference to a model face, and a transform to be applied to that face, allowing the display of analytical results on faces which are not strictly a part of the Revit model.

This method should not be used if the transform is the identity transform, i.e. the intent is to display results on a face which is part of the Revit model. In that case, use the overload of this method which accepts a reference.

If the input face is from the geometry of a symbol, the face will be considered to be in the location specified by its symbol geometry. If your intention is to transform the face relative to its location in the instance, your input transform must consist of the instance's transform left multiplied by the extra transform to get the results you expect.

Examples

CopyC#

// Create SpatialFieldPrimitive to display results offset from a face
BoundingBoxUV bb = face.GetBoundingBox();
UV min = bb.Min;
UV max = bb.Max;

// Find the face normal at the center of the face's bounding box
UV faceCenter = new UV((max.U + min.U) / 2, (max.V + min.V) / 2);
Transform computeDerivatives = face.ComputeDerivatives(faceCenter);
XYZ faceCenterNormal = computeDerivatives.BasisZ;

// Normalize the normal vector and multiply by 2.5 
XYZ faceCenterNormalMultiplied = faceCenterNormal.Normalize().Multiply(2.5);
Transform transform = Transform.CreateTranslation(faceCenterNormalMultiplied);

// Use face and transform when adding the SpatialFieldPrimitive
SpatialFieldManager sfm = SpatialFieldManager.CreateSpatialFieldManager(doc.ActiveView, 3);
int idx = sfm.AddSpatialFieldPrimitive(face, transform);

CopyVB.NET

' Create SpatialFieldPrimitive to display results offset from a face
Dim bb As BoundingBoxUV = face.GetBoundingBox()
Dim min As UV = bb.Min
Dim max As UV = bb.Max

' Find the face normal at the center of the face's bounding box
Dim faceCenter As New UV((max.U + min.U) / 2, (max.V + min.V) / 2)
Dim computeDerivatives As Transform = face.ComputeDerivatives(faceCenter)
Dim faceCenterNormal As XYZ = computeDerivatives.BasisZ

' Normalize the normal vector and multiply by 2.5 
Dim faceCenterNormalMultiplied As XYZ = faceCenterNormal.Normalize().Multiply(2.5)
Dim transform__1 As Transform = Transform.CreateTranslation(faceCenterNormalMultiplied)

' Use face and transform when adding the SpatialFieldPrimitive
Dim sfm As SpatialFieldManager = SpatialFieldManager.CreateSpatialFieldManager(doc.ActiveView, 3)
Dim idx As Integer = sfm.AddSpatialFieldPrimitive(face, transform__1)

Exceptions

Exception	Condition
Autodesk.Revit.Exceptions..::..ArgumentNullException	A non-optional argument was null
Autodesk.Revit.Exceptions..::..ArgumentOutOfRangeException	trf is not conformal.