Skip to main content

​
Overview

The Open Mobile Maps SDK supports advanced 3D globe rendering capabilities, allowing you to display maps on a spherical surface with realistic perspective and camera controls. This is ideal for global visualizations, flight tracking, and immersive map experiences.
The 3D camera system uses MapCamera3dInterface which extends the standard MapCameraInterface with additional 3D-specific features.

​
Enabling 3D Mode

To create a map with 3D capabilities, initialize the camera with the is3D parameter set to true: 
// Create a 3D camera
auto camera = MapCameraInterface::create(mapInterface, screenDensityPpi, true);

// Access 3D-specific features
auto camera3d = camera->asMapCamera3d();

​
Camera3dConfig

The Camera3dConfig struct controls the behavior and appearance of the 3D camera. It includes the following properties:
​
key
string
Unique identifier for this camera configuration
​
allowUserInteraction
bool
Whether the user can interact with the camera through gestures
​
rotationSpeed
float
Automatic rotation speed in degrees per second (optional)
​
animationDurationMs
int32_t
Duration in milliseconds for camera transition animations
​
minZoom
float
Minimum allowed zoom level
​
maxZoom
float
Maximum allowed zoom level
​
pitchInterpolationValues
CameraInterpolation
Defines how camera pitch changes with zoom level
​
verticalDisplacementInterpolationValues
CameraInterpolation
Vertical camera displacement in the viewport, ranging from -1.0 to 1.0

​
Camera Interpolation

The CameraInterpolation struct allows you to define how camera properties change based on zoom level: 
struct CameraInterpolationValue {
    float stop;  // Between 0 and 1
    float value; // The value at this stop
};

struct CameraInterpolation {
    std::vector<CameraInterpolationValue> stops;
};

​
Example: Pitch Interpolation

// Define pitch that changes with zoom
CameraInterpolation pitchInterpolation({
    CameraInterpolationValue(0.0f, 0.0f),    // At min zoom: 0° pitch (straight down)
    CameraInterpolationValue(0.5f, 30.0f),   // At mid zoom: 30° pitch
    CameraInterpolationValue(1.0f, 60.0f)    // At max zoom: 60° pitch (angled view)
});

​
Preset Configurations

The SDK provides factory methods for common 3D configurations: 
// Basic configuration with default settings
auto basicConfig = Camera3dConfigFactory::getBasicConfig();

// Configuration for restaurant/venue viewing
auto restorConfig = Camera3dConfigFactory::getRestorConfig();

​
Setting Camera Configuration

Apply a camera configuration with optional animation: 
auto camera3d = camera->asMapCamera3d();

if (camera3d) {
    // Get current config
    auto currentConfig = camera3d->getCameraConfig();
    
    // Apply new config with 2-second animation
    camera3d->setCameraConfig(
        newConfig,
        2.0f,                    // duration in seconds
        std::nullopt,            // target zoom (optional)
        std::nullopt             // target coordinate (optional)
    );
    
    // Or apply immediately without animation
    camera3d->setCameraConfig(newConfig, std::nullopt, std::nullopt, std::nullopt);
}
Use targetZoom and targetCoordinate parameters to simultaneously change the camera configuration and navigate to a specific location.

​
3D Helper Functions

The MapCamera3DHelper class provides utility functions for 3D calculations: 
// Calculate viewport dimensions
float halfWidth = MapCamera3DHelper::halfWidth(
    cameraDistance, 
    fovy, 
    width, 
    height
);

float halfHeight = MapCamera3DHelper::halfHeight(cameraDistance, fovy);

// Ray-sphere intersection for touch/click detection
Vec3D rayStart, rayEnd, sphereCenter;
double radius = 1.0;
bool didHit = false;

Vec3D intersection = MapCamera3DHelper::raySphereIntersection(
    rayStart, 
    rayEnd, 
    sphereCenter, 
    radius, 
    didHit
);

​
Field of View

The 3D camera uses a perspective projection with configurable field of view. The camera automatically calculates horizontal and vertical FOV based on the viewport aspect ratio.
The SDK uses a right-handed coordinate system where the globe is represented as a unit sphere.

​
Best Practices

For navigation apps, use lower pitch angles (0-30°) to maintain top-down view. For exploration apps, higher pitch angles (30-60°) provide more immersive perspective.
Prevent users from zooming too far out (where the globe appears too small) or too far in (where 3D perspective becomes less useful) by setting sensible minZoom and maxZoom values.
When changing camera configurations, always specify an animationDurationMs to provide smooth visual transitions between states.

​
Next Steps

Camera Controls

Learn about camera movement, bounds, and gestures

Animations

Animate camera transitions and layer properties

Build docs developers (and LLMs) love

Get started for freeTalk to us