When you specify altitude for features on a 3D map -- such as lines, polygons,
models, or markers -- there are several factors that can affect their placement,
both within the scene and in how the rendering of the scene interacts with that
feature. This document covers the use of
['AltitudeMode'](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#AltitudeMode)
on a 3D map and how manage the altitude for features.

> [!NOTE]
> **Note:** This document uses examples from the Javascript API, but the core concepts apply to both the Android and iOS SDK versions as well.

Here's how you can use **`AltitudeMode`** with a number of feature types:

- **Markers:** [Marker3DElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Marker3DElement),
  [Marker3DInteractiveElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Marker3DInteractiveElement)

  Specify an altitude on the location, and also extrusion.
- **Models:** [Model3DElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Model3DElement),
  [Model3DInteractiveElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Model3DInteractiveElement)

  Specify an altitude on the model's anchor point, which should be
  used with its orientation for proper positioning in the scene.
- **Polylines:** [Polyline3DElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Polyline3DElement),
  [Polyline3DInteractiveElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Polyline3DInteractiveElement)

  Specify how altitude is applied to position points along a polyline.
- **Polygons:** [Polygon3DElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Polygon3DElement),
  [Polygon3DInteractiveElement](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Polygon3DInteractiveElement)

  Specify how altitude is applied to position points along a polygon.

## How Altitude is used in 3D Environments

When placing points within a 3D scene, their final position is influenced by the
presence of captured 3D buildings or objects like trees. It's crucial to
understand two key concepts:

- **Digital Terrain Model (DTM)** : This represents the "bare earth" elevation. Think of it as the natural shape of the land without any buildings, trees, or other structures on top. All areas are underpinned by the DTM, which forms the basis for the globe's elevation (calculated using [EGM96](https://en.wikipedia.org/wiki/Earth_Gravitational_Model)).
- **Digital Surface Model (DSM)**: This represents the "top surface" elevation, including buildings, trees, and other structures. In areas where features have been captured (particularly urban environments where buildings dominate the view), the visible surface will appear higher than the base terrain.

The distinction between DTM and DSM is vital for understanding how different
altitude modes interact with these Digital Elevation Models (DEMs), as the
placement of features might be obscured or influenced by the surface model.
You can see the differences in the diagram below:

![A 3D map showing the distinction between Digital Terrain Model (DTM) and Digital Surface Model (DSM).](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/dtmdsm.png)

## When Features Lack Altitude Data

If you have data which lacks an altitude measurement or when using data from
another Google service, such as the Routes or Places services, you often won't
have any altitude supplied in the returned geometry. In such cases, placing the
feature in the scene requires you to choose an `AltitudeMode` carefully:

- **Clamp it to the ground**: The simplest approach, where the feature will automatically conform to the terrain. This mode uses the DTM model.
- **Give it an arbitrary altitude + relative mode**: You can assign a chosen altitude and then use RELATIVE_TO_GROUND (which places features relative to the DTM model) or RELATIVE_TO_MESH (which floats them above the DSM model).
- **Use another service to obtain altitude** : For precise DTM altitude at the feature's location, you can use a service like the Google Maps Platform [Elevation API](https://developers.google.com/maps/documentation/elevation/overview.md.txt). If it's a line or polygon, you'll need to do this for each of the points that make up the line or polygon.

## What `AltitudeMode` options mean and when to use them?

There are four `AltitudeMode` options you can specify when defining a feature:

### ABSOLUTE

Imagine an airplane flying at a specific altitude above sea level, say 10,000
feet. Its height is fixed, no matter if it's flying over a mountain or a valley.

**How to use it**: Object altitude is expressed relative to the average mean sea
level (calculated using EGM96). The feature's altitude coordinate is interpreted
as a precise elevation above mean sea level.

**When to use it**: For features with known, precise altitudes, such as flight
paths, submerged objects with exact depth, or fixed-point scientific
instruments.

### CLAMP_TO_GROUND

Think of placing a picnic blanket directly on a hillside. No matter how steep or
flat the hill is, the blanket always lies flat on the visible surface.

**How to use it**: Object altitude is expressed as placed directly on the
ground. They will remain at ground level, following the terrain, regardless of
any altitude value provided. The feature's altitude coordinate is ignored; it's
projected directly onto the terrain surface (DTM).

**When to use it**: For features that should always conform to the terrain, like
roads, fences, trails, property boundaries, or the base of buildings.

### RELATIVE_TO_GROUND

Picture a hot air balloon that stays 100 meters *above* whatever the natural
ground elevation (DTM) is beneath it. If the ground goes up, the balloon goes up
with it, maintaining that 100-meter gap from the "bare earth."

**How to use it**: Object altitude is expressed relative to the ground surface
(DTM). The feature's altitude coordinate is interpreted as an offset from the
terrain elevation at its horizontal position.

**When to use it**: For objects that need to maintain a consistent height above
the natural terrain, such as communication towers or overhead lines in rural
areas.

### RELATIVE_TO_MESH

This is like a drone flying a fixed height *above* whatever it's flying over,
whether that's the bare ground, a building roof, or the top of a tree. It
adjusts to the highest visible surface (DSM).

**How to use it**: Object altitude is expressed relative to the highest of the
ground+building+water surface (DSM). The feature's altitude coordinate is
interpreted as an offset from the DSM elevation.

**When to use it**: For objects that need to float a certain height above
whatever is physically there (DTM, buildings, water), useful for markers on
roofs or features that dynamically adjust to the visible scene.

For more details, see the documentation for the [AltitudeMode constants](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#AltitudeMode).

## Visual examples and practical applications

These examples use a specific location, Stonehenge, to illustrate how different
`AltitudeMode` options affect feature placement. These examples first cover
positioning markers, then lines and areas, which have a few different
considerations.

### Position Markers

Consider a pin marker placed as follows:

```javascript
const markerLocation = { lat: 51.1789, lng: -1.8262, altitude: 102.23 };
```

You can see this as the white pin in the scene below:

![A 3D map scene with a white pin marker, illustrating the default placement of a marker.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/whitepin.jpg)

Now look at the image below which shows pins of various colors positioned using
the different altitude modes.

![A 3D map scene showing multiple pins (white, purple, orange, blue) positioned using different altitude modes, all centered around Stonehenge.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/allpins.jpg)

Let us take a look at how the different `AltitudeMode`affects the positioning of
the marker in ascending order of elevation.

**CLAMP_TO_GROUND (Purple Pin)**

This pin ignores the altitude value and attaches itself to the nearest
ground elevation. You can see it just below the white pin, effectively
"clamping" to the terrain.

Technically, this mode ignores the actual altitude and clamps the pin to the
nearest DTM height.

**ABSOLUTE (White Pin)**

This pin uses the exact altitude value (102.23m) to place the marker at that
height above sea level (EGM96), appearing on top of one of the Stonehenge stones
as specified by its supplied altitude.

Technically, this mode uses the actual supplied altitude value to place the pin
at the specified height above sea level, which in this example is the location
of Stonehenge, but at the top of one of the stones.

**RELATIVE_TO_GROUND (Orange Pin)**

This pin takes the ground (DTM) as its base and places itself 102.23m above that
ground level, appearing to float above the natural ground that is under the
stone in the henge.

Technically, this mode sets its base to the level of the actual DTM on the
ground and then places the pin at 102.23m above it.

**RELATIVE_TO_MESH (Blue Pin)**

This pin uses the visible surface (DSM) as its base and places itself 102.23m
above that surface. This mode includes the stone's height in its measurement,
aligning it slightly higher than the orange pin.

Technically, this mode uses the mesh (DSM) as the base and places the location
at the given altitude above that. Since the DSM is at the top of the standing
stone, this pin includes this extra height in its measurement when determining
its relative height, aligning it slightly higher than the RELATIVE_TO_GROUND
pin.

> [!NOTE]
> **Note:** When a marker is covered by the surface model, it might be considered occluded and not shown. To prevent this, set the [drawsWhenOccluded](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Marker3DElement.drawsWhenOccluded) property of the marker to True. It also might not be shown if it's hidden behind another marker with a higher priority. To prevent this, set the [collisionBehavior](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Marker3DElement.collisionBehavior) property to REQUIRED. You can find more details about these modes in the sample about [marker collision](https://developers.google.com/maps/documentation/javascript/3d/marker-collision.md.txt).

### Position Lines and Areas

For lines and areas, both the altitude of the points within the feature (whether
specified or not) and the **`AltitudeMode`** being used are crucial. Let us
examine a line along Stonehenge with the following specified altitudes:

```javascript
const lineCoords = [
   { lat: 51.1786, lng : -1.8266, altitude: 101.36 },
   { lat: 51.1787, lng : -1.8264, altitude: 101.18 },
   { lat: 51.178778, lng : -1.826354, altitude: 104.89 },
   { lat: 51.178815, lng : -1.826275, altitude: 107.55 },
   { lat: 51.178923, lng : -1.825980, altitude: 105.53 },
   { lat: 51.1791, lng : -1.8258, altitude: 100.29 },
   { lat: 51.1792, lng : -1.8257, altitude: 100.29 }
];
```

You can see this line represented in the image below in white, using absolute
positioning.

![A 3D map showing a white line placed around Stonehenge using absolute positioning.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/whiteline.jpg)

Once again, the image below shows the lines using different altitude modes.
Let us discuss each in turn, from lowest to highest.

![A 3D map showing multiple colored lines (purple, white, orange, blue) positioned around Stonehenge using different altitude modes.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/manylines.jpg)

**CLAMP_TO_GROUND (Purple Line)**

This line ignores the specified altitude for each point and instead "drapes"
the line directly over the underlying ground (DTM). It follows the terrain,
ignoring the presence of any features like buildings or stones above it.

Technically, this mode ignores the actual altitude values and drapes the line
over the DTM, following the underlying terrain and ignoring the mesh of features
above it.

**ABSOLUTE (White Line)**

This line uses the exact altitude for each point, causing the line to go over
some of the stones. It is connected by straight lines between each point, which
can sometimes make it appear to pass through objects if the points are not
frequent enough.

Technically, this mode follows the specified altitude for each point, connecting
them with straight lines, meaning it can pass through the mesh (for example:
stones) if the altitude values dictate. This scenario is covered in a later
section.

**RELATIVE_TO_GROUND (Orange Line)**

This line uses the natural ground (DTM) as its base and places each point at the
specified altitude above that ground level.

Technically, this mode uses the DTM as the base and places the line locations at
the listed altitude relative to it.

**RELATIVE_TO_MESH (Blue Line)**

This line uses the visible surface, which includes buildings and stones, as its
base. It then places each point at the specified altitude above that mesh,
effectively replicating the line's shape in relation to the visible landscape.

Technically, this mode uses the mesh (DSM) as the base and places the locations
at the specified altitude above that, depending on the mesh the line might alter
given the different features on the ground.

> [!NOTE]
> **Note:** The nature of line creation means that any line passing through the mesh (or the ground) might cause issues in seeing the lines, as they are hidden by the overlying features. To allow the lines to be seen even when they are occluded by the mesh, set [drawsOccludedSegments](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Polyline3DElement.drawsOccludedSegments): true.

### When Altitude is Not Specified for Lines

Now, let us consider the same line coordinates but **without** any altitude
specified:

```javascript
const lineCoords = [
   { lat: 51.1786, lng : -1.8266 },
   { lat: 51.1787, lng : -1.8264 },
   { lat: 51.178778, lng : -1.826354 },
   { lat: 51.178815, lng : -1.826275 },
   { lat: 51.178923, lng : -1.825980 },
   { lat: 51.1791, lng : -1.8258 },
   { lat: 51.1792, lng : -1.8257 }
];
```

In this scenario, where no altitude is provided, the lines often appear in
similar locations. The White, orange, and purple lines might merge into a single
line (orange, as it's typically drawn last) because they all default to a
similar ground-level positioning. You can see this below:

![A 3D map showing multiple colored lines (orange, blue) around Stonehenge, with the white and purple lines merging due to a lack of altitude data.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/mergedlines.jpg)

The blue line (**RELATIVE_TO_MESH** ) again uses the mesh (DSM) as the base.
Since no altitude is specified, it just overlays the points directly on top of
the mesh. It's important to note that it doesn't lay the line *on* the mesh but
connects the specified points on the mesh with straight connections. While this
might look acceptable in some examples, it can cause visibility issues when
covered by other features. This issue is covered in the next section.

### The interaction of meshes and lines

Now we can look at another polyline. This image is in the same area but with
more ground coverage (or more detail on the DSM on top of the DTM).

```javascript
const lineCoords = [
    { lat: 51.188404, lng: -1.779059, altitude: 70.69 },
    { lat: 51.187955, lng: -1.780143, altitude: 77.25 },
    { lat: 51.187658, lng: -1.781552, altitude: 68.97 },
    { lat: 51.187376, lng: -1.782447, altitude: 99.02 },
    { lat: 51.186912, lng: -1.783692, altitude: 104.35 },
    { lat: 51.185855, lng: -1.788368, altitude: 86.91 },
];
```

When we see the representation using the same methods (and colors) of before, we
get this view:

![A 3D map displaying multiple colored lines (purple, white, orange, blue) over a terrain with trees and varying elevations.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/meshedlines.jpg)

Purple is **CLAMP_TO_GROUND**, which you can see going along the ground. White
is ABSOLUTE, which you can see that straight lines connect the points which are
positioned absolutely in space. With orange and blue being relative versions
either about the SURFACE (DTM) or MESH (DSM), note the blue line is slightly
different in form due to the height of the features below.

Again we can note the nature of the line creation means that the line passes
through the mesh as the points are connected together by straight lines. This
scenario might cause issues in seeing the lines, so you can set
**drawsOccludedSegments** to **true** to make sure the line is visible through
the trees, as shown in more detail in the following image, where the lines
passing through the mesh can still be seen.

![A 3D map showing lines passing through trees, with occluded segments made visible to illustrate the occlusion of segments: true.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/meshzoom.jpg)

The nature of positioning in space means that the points might fall within the
mesh and also the lines connecting the points might also fall into the mesh,
potentially causing visual artifacts. In the section below we may see how such
artifacts might be improved where possible.

### Solving issues in the interaction between lines and terrain

In another example, in the same area, we can see some other artifacts that we
must be aware of when using specific altitude modes.

Here we have a relatively flat area which is mainly at the level of the DTM,
with limited extra details above it in the mesh. This scenario would also be the
case in an area which had no 3d coverage above the terrain model. Let us take a
look at the following location, as specified below:

```javascript
const lineCoords = [
   { lat: 51.194642, lng: -1.782636, altitude: 99.10 },
   { lat: 51.193974, lng: -1.783952, altitude: 99.86 },
   { lat: 51.192203, lng: -1.787175, altitude: 96.14 },
   { lat: 51.190024, lng: -1.790250, altitude: 105.92 },
   { lat: 51.187491, lng: -1.793580, altitude: 102.60 },
   { lat: 51.183690, lng: -1.798745, altitude: 95.69 },
];
```

And can seen in the image, with the lines having the same color representation
as before:
(white : ABSOLUTE, blue : RELATIVE_TO_MESH, purple : CLAMP_TO_GROUND, orange :
RELATIVE_TO_GROUND).

![A 3D map showing various colored lines (white, blue, purple, orange) over a relatively flat terrain, highlighting visual artifacts where lines disappear into the ground.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/flatlines.jpg)

Here we can see a number of artifacts, the first of which is that due to the
lack of surface cover the orange (RELATIVE_TO_GROUND) and blue
(RELATIVE_TO_MESH) lines are in (mostly) the same location (with the blue line
being shown as it is drawn last).

We can also see that the purple (CLAMP_TO_GROUND) line follows the ground and
can be seen on the hill, whilst the white (ABSOLUTE) line can be seen as
disappearing into the hill as only the points are connected and the straight
lines go through the ground.

You can see this specifically in this image when the purple line has been
hidden.

![A 3D map showing white and blue lines disappearing into a hill, with the purple line hidden, illustrating visual artifacts of absolute and relative-to-mesh lines.](https://developers.google.com/static/maps/architecture/3d-understand-altitude-modes/images/flatclear.jpg)

This can therefore lead to some strange visual artifacts, where the line can be
seen to disappear under the ground (or even through the mesh) as the line
between the points just follows a straight path. You might be able to improve
the visual display of such a line by adding more points between the lines
through using an interpolation method, how this might affect the visual will
once again be dependent on the method being used:

- **For Relative Measurements (RELATIVE_TO_GROUND or
  RELATIVE_TO_MESH)**: When using relative altitude values, creating more points along a line or polygon will allow the feature to be placed at a more appropriate level, conforming better to the elevation profile. If these intermediary points aren't present in your data, you can use an interpolation function, such as the Interpolate function in the Google Maps Platform Geometry library, to add them. These new points can then be given relative values that will be placed above the relevant elevation profile and then the length of any line joining the points will be limited and visual representation improved.
- **For Absolute Features (ABSOLUTE)**: For ABSOLUTE features, more points will need to have actual altitude values. Interpolating between existing absolute values won't give a point that accurately reflects any value above the mesh, as it would merely be an average between point A and point B.

## Summary

Hopefully this document has provided you a comprehensive overview of
`AltitudeMode` options in Photorealistic 3D Maps, detailing how ABSOLUTE,
CLAMP_TO_GROUND, RELATIVE_TO_GROUND, and RELATIVE_TO_MESH impact the placement
and rendering of various features like markers, lines, and polygons.

Understanding how these modes work together with the underlying Digital Terrain
Model (DTM) and Digital Surface Model (DSM) is crucial to create accurate and
visually compelling 3D map representations with the minimum of visual artifacts.

We hope you will experiment with these altitude modes in your own projects to
unlock the full potential of 3D mapping and create engaging, immersive
experiences for your users and provide feedback.

## Contributors

[Matt Toon](https://www.linkedin.com/in/mtoon/) \| Solutions
Engineer, Geo Developer