Skip to main content

​
Overview

The MapCameraInterface provides comprehensive control over camera position, zoom, rotation, and viewport boundaries. Understanding these controls is essential for creating intuitive map interactions.

​
Camera Movement

​
Move to Position

Navigate the camera to a specific coordinate: 
// Move to a coordinate with animation
Coord newPosition(EPSG3857, longitude, latitude, 0.0);
camera->moveToCenterPosition(newPosition, true);

// Move without animation
camera->moveToCenterPosition(newPosition, false);

​
Move to Position and Zoom

Simultaneously set position and zoom level: 
// Move to New York at zoom level 14
Coord nyc(EPSG3857, -74.006, 40.7128, 0.0);
double zoom = 14.0;
camera->moveToCenterPositionZoom(nyc, zoom, true);

​
Move to Bounding Box

Automatically frame a geographic area: 
// Define bounding box (southwest and northeast corners)
RectCoord boundingBox(
    Coord(EPSG3857, -74.05, 40.68, 0.0),  // SW corner
    Coord(EPSG3857, -73.90, 40.85, 0.0)   // NE corner
);

float paddingPercent = 0.1f;  // 10% padding
bool animated = true;

// Optional zoom constraints
std::optional<double> minZoom = 10.0;
std::optional<double> maxZoom = 16.0;

camera->moveToBoundingBox(
    boundingBox, 
    paddingPercent, 
    animated, 
    minZoom, 
    maxZoom
);
Use moveToBoundingBox to show multiple points of interest simultaneously. The camera automatically calculates the optimal zoom and position.

​
Zoom Control

​
Setting Zoom Level

// Get current zoom
double currentZoom = camera->getZoom();

// Set new zoom level
camera->setZoom(15.0, true);  // Animated
camera->setZoom(15.0, false); // Instant

​
Zoom Limits

Constrain the zoom range to prevent over-zooming: 
// Set zoom constraints
camera->setMinZoom(8.0);   // Minimum zoom (zoomed out)
camera->setMaxZoom(18.0);  // Maximum zoom (zoomed in)

// Get current limits
double minZoom = camera->getMinZoom();
double maxZoom = camera->getMaxZoom();
Lower zoom values mean more zoomed out (larger area visible), while higher values mean more zoomed in (smaller area, more detail).

​
Rotation

Control map rotation (bearing): 
// Rotate map to 45 degrees
float angle = 45.0f;  // In degrees
camera->setRotation(angle, true);

// Get current rotation
float currentAngle = camera->getRotation();

// Enable/disable rotation gestures
camera->setRotationEnabled(true);

// Enable snap-to-north behavior
camera->setSnapToNorthEnabled(true);
​
angle
float
Rotation angle in degrees. 0° is north, 90° is east, 180° is south, 270° is west.

​
Camera Bounds

Restrict camera movement to a specific geographic area: 
// Define allowed bounds
RectCoord allowedBounds(
    Coord(EPSG3857, -180.0, -85.0, 0.0),  // SW corner
    Coord(EPSG3857, 180.0, 85.0, 0.0)     // NE corner
);

camera->setBounds(allowedBounds);

// Get current bounds
RectCoord bounds = camera->getBounds();

// Check if coordinate is within bounds
Coord testPoint(EPSG3857, longitude, latitude, 0.0);
bool inBounds = camera->isInBounds(testPoint);

​
Bounds Restriction Mode

Control how bounds are enforced: 
// Restrict entire visible rect (default: false)
// When true: entire viewport must be within bounds
// When false: only center point must be within bounds
camera->setBoundsRestrictWholeVisibleRect(true);

​
Viewport Padding

Add padding to the viewport to account for UI elements: 
// Set padding in pixels
camera->setPaddingLeft(20.0f);
camera->setPaddingRight(20.0f);
camera->setPaddingTop(100.0f);   // e.g., for top navigation bar
camera->setPaddingBottom(80.0f); // e.g., for bottom controls
Padding affects the “logical” center of the viewport. Use it to ensure important map content isn’t obscured by UI overlays.

​
Visible Area

Query the visible geographic area: 
// Get full visible rectangle
RectCoord visibleRect = camera->getVisibleRect();

// Get visible rectangle accounting for padding
RectCoord paddedRect = camera->getPaddingAdjustedVisibleRect();

// Check if coordinate is visible
Coord point(EPSG3857, longitude, latitude, 0.0);
float paddingPercent = 0.1f;
bool isVisible = camera->coordIsVisibleOnScreen(point, paddingPercent);

​
Coordinate Conversion

Convert between screen and map coordinates: 
// Screen position to map coordinate
Vec2F screenPos(100.0f, 200.0f);
Coord mapCoord = camera->coordFromScreenPosition(screenPos);

// Map coordinate to screen position
Coord coord(EPSG3857, longitude, latitude, 0.0);
Vec2F screenPosition = camera->screenPosFromCoord(coord);

// Convert at specific zoom level
Coord coordAtZoom = camera->coordFromScreenPositionZoom(screenPos, 15.0f);
Vec2F screenAtZoom = camera->screenPosFromCoordZoom(coord, 15.0f);

​
Gesture Controls

Enable or disable specific user interactions: 
// Enable/disable rotation gestures
camera->setRotationEnabled(true);

// Enable snap-to-north (slight rotation returns to 0°)
camera->setSnapToNorthEnabled(true);

// Freeze all camera interactions
camera->freeze(true);  // Disable all gestures
camera->freeze(false); // Re-enable gestures

​
Camera Listeners

Receive notifications when camera state changes: 
class MyCameraListener : public MapCameraListenerInterface {
public:
    void onMapInteraction() override {
        // User interacted with map
    }
    
    void onBoundsChanged() override {
        // Visible bounds changed
    }
    
    void onRotationChanged() override {
        // Map rotation changed
    }
};

// Add listener
auto listener = std::make_shared<MyCameraListener>();
camera->addListener(listener);

// Remove listener
camera->removeListener(listener);

// Manually trigger bounds change notification
camera->notifyListenerBoundsChange();

​
Utility Functions

​
Distance Calculations

// Convert pixels to map units
double distancePx = 100.0;
double mapUnits = camera->mapUnitsFromPixels(distancePx);

// Get current scaling factor
double scale = camera->getScalingFactor();

// Get screen density
float ppi = camera->getScreenDensityPpi();

​
Invariant Model Matrix

Get transformation matrix for scale/rotation invariant rendering: 
Coord position(EPSG3857, longitude, latitude, 0.0);
bool scaleInvariant = true;
bool rotationInvariant = true;

std::vector<float> matrix = camera->getInvariantModelMatrix(
    position,
    scaleInvariant,
    rotationInvariant
);
Use invariant matrices to render icons or labels that maintain constant size and orientation regardless of map zoom or rotation.

​
Best Practices

When the user taps a search result or selects a point of interest, use animated camera movements (animated = true) for a smooth, professional experience.
For city-specific apps, restrict bounds to prevent users from panning to irrelevant areas. For global apps, use world bounds.
Always set viewport padding to match your UI layout, ensuring map content isn’t hidden behind navigation bars or control panels.
Set minZoom to the lowest zoom level where your map data is meaningful, and maxZoom to your highest detail level to prevent rendering artifacts.

​
Next Steps

3D Maps

Enable 3D globe rendering with perspective camera

Animations

Animate camera transitions smoothly

Build docs developers (and LLMs) love

Get started for freeTalk to us