Magic Lane Maps SDK for C++ (magiclane/magiclane-maps-sdk-for-cpp-docs-context7)

Magic Lane Maps SDK for C++

https://github.com/magiclane/magiclane-maps-sdk-for-cpp-docs-context7
Admin
Magic Lane Maps SDK for C++ is a comprehensive mapping and navigation SDK offering global coverage,...

Tokens:2,345,200
Snippets:15,886
Trust Score:3.5
Update:6 days ago
Show doc for...
Context Summary (auto-generated)
Raw
# Magic Lane Maps SDK for C++

The Magic Lane Maps SDK for C++ is a comprehensive mapping and navigation toolkit that enables developers to build powerful location-aware applications. The SDK provides global coverage using high-quality OpenStreetMap data, featuring 3D terrain visualization, turn-by-turn navigation with voice guidance, and full offline functionality. Core capabilities include interactive map rendering, advanced search (POI, addresses, geocoding), customizable routing, real-time traffic integration, and fleet management optimization.

Built for performance, the SDK runs efficiently on both high-end and resource-constrained devices with cross-platform support for Android and iOS. The architecture centers around key services (`MapView`, `SearchService`, `RoutingService`, `NavigationService`, `ContentStore`) that work together to deliver a complete mapping solution. All online features require an API key, while offline functionality enables search, routing, and navigation without internet connectivity after downloading the necessary map data.

## SDK Initialization

Initialize the SDK session with your API token before creating any SDK objects. The `SdkSession` handles SDK initialization in its constructor and cleanup in its destructor.

```cpp
#include "Environment.h"
#include <API/GEM_MapView.h>

int main(int argc, char** argv)
{
    // Get API token from environment or compile-time definition
    std::string projectApiToken = "";

#if defined(API_TOKEN)
    projectApiToken = std::string(API_TOKEN);
#else
    auto value = std::getenv("GEM_TOKEN");
    if (value != nullptr)
        projectApiToken = value;
#endif

    // Initialize SDK - objects can be created after this line
    Environment::SdkSession session(projectApiToken, { argc > 1 ? argv[1] : "" });

    if (GEM_GET_API_ERROR() != gem::KNoError)
        return GEM_GET_API_ERROR();

    // Verify token validity
    SdkSettings().verifyAppAuthorization(projectApiToken, yourProgressListenerImpl);
    // Status delivered on notifyComplete: KNoError, error::KInvalidInput, error::KExpired, or error::KAccessDenied

    // SDK is released when session goes out of scope
    return 0;
}
```

## MapView - Display Interactive Maps

Create and display an interactive map view using an OpenGL context. The `MapView` is the central component for all map-related visualization and user interaction.

```cpp
#include "Environment.h"
#include <API/GEM_MapView.h>

int main(int argc, char** argv)
{
    std::string projectApiToken = std::getenv("GEM_TOKEN") ? std::getenv("GEM_TOKEN") : "";

    Environment::SdkSession session(projectApiToken, { argc > 1 ? argv[1] : "" });

    if (GEM_GET_API_ERROR() != gem::KNoError)
        return GEM_GET_API_ERROR();

    // Create an interactive map view with touch event handling
    CTouchEventListener pTouchEventListener;
    gem::StrongPointer<gem::MapView> mapView = gem::MapView::produce(
        session.produceOpenGLContext(Environment::WindowFrameworks::Available, "MapView", &pTouchEventListener)
    );

    if (!mapView)
    {
        GEM_LOGE("Error creating gem::MapView: %d", GEM_GET_API_ERROR());
        return -1;
    }

    // Center map on Paris with zoom level 72
    mapView->centerOnCoordinates({ 48.86130, 2.33387 }, 72);

    // Center with animation (2 second linear animation)
    mapView->centerOnCoordinates(
        { 52.14569, 1.0615 },
        gem::Animation(gem::Animation::AnimationLinear, 2000)
    );

    // Center on a geographic area
    auto topLeft = Coordinates(44.93343, 25.09946);
    auto bottomRight = Coordinates(44.93324, 25.09987);
    mapView->centerOnArea(RectangleGeographicArea(topLeft, bottomRight));

    // Adjust map view settings
    mapView->setZoomLevel(50);
    mapView->preferences().setRotationAngle(45);  // 0-360 degrees
    mapView->preferences().setViewAngle(60);      // Camera tilt angle
    mapView->preferences().setMapViewPerspective(EMapViewPerspective::MVP_3D);
    mapView->preferences().setBuildingsVisibility(EBuildingsVisibility::BV_3D);

    // Convert between screen and WGS coordinates
    Coordinates wgsCoords = mapView->transformScreenToWgs(gem::Xy(100, 200));
    gem::Xy screenPos = mapView->transformWgsToScreen(Coordinates(48.86130, 2.33387));

    WAIT_UNTIL_WINDOW_CLOSE();
    return 0;
}
```

