Working with Object Altitudes in Carmenta Engine

In this article, we will explore various ways to work with objects and their altitudes, including GlobeView.GroundAt, CreateTool.Elevation, OrdinaryLayer.GroundRelative, ElevationOperator, and OffsetOperator.

This article introduces these different options, explaining when to use them and their limitations.

GlobeView

The GlobeView provides different methods to handle altitude in your application. To get the most out of these methods, elevation data is required. The data must be available to GlobeView through ElevationInput:

This example comes from the 3d_globe.px sample configuration available with the Carmenta Engine SDK.

The GMTED2010 dataset provides global elevation data but at a low resolution.

GroundAt

The GlobeView.GroundAt method returns the coordinate at the mouse pointer or Point.Undefined if no ground is found. The coordinate given to this method must be expressed in drawable coordinates (pixels).

A typical use case is tracking the mouse position in an application. With GlobeView.GroundAt, you can determine whether the cursor is over the ground or in the sky (sky points are represented by Point.Undefined). If the coordinate is valid, you can use it, for example, to display information. However, if the cursor is hovering over the sky, you may choose to do nothing.

Elevation

The GlobeView.Elevation method returns the ground elevation at a given coordinate. The coordinate must be in longitude-latitude format. This method depends on the elevation data available to GlobeView. If no data is available at the given coordinate, it returns 0.

Typically, you would use this method to set the z-coordinate of points to the ground elevation.

CreateTool3D and CreateTouchTool3D

The CreateTool3D and CreateTouchTool3D tools have an ElevationMode property, which defines how the tool applies elevation when creating nodes. This property also considers the offset value defined on the tool.

Available values:

• GroundRelative The z-coordinate is determined by the ground elevation plus the offset. This applies to all nodes. This mode ensures that nodes stay at ground level and follow the terrain, which is useful for applications such as UAV nap-of-the-earth flight simulation.
• GroundRelativeAtFirst The z-coordinate is determined by the ground elevation plus the offset, but only for the first node. Subsequent nodes maintain the same z-coordinate. This is useful for volumes like boxes, where maintaining a constant bottom elevation is important.
• AboveSeaLevel The z-coordinate is defined only by the offset, meaning it ignores ground elevation and starts from sea level. If the offset is too low, objects may end up below the terrain. This mode should be avoided if terrain crossing must be prevented (e.g., for flight paths).

OrdinaryLayer

The OrdinaryLayer class provides a way to define how height values are interpreted through the GroundRelative property. This property determines whether z-coordinates represent height above ground (true) or height above sea level (false). This setting is only applicable in 3D configurations.

This solution is easy to set up, but it offers less control over data because it applies to the entire layer and cannot be shared across other operators. However, it is useful when working with third-party data that includes proper elevation values.

ElevationOperator

A more advanced way to handle altitudes is to use the ElevationOperator. This operator makes features ground-relative by adding the current ground height to their z-coordinates. Therefore, it is best to ensure that geometries either lack z-coordinates or only contain offsets, allowing the operator to handle elevation correctly. If geometries already contain ground-relative z-coordinates, applying this operator again may cause objects to appear too high above the terrain.

To function correctly, elevation data must be available in ElevationInput, while the geometries to be adjusted must be in ObjectInput.

Since it is an Operator, it can be easily reused in different parts of a configuration to maintain consistent z-coordinates across multiple geometries.

OffsetOperator

As the name suggests, the OffsetOperator applies an offset in X, Y, and Z to all points in all passing features. This operator is useful for elevating objects and making simple positional corrections within a dataset.

Since the operator simply adds an offset to existing coordinates, it does not take geographical context into account and does not recognize terrain elevation. Overusing it as an altitude “fixer” can result in misplaced features and incorrect spatial relationships.

Conclusion

Carmenta provides multiple ways to define altitude for features, whether through code or configuration files. While most solutions require detailed elevation data for accuracy, it is still possible to correctly display features in 3D even when limited data is available.