Use the OfflineMapTask
to take a web map offline, but instead of downloading an online basemap, use one which is already on the device.
Use case
There are a number of use-cases where you may wish to use a basemap which is already on the device, rather than downloading:
- You want to limit the total download size.
- You want to be able to share a single set of basemap files between many offline maps.
- You want to use a custom basemap (for example authored in ArcGIS Pro) which is not available online.
- You do not wish to sign into ArcGIS.com in order to download Esri basemaps.
The author of a web map can support the use of basemaps which are already on a device by configuring the web map to specify the name of a suitable basemap file. This could be a basemap which:
- Has been authored in ArcGIS Pro to make use of your organization's custom data.
- Is available as a PortalItem which can be downloaded once and re-used many times.
How to use the sample
- Click on "Generate Offline Map".
- You will be prompted to choose whether you wish to download the online basemap or use the "naperville_imagery.tpkx" basemap which is already on the device.
- If you choose to download the online basemap, the offline map will be generated with the same (topographic) basemap as the online web map.
- If you choose to use the basemap from the device, the offline map will be generated with the local imagery basemap. The download will be quicker since no tiles are exported or downloaded.
- Since the application is not exporting online ArcGIS Online basemaps you will not need to log-in.
How it works
- The sample creates a
PortalItem
object using a web map's ID. This portal item is used to initialize anOfflineMapTask
object. When the button is clicked, the sample requests the default parameters for the task, with the selected extent, by callingOfflineMapTask::createDefaultGenerateOfflineMapParameters
. - If the user chooses to use the basemap on the device, the
GenerateOfflineMapParameters::referenceBasemapDirectory
is set to the absolute path of the directory which contains the .tpkx file. - A
GenerateOfflineMapJob
is created by callingOfflineMapTask::generateOfflineMap
passing the parameters and the download location for the offline map. - When the
GenerateOfflineMapJob
is started it will check whetherGenerateOfflineMapParameters::referenceBasemapDirectory
has been set. If this property is set, no online basemap will be downloaded and instead, the mobile map will be created with a reference to the .tpkx on the device.
Relevant API
- GenerateOfflineMapJob
- GenerateOfflineMapParameters
- GenerateOfflineMapResult
- OfflineMapTask
Offline data
Read more about how to set up the sample's offline data here.
Link | Local Location |
---|---|
Naperville Imagery Tile Package | <userhome> /ArcGIS/Runtime/Data/tpkx/naperville_imagery.tpkx |
Tags
basemap, download, local, offline, save, web map
Sample Code
// [WriteFile Name=GenerateOfflineMapLocalBasemap, Category=Maps]
// [Legal]
// Copyright 2019 Esri.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// [Legal]
#ifdef PCH_BUILD
#include "pch.hpp"
#endif // PCH_BUILD
#include "GenerateOfflineMapLocalBasemap.h"
#include "Map.h"
#include "MapQuickView.h"
#include "Portal.h"
#include "PortalItem.h"
#include "OfflineMapTask.h"
#include "GeometryEngine.h"
#include "Envelope.h"
#include "Point.h"
#include <QDir>
#include <QTemporaryDir>
#include <QtCore/qglobal.h>
#ifdef Q_OS_IOS
#include <QStandardPaths>
#endif // Q_OS_IOS
using namespace Esri::ArcGISRuntime;
// helper method to get cross platform data path
namespace
{
QString defaultDataPath()
{
QString dataPath;
#ifdef Q_OS_ANDROID
dataPath = "/sdcard";
#elif defined Q_OS_IOS
dataPath = QStandardPaths::writableLocation(QStandardPaths::DocumentsLocation);
#else
dataPath = QDir::homePath();
#endif
return dataPath;
}
} // namespace
const QString GenerateOfflineMapLocalBasemap::s_webMapId = QStringLiteral("acc027394bc84c2fb04d1ed317aac674");
GenerateOfflineMapLocalBasemap::GenerateOfflineMapLocalBasemap(QQuickItem* parent /* = nullptr */):
QQuickItem(parent)
{
}
void GenerateOfflineMapLocalBasemap::init()
{
// Register the map view for QML
qmlRegisterType<MapQuickView>("Esri.Samples", 1, 0, "MapView");
qmlRegisterType<GenerateOfflineMapLocalBasemap>("Esri.Samples", 1, 0, "GenerateOfflineMapLocalBasemapSample");
}
void GenerateOfflineMapLocalBasemap::componentComplete()
{
QQuickItem::componentComplete();
// find QML MapView component
m_mapView = findChild<MapQuickView*>("mapView");
// Create a Portal Item for use by the Map and OfflineMapTask
m_portalItem = new PortalItem(webMapId(), this);
// Create a map from the Portal Item
m_map = new Map(m_portalItem, this);
// Update property once map is done loading
connect(m_map, &Map::doneLoading, this, [this](Error e)
{
if (!e.isEmpty())
return;
m_mapLoaded = true;
emit mapLoadedChanged();
});
// Set map to map view
m_mapView->setMap(m_map);
// Create the OfflineMapTask with the PortalItem
m_offlineMapTask = new OfflineMapTask(m_portalItem, this);
// connect to the error signal
connect(m_offlineMapTask, &OfflineMapTask::errorOccurred, this, [](Error e)
{
if (e.isEmpty())
return;
qDebug() << e.message() << e.additionalMessage();
});
}
void GenerateOfflineMapLocalBasemap::generateMapByExtent(double xCorner1, double yCorner1, double xCorner2, double yCorner2)
{
// create an envelope from the QML rectangle corners
const Point corner1 = m_mapView->screenToLocation(xCorner1, yCorner1);
const Point corner2 = m_mapView->screenToLocation(xCorner2, yCorner2);
const Envelope extent = Envelope(corner1, corner2);
const Envelope mapExtent = GeometryEngine::project(extent, SpatialReference::webMercator());
const QString tempPath = m_tempDir.path() + "/OfflineMap.mmpk";
const QString dataPath = defaultDataPath() + "/ArcGIS/Runtime/Data/tpkx";
// connect to the signal for when the default parameters are generated
connect(m_offlineMapTask, &OfflineMapTask::createDefaultGenerateOfflineMapParametersCompleted,
this, [this, dataPath, tempPath](QUuid, GenerateOfflineMapParameters params)
{
// update default parameters to specify use of local basemap
// this will prevent new tiles from being generated on the server
// and will reduce generation and download time
if (m_useLocalBasemap)
{
params.setReferenceBasemapDirectory(dataPath);
// A default reference basemap filename can be specified by the source portal item's advanced offline options.
params.setReferenceBasemapFilename("naperville_imagery.tpkx");
}
// Take the map offline once the parameters are generated
GenerateOfflineMapJob* generateJob = m_offlineMapTask->generateOfflineMap(params, tempPath);
// check if there is a valid job
if (generateJob)
{
// connect to the job's status changed signal
connect(generateJob, &GenerateOfflineMapJob::statusChanged, this, [this, generateJob](JobStatus jobStatus)
{
// connect to the job's status changed signal to know once it is done
switch (jobStatus) {
case JobStatus::Failed:
emit updateStatus("Generate failed");
emit hideWindow(5000, false);
break;
case JobStatus::NotStarted:
emit updateStatus("Job not started");
break;
case JobStatus::Paused:
emit updateStatus("Job paused");
break;
case JobStatus::Started:
emit updateStatus("In progress");
break;
case JobStatus::Succeeded:
// show any layer errors
if (generateJob->result()->hasErrors())
{
QString layerErrors = "";
const QMap<Layer*, Error>& layerErrorsMap = generateJob->result()->layerErrors();
for (auto it = layerErrorsMap.cbegin(); it != layerErrorsMap.cend(); ++it)
{
layerErrors += it.key()->name() + ": " + it.value().message() + "\n";
}
emit showLayerErrors(layerErrors);
}
// show the map
emit updateStatus("Complete");
emit hideWindow(1500, true);
m_mapView->setMap(generateJob->result()->offlineMap(this));
break;
default:
break;
}
});
// connect to progress changed signal
connect(generateJob, &GenerateOfflineMapJob::progressChanged, this, [this, generateJob]()
{
emit updateProgress(generateJob->progress());
});
// connect to the error signal
connect(generateJob, &GenerateOfflineMapJob::errorOccurred, this, [](Error e)
{
if (e.isEmpty())
return;
qDebug() << e.message() << e.additionalMessage();
});
// start the generate job
generateJob->start();
}
else
{
emit updateStatus("Export failed");
emit hideWindow(5000, false);
}
});
// generate parameters
m_offlineMapTask->createDefaultGenerateOfflineMapParameters(mapExtent);
}