## Coordinates and Geographic Areas

The SDK uses WGS84 coordinates for all geographic positions. Geographic areas support rectangles, circles, and polygons for region-based operations.

```cpp
// Create coordinates (latitude, longitude)
auto eiffelTower = Coordinates(48.858844, 2.294351);
auto louvre = Coordinates(48.854520, 2.299751);

// Calculate distance between two points (meters)
double distance = eiffelTower.getDistance(louvre);

// Create a path from coordinates
CoordinateList coords = {
    Coordinates(40.786, -74.202),
    Coordinates(40.690, -74.209),
    Coordinates(40.695, -73.814),
    Coordinates(40.782, -73.710),
};
Path gemPath = Path(coords);

// Create path from GPX data
DataBuffer gpxData = ...; // Path data in GPX format
Path pathFromGpx = Path(gpxData, (int)EPathFileFormat::PFF_Gpx);

// Export path to GeoJSON
DataBuffer exportedData = gemPath.exportAs((int)EPathFileFormat::PFF_GeoJson);

// Rectangle geographic area
auto rectArea = RectangleGeographicArea(
    Coordinates(44.93343, 25.09946),  // top-left
    Coordinates(44.93324, 25.09987)   // bottom-right
);

// Circle geographic area (center + radius in meters)
auto circleArea = CircleGeographicArea(
    Coordinates(40.748817, -73.985428),
    100000  // 100 km radius
);

// Polygon geographic area
CoordinateList polygonCoords = {
    Coordinates(10, 0),
    Coordinates(10, 10),
    Coordinates(0, 10),
    Coordinates(0, 0),
};
PolygonGeographicArea polygonArea = PolygonGeographicArea(polygonCoords);

// Check if a point is contained within an area
bool isInside = rectArea.containsCoordinates(Coordinates(44.933, 25.099));
Coordinates center = rectArea.getCenterPoint();
```

## Landmarks and Landmark Stores

Landmarks represent significant locations with rich metadata. Landmark stores provide persistent storage for organizing and displaying landmarks on the map.

```cpp
// Create a landmark
Landmark landmark;
landmark.setName("My Location");
landmark.setCoordinates(Coordinates(51.509865, -0.118092));
landmark.setImage(Image(image::Core::Search_Results_Pin));

// Add contact information
ContactInfo info = landmark.getContactInfo();
info.addField(EContactInfoFieldType::FT_Phone, "5555551234", "office phone");
landmark.setContactInfo(info);

// Create and manage landmark stores
auto storeResult = LandmarkStoreService().createLandmarkStore("MyLandmarkStore");

if (storeResult.second == KNoError || storeResult.second == error::KExist)
{
    LandmarkStore& landmarkStore = *storeResult.first;

    // Add landmarks to the store
    landmarkStore.addLandmark(landmark);

    // Display landmarks on the map
    mapView->preferences().lmks().add(landmarkStore);

    // Retrieve landmarks from store
    auto landmarks = landmarkStore.getLandmarks();

    // Get landmark by ID
    auto retrievedLandmark = landmarkStore.getLandmark(landmark.getLandmarkId());
}

// Get landmark store by name or ID
auto storeByName = LandmarkStoreService().getLandmarkStore("MyLandmarkStore");
auto storeById = LandmarkStoreService().getLandmarkStore(12345);

// Iterate all landmark stores
std::vector<StrongPointer<LandmarkStore>> stores;
LandmarkStoreService().iterateLandmarkStores([&stores](StrongPointer<LandmarkStore> store) {
    stores.push_back(store);
    return true; // continue iteration
});

// Import landmarks from KML file
landmarkStore.importLandmarks(
    "/path/to/file.kml",
    ELandmarkFileFormat::LFF_Kml,
    landmarkImage,
    yourProgressListenerImpl,
    KUncategorizedLandmarkCategId
);

// Remove landmark store
int storeId = landmarkStore.getId();
landmarkStore.reset();
LandmarkStoreService().removeLandmarkStore(storeId);
```

