Skip to main content

​
Overview

The SDK provides a powerful animation system for creating smooth transitions and visual effects. You can animate camera properties (position, zoom, rotation) and layer properties (opacity, brightness, contrast).

​
Animation System

All animations implement the AnimationInterface: 
class AnimationInterface {
public:
    virtual void start() = 0;
    virtual void start(int64_t delay) = 0;
    virtual void cancel() = 0;
    virtual void finish() = 0;
    virtual bool isFinished() = 0;
    virtual void update() = 0;
};

​
Camera Animations

Camera animations are built into MapCameraInterface and triggered by setting the animated parameter:

​
Position Animation

// Animated camera movement
Coord destination(EPSG3857, longitude, latitude, 0.0);
camera->moveToCenterPosition(destination, true);

// Instant movement
camera->moveToCenterPosition(destination, false);

​
Zoom Animation

// Smooth zoom transition
camera->setZoom(15.0, true);

// Combined position and zoom animation
camera->moveToCenterPositionZoom(destination, 15.0, true);

​
Rotation Animation

// Smooth rotation to 45 degrees
camera->setRotation(45.0f, true);

​
Custom Animations

The SDK provides several animation classes for custom use cases:

​
CoordAnimation

Animate coordinate transitions with custom interpolation: 
Coord startCoord(EPSG3857, -74.006, 40.7128, 0.0);  // NYC
Coord endCoord(EPSG3857, 2.3522, 48.8566, 0.0);     // Paris

auto animation = std::make_shared<CoordAnimation>(
    2000,                          // Duration: 2 seconds
    startCoord,                    // Start position
    endCoord,                      // End position
    std::nullopt,                  // Helper coord (for arc paths)
    InterpolatorFunction::EaseInOut,  // Interpolation function
    [this](Coord current) {        // Update callback
        camera->moveToCenterPosition(current, false);
    },
    []() {                         // Finish callback (optional)
        std::cout << "Animation complete!" << std::endl;
    }
);

animation->start();
Use the helperCoord parameter to create curved paths. This is useful for long-distance animations where a straight line would cross through the earth.

​
DoubleAnimation

Animate any numeric property: 
// Animate custom zoom with easing
auto zoomAnimation = std::make_shared<DoubleAnimation>(
    1500,                          // Duration: 1.5 seconds
    10.0,                          // Start zoom
    15.0,                          // End zoom
    InterpolatorFunction::EaseOut, // Interpolation
    [this](double currentZoom) {   // Update callback
        camera->setZoom(currentZoom, false);
    }
);

zoomAnimation->start();

// Start with delay (in milliseconds)
zoomAnimation->start(500);

​
Interpolation Functions

The SDK supports multiple interpolation curves:
​
Linear
InterpolatorFunction
Constant speed throughout animation
​
EaseIn
InterpolatorFunction
Slow start, accelerating to end
​
EaseOut
InterpolatorFunction
Fast start, decelerating to end (most common for UI)
​
EaseInOut
InterpolatorFunction
Slow start and end, fast middle
​
EaseInBounce
InterpolatorFunction
Bouncing effect at the start
​
EaseOutBounce
InterpolatorFunction
Bouncing effect at the end

​
Interpolation Examples

// Smooth deceleration (recommended for most UI)
InterpolatorFunction::EaseOut

// Bounce effect for playful interactions
InterpolatorFunction::EaseOutBounce

// Smooth acceleration and deceleration
InterpolatorFunction::EaseInOut

// Linear for constant speed
InterpolatorFunction::Linear

​
Layer Animations

​
Opacity Animation

Layers support opacity control through the LayerInterface: 
// Get layer
auto layer = mapInterface->getLayer(layerIndex);

// Animate opacity from 0 to 1
auto opacityAnimation = std::make_shared<DoubleAnimation>(
    1000,                          // 1 second
    0.0,                           // Start: fully transparent
    1.0,                           // End: fully opaque
    InterpolatorFunction::Linear,
    [layer](double opacity) {
        layer->setAlpha(static_cast<float>(opacity));
    }
);

opacityAnimation->start();

​
Raster Layer Styling

Animate visual properties of raster layers: 
// Define start and end styles
RasterShaderStyle startStyle(
    0.5f,   // opacity
    0.0f,   // brightnessMin
    1.0f,   // brightnessMax
    1.0f,   // contrast
    1.0f,   // saturation
    1.0f,   // gamma
    0.0f    // brightnessShift
);

