Realistic Lighting Rendering for 3D Building Elements in AMap JSAPI 2.0

Background

In early 2020, AMap Open Platform released AMap JSAPI 2.0, which has now become a stable version. This version introduced a new rendering pipeline with targeted performance optimizations in each rendering stage.

Compared with the previous stable version, the new version brings significant improvements. To achieve a more realistic world, we aim to give map buildings richer lighting effects that simulate the ubiquitous illumination in the real world, and to make building materials respond differently to light sources.

In this article we discuss how to render lighting effects for three‑dimensional building elements on the map.

Current Situation

Major map service providers adopt different rendering approaches:

Figure 1: Simple polygon representation (no height information)

Figure 2: Box‑shaped building with basic sun lighting

Figure 3: Near‑realistic rendering using tilted‑photography (3DTile‑like) data

Previously, AMap used the simple box lighting of scheme two. With new data resources we want to achieve more realistic effects, specifically:

Implement smoother, more three‑dimensional lighting to avoid flat, uniformly lit facades.

Illuminate designated areas to simulate night‑time city lighting.

Support special scenarios such as metallic specular highlights.

Solution Survey – Blinn‑Phong Lighting Model

The Blinn‑Phong model defines a fragment’s color as the sum of three reflection components:

Ambient Light Simulates the continuous reflection of light from all directions. <Ambient> = AmbientIntensity × AmbientColor

Diffuse Light Depends on the angle between the surface normal and the incoming light direction. <Diffuse> = LightIntensity × LightColor × cos(θ)

Specular Light Models the highlight on smooth surfaces. <Specular> = LightIntensity × LightColor × cos(α)^shininess

The final fragment color is the sum of ambient, diffuse, and specular components.

Light Sources and Materials

Four typical light types are used:

Ambient Light – already described.

Directional Light – simulates sunlight; rays are parallel.

Point Light – simulates a bulb; radiates in all directions and includes attenuation.

Spot Light – cone‑shaped light for special effects.

Three‑Point Lighting

To avoid harsh shadows from a single light source, the classic three‑point lighting technique is applied:

Key Light – primary source that defines the main illumination direction and intensity.

Fill Light – softens shadows created by the key light.

Back Light (Rim Light) – separates the subject from the background, adding depth.

Comparison and Implementation

We implemented all three lighting techniques using the Blinn‑Phong model, combining ambient, directional, and point lights, and finally applying the three‑point lighting layout.

In AMap JSAPI 2.0 we rendered simple 3D building blocks and then applied the new lighting scheme.

For each plane we compute two normals (front and back) via the cross product of two edge vectors:

<PlaneNormal> = cross(EdgeA, EdgeB)

Point lights require attenuation based on distance, so we placed a point light 1000 m above the Oriental Pearl Tower with a 10 km attenuation radius, illuminating the surrounding city area.

At this point the lighting for map buildings is essentially complete.

Conclusion

We first use a directional light from the south to simulate the sun. To avoid dark facades we add a weaker back‑directional light from the north. Finally, a point light centered on the Oriental Pearl Tower highlights the target area, providing clear depth and hierarchy.

The map rendering domain can benefit from many foundational theories and best practices from other fields to achieve more realistic visual results.

References

[1] Andreas Anyuru, translated by Wu Wenguo, Advanced WebGL Programming – Developing Web 3D Graphics , Tsinghua University Press, 2013.

[2] Kouichi Matsuda & Rodger Lea, translated by Xie Guanglei, WebGL Programming Guide , Electronic Industry Press, 2014.