## Markers - Visual Map Elements

Markers are visual elements (icons, polylines, polygons) placed at specific geographic locations. Unlike landmarks, markers are temporary and not searchable.

```cpp
// Create a point marker
auto marker = Marker();
marker.add(Coordinates(52.1459, 1.0613));
marker.add(Coordinates(52.14569, 1.0615));
marker.setName("My Marker");

// Create marker collection and add to map
auto markerCollection = MarkerCollection(EMarkerType::MT_Point, "myCollection");
markerCollection.add(marker);
mapView->preferences().markers().add(markerCollection);

// Center on markers
mapView->centerOnArea(markerCollection.getArea(), 90);

// Customize marker appearance
auto renderSettings = MarkerCollectionRenderSettings();
renderSettings.setLabelingMode(
    EMarkerLabelingMode::MLM_ItemLabelVisible |
    EMarkerLabelingMode::MLM_TextAbove |
    EMarkerLabelingMode::MLM_IconBottomCenter
);

Image customIcon = Image(image::Core::Search_Results_Pin);
renderSettings.setImage(customIcon);
renderSettings.setLabelTextColor(Rgba(255, 0, 0, 255));
renderSettings.setLabelTextSize(3.0);

mapView->preferences().markers().add(markerCollection, renderSettings);

// Create polyline marker
auto polylineMarker = Marker();
polylineMarker.add(Coordinates(52.1459, 1.0613), -1, 0);
polylineMarker.add(Coordinates(52.14569, 1.0615), -1, 0);
polylineMarker.add(Coordinates(52.14585, 1.06186), -1, 0);

auto polylineCollection = MarkerCollection(EMarkerType::MT_Polyline, "polylines");
polylineCollection.add(polylineMarker);
mapView->preferences().markers().add(polylineCollection);

// Create polygon marker (minimum 3 coordinates)
auto polygonMarker = Marker();
polygonMarker.add(Coordinates(52.145, 1.061), -1, 0);
polygonMarker.add(Coordinates(52.146, 1.062), -1, 0);
polygonMarker.add(Coordinates(52.145, 1.063), -1, 0);

auto polygonCollection = MarkerCollection(EMarkerType::MT_Polygon, "polygons");
polygonCollection.add(polygonMarker);
mapView->preferences().markers().add(polygonCollection);

// Individual marker customization with MarkerSketches
auto sketches = mapView->preferences().markers().sketches(EMarkerType::MT_Point);
MarkerRenderSettings individualSettings;
individualSettings.setLabelTextColor(Rgba(0, 255, 0, 255));
individualSettings.setImage(Image(image::Core::Search_Results_Pin));
sketches.add(marker, individualSettings, 0);
```

## Highlight Landmarks

Highlights allow customizing landmark appearance and making them more prominent on the map.

```cpp
// Create landmarks to highlight
List<Landmark> landmarksToHighlight;

Landmark landmark;
landmark.setName("Highlighted Location");
landmark.setCoordinates(Coordinates(52.48209, -2.48888));
landmark.setImage(Image(image::Core::Search_Results_Pin));
landmarksToHighlight.push_back(landmark);

// Configure highlight render settings
HighlightRenderSettings settings;
settings.setOption(EHighlightOptions::HO_NoFading | EHighlightOptions::HO_Overlap);
settings.setImageSize(50);
settings.setTextSize(10);

// Add landmark to store first (required for highlighting)
auto storeResult = LandmarkStoreService().createLandmarkStore("highlights");
if (storeResult.second == KNoError || storeResult.second == error::KExist)
{
    LandmarkStore& store = *storeResult.first;
    store.addLandmark(landmark);
    mapView->preferences().lmks().add(store);
}

// Activate highlight with unique ID
int highlightId = 2;
mapView->activateHighlight(landmarksToHighlight, settings, highlightId);
mapView->centerOnCoordinates(Coordinates(52.48209, -2.48888), 40);

// Get highlighted landmarks by ID
List<Landmark> highlighted = mapView->getHighlight(highlightId);

// Deactivate specific highlight or all highlights
mapView->deactivateHighlight(highlightId);
mapView->deactivateAllHighlights();
```