RasterShaderStyle endStyle(
    1.0f,   // opacity
    0.2f,   // brightnessMin
    0.8f,   // brightnessMax
    1.2f,   // contrast
    1.1f,   // saturation
    1.0f,   // gamma
    0.1f    // brightnessShift
);

// Create style animation
auto styleAnimation = std::make_shared<RasterStyleAnimation>(
    2000,                          // 2 seconds
    startStyle,
    endStyle,
    InterpolatorFunction::EaseInOut,
    [rasterLayer](RasterShaderStyle style) {
        rasterLayer->setStyle(style);
    }
);

styleAnimation->start();

​
Animation Control

​
Starting Animations

// Start immediately
animation->start();

// Start with delay (milliseconds)
animation->start(1000);

​
Stopping Animations

// Cancel animation (stops at current value)
animation->cancel();

// Finish animation (jumps to end value)
animation->finish();

// Check if finished
if (animation->isFinished()) {
    // Animation complete
}

​
Manual Update

For custom animation loops: 
// Call in render loop or update cycle
animation->update();

​
Layer Animation Control

Enable or disable animations on layers: 
auto layer = mapInterface->getLayer(layerIndex);

// Enable animations (default)
layer->enableAnimations(true);

// Disable animations for performance
layer->enableAnimations(false);
Disabling layer animations can improve performance when rendering many animated elements, but will make transitions appear abrupt.

​
Complex Animation Sequences

Chain animations together using completion callbacks: 
void animateJourney() {
    Coord waypoint1(EPSG3857, -74.006, 40.7128, 0.0);  // NYC
    Coord waypoint2(EPSG3857, 2.3522, 48.8566, 0.0);   // Paris
    Coord waypoint3(EPSG3857, 139.6917, 35.6895, 0.0); // Tokyo
    
    // First leg
    auto leg1 = std::make_shared<CoordAnimation>(
        3000, currentPosition, waypoint1,
        std::nullopt, InterpolatorFunction::EaseInOut,
        [this](Coord c) { camera->moveToCenterPosition(c, false); },
        [this, waypoint2, waypoint3]() { animateLeg2(waypoint2, waypoint3); }
    );
    
    leg1->start();
}

void animateLeg2(Coord waypoint2, Coord waypoint3) {
    auto leg2 = std::make_shared<CoordAnimation>(
        3000, waypoint1, waypoint2,
        std::nullopt, InterpolatorFunction::EaseInOut,
        [this](Coord c) { camera->moveToCenterPosition(c, false); },
        [this, waypoint3]() { animateLeg3(waypoint3); }
    );
    
    leg2->start();
}

​
Synchronizing Multiple Animations

Run multiple animations simultaneously: 
// Animate position and zoom together
auto posAnimation = std::make_shared<CoordAnimation>(
    2000, startCoord, endCoord,
    std::nullopt, InterpolatorFunction::EaseInOut,
    [this](Coord c) { camera->moveToCenterPosition(c, false); }
);

auto zoomAnimation = std::make_shared<DoubleAnimation>(
    2000, 10.0, 15.0,
    InterpolatorFunction::EaseInOut,
    [this](double z) { camera->setZoom(z, false); }
);

// Start both at the same time
posAnimation->start();
zoomAnimation->start();

​
Best Practices

  • Short distances: 500-1000ms
  • Medium distances: 1000-2000ms
  • Long distances or complex animations: 2000-3000ms
  • Avoid animations longer than 3 seconds to maintain user engagement
EaseOut provides the most natural feel for user-initiated actions like button clicks or search results, as it starts fast and decelerates smoothly.
When chaining animations, use completion callbacks to ensure smooth transitions between animation stages.
If the user initiates a new interaction while an animation is running, cancel the current animation to maintain responsiveness.
Small delays (100-300ms) between sequential animations can help users follow complex transitions.

​
Performance Tips

Animating many properties simultaneously can impact performance. Consider:
  • Disabling layer animations during camera movements
  • Reducing animation duration on lower-end devices
  • Using simpler interpolation functions (Linear) when performance is critical

​
Next Steps

Camera Controls

Master camera movement and gestures

Custom Layers

Create custom animated layer implementations

Build docs developers (and LLMs) love

Get started for freeTalk to us