About views

About views

This section is a high-level overview discussing the following:

View Process

The following figure illustrates how a view is generated.

Figure 94: Create view process

Each view is generated by projecting a three-dimensional object onto a two-dimensional projection plane. Projections are divided into two basic classes:

  • Perspective
  • Parallel

After the projection type is determined, you must specify the conditions under which the 3D model is needed and the scene is to be rendered. For more information about projection, refer to the View 3D section.

World coordinates include the following:

  • The viewer's eye position
  • The viewing plane location where the projection is displayed.

Revit uses two coordinate systems:

  • The global or model space coordinates where the building exists
  • The viewing coordinate system.

The viewing coordinate system represents how the model is presented in the observer's view. Its origin is the viewer's eye position whose coordinates in the model space are retrieved by the View.Origin property. The X, Y, and Z axes are represented by the View.RightDirection, View.UpDirection, and View.ViewDirection properties respectively.

  • View.RightDirection is towards the right side of the screen.
  • View.UpDirection towards the up side of the screen.
  • View.ViewDirection from the screen to the viewer.

The viewing coordinate system is right-handed. For more information, see the Perspective Projection picture and the Parallel Projection picture in View3D.

Some portions of a 3D model space that do not display, such as those that are behind the viewer or are too far away to display clearly, are excluded before being projected onto the projection plane. This action requires cropping the view. The following rules apply to cropping:

  • Elements outside of the crop region are no longer in the view.

  • The View.GetCropRegionShapeManager method returns a ViewCropRegionShapeManager which provides the boundary information for the crop region, which may or may not be rectangular.

  • The View.CropBoxVisible property determines whether the crop box is visible in the view.
  • The View.CropBoxActive property determines whether the crop box is actually being used to crop the view.

After cropping, the model is projected onto the projection plane. The following rules apply to the projection:

  • The projection contents are mapped to the screen view port for display.
  • During the mapping process, the projection contents are scaled so that they are shown properly on the screen.
  • The View.Scale property is the ratio of the actual model size to the view size.
  • The view boundary on paper is the crop region, which is a projection of the crop shape on the projection plane.
  • The size and position of the crop region is determined by the View.OutLine property.

Display Settings

The view class has properties to get and set the display style settings and the detail level settings. The View.DisplayStyle property uses the DisplayStyle enumeration and corresponds to the display options available at the bottom of the Revit window as shown below.

Because setting a view's display style to raytrace enters a special restricted mode with limited capabilities, it is not permitted to directly assign the display style to this value.

The View.DetailLevel property uses the ViewDetailLevel enumeration and corresponds to the detail level options available at the bottom of the Revit window as shown below.

The ViewDetailLevel enumeration includes Undefined in the case that a given View does not use detail level.

Temporary View Modes

The View class allows for control of temporary view modes. The View.EnableRevealHiddenMode() method turns on the reveal hidden elements mode for the view. View.EnableTemporaryAnalyticalDisplayMode() enables temporary display of Analytical Model categories only. And the View.DisableTemporaryViewMode()will disable the specified temporary view mode. The DisableTemporaryViewMode() method takes a TemporaryViewMode enum. The possible options are shown below.

Member Name

Description

RevealHiddenElements

The reveal hidden elements mode

TemporaryHideIsolate

The temporary hide/isolate mode

WorksharingDisplay

One of the worksharing display modes

AnalyticalModel

The mode that isolates the analytical model

Rayrace

The mode that shows the model in interactive raytracing

The View.IsInTemporaryViewMode method can be used to determine whether the view is currently in the specified TemporaryViewMode.

Element Visibility in a View

Views keep track of visible elements. All elements that are graphical and visible in the view can be retrieved using a FilteredElementCollector constructed with a document and the id of the view. However, some elements in the set may be hidden or covered by other elements. You can see them by rotating the view or removing the elements that cover them. Accessing these visible elements may require Revit to rebuild the geometry of the view. The first time your code uses this constructor for a given view, or the first time your code uses this constructor for a view whose display settings have just been changed, you may experience a significant performance degradation.

Elements are shown or hidden in a view by category.

  • The View.GetVisibility() method queries a category to determine if it is visible or invisible in the view.
  • The View.SetVisibility() method sets all elements in a specific category to visible or invisible.

A FilteredElementCollector based on a view will only contain elements visible in the current view. You cannot retrieve elements that are not graphical or elements that are invisible. A FilteredElementCollector based on a document retrieves all elements in the document including invisible elements and non-graphical elements. For example, when creating a default 3D view in an empty project, there are no elements in the view but there are many elements in the document, all of which are invisible.

The following code sample counts the number of wall category elements in the active document and active view. The number of elements in the active view differs from the number of elements in the document since the document contains non-graphical wall category elements.

Code Region: Counting elements in the active view 

private void CountElements(UIDocument uiDoc)
{
    StringBuilder message = new StringBuilder();
    FilteredElementCollector viewCollector = 
        new FilteredElementCollector(uiDoc.Document, uiDoc.ActiveView.Id);
    viewCollector.OfCategory(BuiltInCategory.OST_Walls);
    message.AppendLine("Wall category elements within active View: "
        + viewCollector.ToElementIds().Count);

    FilteredElementCollector docCollector = new FilteredElementCollector(uiDoc.Document);
    docCollector.OfCategory(BuiltInCategory.OST_Walls);
    message.AppendLine("Wall category elements within document: "
        + docCollector.ToElementIds().Count);

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

Temporary view modes can affect element visibility. The View.IsInTemporaryViewMode() method can be used to determine if a View is in a temporary view mode. The method View.IsElementVisibleInTemporaryViewMode() identifies if an element should be visible in the indicated view mode. This applies only to the TemporaryHideIsolate and AnalyticalModel view modes. Other modes will result in an exception.

Creating and Deleting Views

The Revit Platform API provides numerous methods to create the corresponding view elements derived from Autodesk.Revit.DB.View class. Most view types are created using static methods of the derived view classes. If a view is created successfully, these methods return a reference to the view, otherwise they return null. The methods are described in the following sections specific to each view class.

Views can also be created using the View.Duplicate() method. A new view can be created from an existing view with options for the new view to be dependent or to have detailing.

Delete a view by using the Document.Delete method with the view ID. You can also delete elements associated with a view. For example, deleting the level element causes Revit to delete the corresponding plan view or deleting the camera element causes Revit to delete the corresponding 3D view.

Parent topic: Views