## SearchService - Location Search

The Search service provides text-based and proximity-based search for locations, addresses, and points of interest.

```cpp
// Basic text search
LandmarkList results;
SearchPreferences preferences;
preferences.setMaxMatches(40);
preferences.setAllowFuzzyResults(true);

auto listener = StrongPointerFactory<YourProgressListenerImpl>();

const String textFilter("Paris");
Coordinates referenceCoords(45.0, 10.0);

int startErr = SearchService().search(
    results,
    listener,
    textFilter,
    referenceCoords,
    preferences
);

if (startErr == KNoError)
{
    WAIT_UNTIL(std::bind(&YourProgressListenerImpl::IsFinished, listener), 5000);

    int completeErr = listener->GetError();
    if (completeErr == KNoError)
    {
        GEM_INFO_LOG("Search completed. Results: %d", (int)results.size());
        for (auto& lm : results)
        {
            if (!lm.isDefault())
            {
                auto name = lm.getName();
                auto coords = lm.getCoordinates();
            }
        }
    }
}

// Search by category (e.g., gas stations, parking)
SearchPreferences categoryPrefs;
categoryPrefs.setSearchMapPOIs(true);
categoryPrefs.setSearchAddresses(false);

auto categories = GenericCategories().getCategories();
if (categories.size() >= 2)
{
    auto gasStations = categories[0];
    auto parking = categories[1];
    categoryPrefs.lmks().addStoreCategoryId(gasStations.getLandmarkStoreId(), gasStations.getId());
    categoryPrefs.lmks().addStoreCategoryId(parking.getLandmarkStoreId(), parking.getId());
}

SearchService().searchAroundPosition(results, listener, Coordinates(48.83952, 2.334284), "fuel", categoryPrefs);

// Proximity search (no text filter - returns nearest POIs)
SearchPreferences proximityPrefs;
proximityPrefs.setMaxMatches(40);

SearchService().searchAroundPosition(
    results,
    listener,
    Coordinates(45.0, 10.0),
    String(),  // empty text filter
    proximityPrefs
);

// Search within geographic area
RectangleGeographicArea searchArea(
    Coordinates(41.98846, -73.12412),
    Coordinates(41.37716, -72.02342)
);

SearchService().search(results, listener, String("restaurant"), Coordinates(41.68905, -72.64296), preferences, searchArea);

// Search in custom landmark stores
auto customStore = LandmarkStoreService().createLandmarkStore("CustomPOIs");
// ... add landmarks to store ...

SearchPreferences customPrefs;
customPrefs.setSearchMapPOIs(false);
customPrefs.setSearchAddresses(false);
customPrefs.lmks().add(*customStore.first);

SearchService().search(results, listener, String("My Custom"), Coordinates(25.003, 30.003), customPrefs);

// Search in overlays (e.g., speed cameras)
int overlayId = ECommonOverlayId::OID_Safety;
OverlayService().enableOverlay(overlayId);

SearchPreferences overlayPrefs;
overlayPrefs.setSearchMapPOIs(false);
overlayPrefs.setSearchAddresses(false);
overlayPrefs.overlays().add(overlayId);

SearchService().search(results, listener, String("Speed"), Coordinates(48.76930, 2.34483), overlayPrefs);
```

## RoutingService - Route Calculation

Calculate routes between locations with customizable preferences, waypoints, and traffic awareness.

