Working with viewpoints, components, and section planes in the SDK Connector

A viewpoint stores how a user looked at the model when they created an issue. This article explains how your AppInterface creates viewpoints from the current view, and how it recreates a view from a viewpoint.

💡 Tip: New to the AppInterface? Read Getting started with the SDK Connector: implementing the AppInterface first.

When your application works with viewpoints

The user control uses viewpoints in two directions:

Direction	When	AppInterface methods
From your model to a viewpoint	A user creates an issue or updates its viewpoint.	`SetView2D`, `SetView3D`
From a viewpoint to your model	A user opens or zooms to an issue.	`ZoomTo2D`, `ZoomTo3D`

In both directions, the user control also sends a settings object with the options the user selected. See Settings.

The Viewpoint class

The ViewPoint class is a container. It holds:

Camera position: where you look from and in which direction.
Components: the model objects that are visible, hidden, selected, or colored.
Clipping planes: planes that cut away part of the model.

The definitions are in ViewPoint.cs in the Source folder of the package.

To create a viewpoint, start with a camera. Then add components and clipping planes to their collections.

Cameras

3D cameras

For 3D views, use one of two camera types:

CameraPerspective: a normal 3D view with perspective, like a photo.
CameraOrthogonal: a 3D view without perspective, where parallel lines stay parallel.

Property	Type	Meaning
`location`	`Point3D`	The position of the camera.
`direction`	`Vector3D`	The direction the camera looks in.
`upVector`	`Vector3D`	Which way is "up" for the camera. It defines the rotation of the camera around its looking direction.
`fieldOfView`	number	Perspective camera only. The view angle of the camera.
`viewToWorldScale`	number	Orthogonal camera only. The relation between the area in view and the image of the camera.

⚠️ Attention: All dimensions are in meters. If your application uses other units, such as millimeters, convert the values.

💡 Tip: imagine holding a camera. location is where you stand, direction is where you point the lens, and upVector is the direction of the top of the camera. If upVector is wrong, the view is rotated or upside down.

2D cameras

For 2D views, such as drawings or plans, use CameraDrawing:

Property	Meaning
`viewLeftTop_X`, `viewLeftTop_Y`	The top-left corner of the visible area.
`viewRightBottom_X`, `viewRightBottom_Y`	The bottom-right corner of the visible area.
`viewName`	The name of the view.
`viewPortClient`	The application that created the 2D view.

Components

A component is an object in the model, such as a wall or a beam. In a viewpoint, components are identified by their IFC GUID: the unique ID of the object in the IFC model.

Each component has three viewing properties:

Property	Meaning
`color`	A color to show on the component.
`selected`	Show the component as selected.
`visibility`	`true` to show the component, `false` to hide it.

How to apply component visibility

When you recreate a view, follow these rules in order:

Components that have a color or are selected are always visible. Don't use them for the visibility rules below.
If at least one of the other components has visibility set to true: hide all models, and show only the components with visibility set to true.
If all the other components have visibility set to false: show the model, and hide only those components.
After the view is set, show the colored and selected components in their color or selected state.

Examples:

Components in the viewpoint	Result in your model
Two walls with `visibility = true`	Only the two walls are visible.
Two walls with `visibility = false`	The whole model is visible, except the two walls.
One red beam (color) and one wall with `visibility = false`	The whole model is visible, except the wall. The beam is red.

Settings

The settings object tells your AppInterface which options the user selected in the user control. Use it when you create or recreate a view.

Setting	Meaning
`showComponentColor`	`true` when the user wants to use the colors in the viewpoint. When `false`, ignore the colors when you recreate the view.
`maxNumberOfComponents`	The maximum number of components in a viewpoint. If you add more, the component list is ignored when the issue is created.
`linkVisibleObjects`	`true` when the user selected Visible in Components in viewpoint. Add all visible components of the current view to the viewpoint.
`linkSelectedObjects`	`true` when the user selected Selected in Components in viewpoint. Add only the selected components to the viewpoint.
`linkNoObjects`	`true` when the user selected None in Components in viewpoint. Don't add components to the viewpoint.
`saveSelected`	`true` when the user checked Save selection as selected components. Mark the components that are selected in your application as selected in the viewpoint.

💡 Tip: Check maxNumberOfComponents before you add components. Large models can have thousands of visible components, and a viewpoint with too many components loses its component list.

Clipping planes

A clipping plane cuts away part of the model, for example, to look inside a building. It is defined by:

Property	Type	Meaning
`location`	`Point3D`	A point on the plane. It fixes the plane at a position in the model.
`direction`	`Vector3D`	The direction perpendicular to the plane (the "normal").

The direction points to the side of the plane that is cut away.

Example: to cut away everything above a height of 3 meters, use a location of (0, 0, 3) and a direction of (0, 0, 1), pointing up.

When a view can't be fully recreated

Sometimes your application can't recreate a view completely, for example, when a component doesn't exist in the loaded model. In that case, tell the user:

Call AddZoomMessage(message) for each problem.
Call ShowZoomMessage() to show the message icon in the user control.

Users click the icon to read your messages.

Troubleshooting

Problem	Possible cause	Solution
The view opens at the wrong position or scale.	The coordinates aren't in meters.	Convert the values to meters.
The view is rotated or upside down.	The `upVector` is wrong.	Check the direction of `upVector`.
The whole model disappears when you zoom to an issue.	One component has `visibility = true`, so all other components are hidden.	This is expected. See How to apply component visibility.
The wrong part of the model is cut away.	The clipping plane `direction` points the wrong way.	Reverse the direction. The direction points to the side that is cut away.
An issue is created without components.	The number of components is higher than `maxNumberOfComponents`.	Add fewer components, for example only the selected ones.