The 2D Sketch Class

The Sketch class represents enclosed curves in a plane used to create a 3D model. The key features are represented by the SketchPlane and CurveLoop properties.

When editing a Revit file, you cannot retrieve a Sketch object by iterating Document.Elements enumeration because all Sketch objects are transient Elements. When accessing the Family's 3D modeling information, Sketch objects are important to forming the geometry. For more details, refer to 3D Sketch.

SketchPlane is the basis for all 2D sketch classes such as ModelCurve and Sketch. SketchPlane is also the basis for 2D Annotation Elements such as DetailCurve. Both ModelCurve and DetailCurve have the SketchPlane property and need a SketchPlane in the corresponding creation method. SketchPlane is always invisible in the Revit UI.

Every ModelCurve must lie in one SketchPlane. In other words, wherever you draw a ModelCurve either in the UI or by using the API, a SketchPlane must exist. Therefore, at least one SketchPlane exists in a 2D view where a ModelCurve is drawn.

The 2D view contains the CeilingPlan, FloorPlan, and Elevation ViewTypes. By default, a SketchPlane is automatically created for all of these views. The 2D view-related SketchPlane Name returns the view name such as Level 1 or North.

Figure 77: Pick a Plane to identify a new Work Plane

When you specify a new work plane, you can select Pick a plane as illustrated in the previous picture. After you pick a plane, select a plane on a particular element such as a wall as the following picture shows. In this case, the SketchPlane.Name property returns a string related to that element. For example, in the following picture, the SketchPlane.Name property returns 'Generic - 8' the same as the Wall.Name property.

Figure 78: Pick a Plane on a wall as Work Plane

Note: A SketchPlane is different from a work plane because a work plane is visible and can be selected. It does not have a specific class in the current API, but is represented by the Element class. A work plane must be defined based on a specific SketchPlane. Both the work plane and SketchPlane Category property return null. Although SketchPlane is always invisible, there is always a SketchPlane that corresponds to a work plane. A work plane is used to express a SketchPlane in text and pictures.

The following information applies to SketchPlane members:

ID, UniqueId, Name, and Plane properties return a value;
Parameters property is empty
Location property returns a Location object
Other properties return null.

Plane contains the SketchPlane geometric information. SketchPlane sets up a plane coordinate system with Plane as the following picture illustrates:

Figure 79: SketchPlane and Plane coordinate system

The following code sample illustrates how to create a new SketchPlane:

Code Region 17-1: Creating a new SketchPlane

private SketchPlane CreateSketchPlane(UIApplication application)
{
    //try to create a new sketch plane
    XYZ newNormal = new XYZ(1, 1, 0);  // the normal vector
    XYZ newOrigin = new XYZ(0, 0, 0);  // the origin point
    // create geometry plane
    Plane geometryPlane = Plane.CreateByNormalAndOrigin(newNormal, newOrigin);

    // create sketch plane
    SketchPlane sketchPlane = SketchPlane.Create(application.ActiveUIDocument.Document,geometryPlane);

    return sketchPlane;
}