```cpp
// Define departure and destination
Landmark departure("Departure", { 48.85682, 2.34375 });
Landmark destination("Destination", { 50.84644, 4.34587 });

LandmarkList landmarks;
landmarks.push_back(departure);
landmarks.push_back(destination);

RoutePreferences routePreferences;
RouteList routes;

auto listener = StrongPointerFactory<YourProgressListenerImpl>();

// Calculate route
auto err = RoutingService().calculateRoute(
    routes,
    landmarks,
    routePreferences,
    listener
);

if (err != KNoError)
{
    GEM_INFO_LOG("Error starting route calculation: %d", err);
    return;
}

WAIT_UNTIL(std::bind(&YourProgressListenerImpl::IsFinished, listener), 5000);

err = listener->GetError();
if (err == KNoError)
{
    GEM_INFO_LOG("Number of routes: %d", (int)routes.size());

    Route& route = routes.front();

    // Get time and distance
    TimeDistance td = route.getTimeDistance(false);
    auto totalDistance = td.getTotalDistance();  // meters
    auto totalDuration = td.getTotalTime();      // seconds

    // Get remaining time/distance (active part)
    TimeDistance remainTd = route.getTimeDistance(true);

    // Get traffic events
    List<RouteTrafficEvent> trafficEvents = route.getTrafficEvents();
    for (auto event : trafficEvents)
    {
        String description = event.getDescription();
        ETrafficEventSeverity severity = event.getEventSeverity();
        bool isRoadBlock = event.isRoadblock();
    }

    // Display route on map
    mapView->preferences().routes().add(route, true);  // true = main route label
    mapView->centerOnRoute(route);
}

// Cancel ongoing route calculation
RoutingService().cancelRoute(listener);

// Route with terrain profile
RoutePreferences terrainPrefs;
terrainPrefs.setBuildTerrainProfile(true);

RoutingService().calculateRoute(routes, landmarks, terrainPrefs, listener);

// Access terrain profile after calculation
auto terrainProfile = routes.front().getTerrainProfile();
if (terrainProfile)
{
    float minElevation = terrainProfile.getMinElevation();
    float maxElevation = terrainProfile.getMaxElevation();
    float totalUp = terrainProfile.getTotalUp();
    float totalDown = terrainProfile.getTotalDown();

    // Elevation at specific distance
    float elevationAt100m = terrainProfile.getElevation(100);

    // Road type sections
    for (auto section : terrainProfile.getRoadTypeSections())
    {
        ERoadType roadType = section.type;
        int startDistance = section.startDistanceM;
    }
}

// Get route instructions
auto segments = routes.front().getSegments();
for (auto& segment : segments)
{
    auto instructions = segment.getInstructions();
    for (auto& instruction : instructions)
    {
        String turnText = instruction.getTurnInstruction();
        String followText = instruction.getFollowRoadInstruction();
        TimeDistance traveled = instruction.getTraveledTimeDistance();
        Coordinates location = instruction.getCoordinates();
    }
}
```

## NavigationService - Turn-by-Turn Navigation

Provides real-time turn-by-turn navigation guidance with voice support, alerts, and route recalculation.

```cpp
// Implement navigation listener
class MyNavigationListener : public INavigationListener
{
public:
    void onNavigationInstruction(const NavigationInstruction& instruction) override
    {
        // Process navigation instruction
        String turnText = instruction.getTurnInstruction();
        TimeDistance remaining = instruction.getRemainingTravelTimeDistance();
    }

    void onNavigationStarted() override { }

    void onWaypointReached(const Landmark& landmark) override
    {
        GEM_INFO_LOG("Waypoint reached: %s", landmark.getName().c_str());
    }

    void onDestinationReached(const Landmark& landmark) override
    {
        GEM_INFO_LOG("Destination reached: %s", landmark.getName().c_str());
    }

    void onRouteUpdated(const Route& route) override { }

    void onBetterRouteDetected(const Route& route, int travelTime, int delay, int timeGain) override
    {
        // Accept better route: NavigationService().setBetterRoute(route);
    }

    void onTurnAround() override { }
};

// Start navigation
auto navigationListener = StrongPointerFactory<MyNavigationListener>();
auto progressListener = StrongPointerFactory<YourProgressListenerImpl>();

int err = NavigationService().startNavigation(
    route,
    navigationListener,
    progressListener  // for recalculation progress
);

if (err != KNoError)
{
    GEM_INFO_LOG("Failed to start navigation: %d", err);
    return;
}

// Set camera to follow position during navigation
mapView->startFollowingPosition();

// Start simulation instead of real navigation
NavigationService().startSimulation(
    route,
    navigationListener,
    progressListener,
    2.0f  // speed multiplier (1.0 = normal speed)
);

// Skip intermediate waypoint
NavigationService().skipNextIntermediateDestination();

// Stop navigation or simulation
NavigationService().cancelNavigation(navigationListener);
```

## PositionService - Location Updates

Receive and manage location updates from GPS or custom data sources.

