Ground Overlays

Ground Overlays

Ground overlays project a bitmap (PNG, JPG) image of a defined coordinate over a basemap. For example, a ground overlay bitmap may be used to show an indoor floorplan over a building map.

Note: You have to know geographical map coordinates of the Ground Control Points. Currently, Mobile SDK supports three or four points on a bitmap image.

Ground Overlay Requirements

The following requirements allow you to ground overlays with the Mobile SDK.

• linear affine transformation enables you to set three control points to set the location, size, and rotation of the bitmap

• perspective transformation enables you to control four control points for the bitmap

• If you have more control points in your data, it is suggested to choose three or four of your best ones, and select those as your ground control settings

• Control points must be defined in the app code. Mobile SDK does not automatically gather control points from the source file metadata

• The entire bitmap must fit to device memory (RAM). Depending on the target device, the maximum size could vary. For example, the target device maximum size might be 2000x2000 pixels.

Tip: For larger rasters, the SDK GIS Extension (special build of SDK) allows you to display any size bitmap, up to hundreds of megabytes. These bitmaps are read directly from common GIS raster formats (such as GeoTIFF, BSB, ECW, MrSID, JPEG2000, and so on), and SDK creates tiles from this internally. Additionally, the source data can be entered using different coordinate systems.

Code sample

This example uses only one geographical coordinate. The building size is known, and the building direction is facing north. This allows us to calculate other ground points with the code. Four ground control points are set to the corners of the bitmap, which typically returns the most accurate result.

Tip: The following sample code assumes that you have the jefferson-building-ground-floor.jpg bitmap file as part of your application project.

• For Android, this image is located under assets
• In iOS, it can be located anywhere in your project

`
    com.carto.graphics.Bitmap overlayBitmap = BitmapUtils.loadBitmapFromAssets("jefferson-building-ground-floor.jpg");

    // 1. Create two vector containing geographical positions and corresponding raster image pixel coordinates
    MapPos pos = proj.fromWgs84(new MapPos(-77.004590, 38.888702));
    double sizeNS = 110, sizeWE = 100;

    MapPosVector mapPoses = new MapPosVector();
    mapPoses.add(new MapPos(pos.getX()-sizeWE, pos.getY()+sizeNS));
    mapPoses.add(new MapPos(pos.getX()+sizeWE, pos.getY()+sizeNS));
    mapPoses.add(new MapPos(pos.getX()+sizeWE, pos.getY()-sizeNS));
    mapPoses.add(new MapPos(pos.getX()-sizeWE, pos.getY()-sizeNS));

    ScreenPosVector bitmapPoses = new ScreenPosVector();
    bitmapPoses.add(new ScreenPos(0, 0));
    bitmapPoses.add(new ScreenPos(0, overlayBitmap.getHeight()));
    bitmapPoses.add(new ScreenPos(overlayBitmap.getWidth(), overlayBitmap.getHeight()));
    bitmapPoses.add(new ScreenPos(overlayBitmap.getWidth(), 0));

    // 2. Create bitmap overlay raster tile data source
    BitmapOverlayRasterTileDataSource rasterDataSource = new BitmapOverlayRasterTileDataSource(0, 20, overlayBitmap, proj, mapPoses, bitmapPoses);
    RasterTileLayer rasterLayer = new RasterTileLayer(rasterDataSource);
    mapView.getLayers().add(rasterLayer);

    // 3. Apply zoom level bias to the raster layer
    // - By default, bitmaps are upsampled on high-DPI screens

    // 4. Correct this by applying appropriate bias
    float zoomLevelBias = (float) (Math.log(mapView.getOptions().getDPI() / 160.0f) / Math.log(2));
    rasterLayer.setZoomLevelBias(zoomLevelBias * 0.75f);
    rasterLayer.setTileSubstitutionPolicy(TileSubstitutionPolicy.TILE_SUBSTITUTION_POLICY_VISIBLE);

    mapView.setFocusPos(pos, 0);
    mapView.setZoom(16f, 0);