```cpp
// Implement position listener
class MyPositionListener : public IPositionListener
{
public:
    void onNewPosition(sense::PositionPtr position) override
    {
        // Cast to improved (map-matched) position for more data
        auto improvedPosition = position->cast<sense::IImprovedPosition>();

        // Current coordinates
        Coordinates coords = improvedPosition->getCoordinates();
        GEM_INFO_LOG("Position: Lat=%f, Lon=%f", coords.getLatitude(), coords.getLongitude());

        // Speed in m/s (-1 if unavailable)
        double speed = improvedPosition->getSpeed();

        // Speed limit on current road (0 if unavailable)
        double speedLimit = improvedPosition->getRoadSpeedLimit();

        // Heading (0=N, 90=E, 180=S, 270=W)
        double course = improvedPosition->getCourse();

        // Road information (tunnel, bridge, ramp, one-way, etc.)
        auto roadModifiers = improvedPosition->getRoadModifier();

        // Position accuracy
        double horizontalAccuracy = improvedPosition->getHorizontalAccuracy();
        auto fixQuality = improvedPosition->getFixQuality();
    }
};

// Register for map-matched position updates
auto positionListener = StrongPointerFactory<MyPositionListener>();
PositionService().addListener(positionListener, sense::EDataType::ImprovedPosition);

// Register for raw GPS position updates
PositionService().addListener(positionListener, sense::EDataType::Position);

// Get current position (one-time read)
auto currentPosition = PositionService().getPosition(sense::EDataType::ImprovedPosition);
if (currentPosition && currentPosition->isValid())
{
    auto improved = currentPosition->cast<sense::IImprovedPosition>();
    Coordinates coords = improved->getCoordinates();
}

// Use live GPS data source
PositionService().setDataSource(sense::DataSourceFactory::produceLive());

// Remove listener when done
PositionService().removeListener(positionListener);
```

## ContentStore - Offline Maps

Download and manage offline map content for search, routing, and navigation without internet connectivity.

```cpp
// List available online content
auto listener = StrongPointerFactory<YourProgressListenerImpl>();

auto err = ContentStore().asyncGetStoreContentList(EContentType::CT_RoadMap, listener);
if (err != KNoError)
{
    GEM_INFO_LOG("Failed to request content list: %d", err);
}

// After completion, get the list
WAIT_UNTIL(std::bind(&YourProgressListenerImpl::IsFinished, listener), 10000);

// Get local (already downloaded) content
auto localItems = ContentStore().getLocalContentList(EContentType::CT_RoadMap);

// Filter content by geographic area
RectangleGeographicArea filterArea(
    Coordinates(53.7731, -1.7990),
    Coordinates(38.4549, 21.1696)
);
StringList countryFilter;  // empty = all countries

ContentStore().asyncGetStoreFilteredList(EContentType::CT_RoadMap, countryFilter, filterArea, listener);

// Download content store item
for (auto& item : localItems)
{
    GEM_INFO_LOG("Item: %s, Size: %lld, Status: %d",
        item.getName().c_str(), item.getTotalSize(), item.getStatus());

    if (item.getStatus() == EContentStoreItemStatus::CIS_Unavailable)
    {
        // Download the item
        item.asyncDownload(listener);
    }

    // Check download progress
    int progress = item.getDownloadProgress();  // 0-100
    bool completed = item.isCompleted();

    // Check for updates
    if (item.isUpdatable())
    {
        item.asyncDownload(listener);  // Downloads update
    }
}

// Pause download
contentStoreItem.pauseDownload();

// Delete downloaded content
if (contentStoreItem.canDeleteContent())
{
    auto error = contentStoreItem.deleteContent();
}

// Download map styles
ContentStore().asyncGetStoreContentList(EContentType::CT_ViewStyleHighRes, listener);

// Download voice files
ContentStore().asyncGetStoreContentList(EContentType::CT_HumanVoice, listener);

// Enable downloads on metered networks
SdkSettings().setAllowOffboardServiceOnExtraChargedNetwork(EServiceGroupType::ContentService, true);

// Download overlays for offline use
auto overlayUid = ECommonOverlayId::OID_Safety;
if (OverlayService().isOverlayOfflineDataGrabberSupported(overlayUid))
{
    OverlayService().enableOverlayOfflineDataGrabber(overlayUid);
    OverlayService().grabOverlayOfflineData(overlayUid, listener);
    // Disable when done
    OverlayService().disableOverlayOfflineDataGrabber(overlayUid);
}
```

## Map Interaction and Selection

Handle user interactions with the map including touch events and element selection.

```cpp
// Implement map view listener
class MyMapViewListener : public IMapViewListener
{
public:
    void onTouch(const Xy& pos) override
    {
        // Set cursor position for selection
        mapView->setCursorScreenPosition(pos);

        // Select landmarks at cursor
        auto landmarks = mapView->cursorSelectionLandmarks();
        for (const auto& landmark : landmarks)
        {
            GEM_INFO_LOG("Selected: %s", landmark.getName().c_str());
        }

        // Select markers
        auto markers = mapView->cursorSelectionMarkers();

        // Select routes
        auto routes = mapView->cursorSelectionRoutes();

        // Select overlay items
        auto overlayItems = mapView->cursorSelectionOverlayItems();

        // Select streets
        auto streets = mapView->cursorSelectionStreets();
        for (const auto& street : streets)
        {
            auto streetName = street.getName();
        }
    }

    void onDoubleTouch(const Xy& pos) override { }
    void onLongPress(const Xy& pos) override { }
    void onMove(const Xy& from, const Xy& to) override { }
    void onPinch(float scale) override { }
    void onViewRendered(EViewDataTransitionStatus status) override { }
};

// Enable/disable touch gestures
mapView->preferences().enableTouchGestures(ETouchGestures::TG_OnTouch, false);
bool isEnabled = mapView->preferences().isTouchGestureEnabled(ETouchGestures::TG_OnTouch);

// Show cursor on screen (for debugging)
mapView->preferences().enableCursor(true);
mapView->preferences().enableCursorRender(true);

// Capture map as image
auto image = mapView->captureAsImage();
if (!image.isDefault())
{
    auto pngBuffer = image.exportAs(Size(500, 300), EImageFileFormat::IFF_Png);
}
```

## Overlays

Overlays are additional map layers containing specialized data like speed cameras, traffic reports, and public transit stops.

```cpp
// Get available overlays for current map style
auto overlays = OverlaysService().getAvailableOverlays(yourProgressListenerImpl);

// Iterate overlay collection
for (int i = 0; i < overlays.first->size(); i++)
{
    auto overlayInfo = overlays.first->getOverlayAt(i);
    GEM_INFO_LOG("Overlay: %s, ID: %d", overlayInfo.getName().c_str(), overlayInfo.getUid());

    // Get overlay categories
    auto categories = overlayInfo.getCategories();
    for (auto& category : categories)
    {
        GEM_INFO_LOG("  Category: %s", category.getName().c_str());
    }
}

// Enable/disable overlay visibility
int safetyOverlayId = ECommonOverlayId::OID_Safety;
OverlayService().enableOverlay(safetyOverlayId);

// Get overlay item details
SearchableParameterList parameters = overlayItem.getPreviewData();
for (const auto& param : parameters)
{
    auto key = param.getKey();
    auto name = param.getName();
    auto valueType = param.getType();
    auto value = param.getValue<gem::String>();
}

// Common overlay types:
// ECommonOverlayId::OID_Safety - Speed cameras, red light cameras
// ECommonOverlayId::OID_SocialReports - User-reported incidents
// ECommonOverlayId::OID_PublicTransport - Public transit stops
```

## Summary

The Magic Lane Maps SDK for C++ provides a complete solution for building location-aware applications with interactive mapping, advanced search, routing, and turn-by-turn navigation. The SDK's modular architecture separates concerns into specialized services: `MapView` for visualization and interaction, `SearchService` for location discovery, `RoutingService` for path calculation, `NavigationService` for guided navigation, and `ContentStore` for offline content management. This design enables developers to integrate only the features they need while maintaining a consistent API pattern across all services.

Key integration patterns include: initializing the SDK session before creating any objects, using progress listeners for asynchronous operations, managing landmarks through persistent stores, and handling map interactions through dedicated listener implementations. The SDK supports both online and offline operation modes, with offline functionality requiring prior download of map data, styles, and voice files. For fleet management and logistics applications, the SDK includes vehicle routing optimization (VRP) capabilities through specialized fleet management APIs. Whether building a simple map viewer or a full-featured navigation application, the SDK provides the flexibility and performance needed for production-grade location services.