Map Fundamentals
Zoom Levels
Zoom levels range from 0 (furthest, entire globe) to 17 (closest). Each zoom level offers a different level of detail, with numerically smaller zoom levels providing coarser details and numerically larger ones providing finer details. To avoid confusion, we recommend using the terms "coarse" and "fine" instead of "low" and "high" when differentiating between zoom levels.
Each successive zoom level (n + 1) contains 4 times the number of map tiles as the previous level (n). This means that as you increase the zoom level, the number of map tiles and the level of detail displayed on the map also increase.
The map radius determines the number of map tiles loaded in a given view.
To maintain optimal performance, limit the number of loaded map tiles!
As you increase the map radius beyond a certain threshold, a zoom level transition will occur. The new zoom level will contain map tiles that are 4 times the size of the previous zoom level, effectively limiting the number of map tiles in view.
This mechanism allows Lightship Maps to maintain a balance between visual detail and performance, ensuring that your map-based experiences run smoothly.
Maptile Data Updates
Lightship periodically generates a new set of maptiles for the entire globe using the most up-to-date map data available. Once these maptiles have been thoroughly tested and verified, the version number of the maptiles is incremented in the Maps settings service.
Clients will automatically begin to download the new maptiles when one of the following events occurs:
- The app is launched for the first time after the maptile version has been incremented.
- The app checks for new settings, which happens at 6-hour intervals.
For most maptile data updates, no action is required from the app's developers, as the updates are automatically handled by the Lightship Maps SDK. However, there are occasions when new maptile features are introduced that require developers to take action.
To take advantage of these new features, developers will need to upgrade their projects to a newer version of the Lightship Maps SDK. This will ensure that their apps remain up-to-date and compatible with the latest maptile enhancements.
Locally-cached Data
Downloaded maptile data is stored in a cache on the client's device to improve the performance of your map views. This cache enables faster loading times and reduces the need for constant re-downloading of maptiles, ultimately providing a smoother user experience.
The size of the cache is currently fixed at 30MB, which offers a balance between storage usage and performance. The cache directory is specified in the call to LightshipMapsSystem.Initialize() within your Unity project.
There might be instances where you need to clear the cache, such as when testing new maptile updates or troubleshooting issues. To clear the cache, simply delete the ntc file located in the cache directory specified during the initialization of the Lightship Maps package.
Feature Layers
Feature Layers (referred to as “Layer Kinds” in the SDK) are broad categories of physical features on the ground in the real world. Each Feature Layer consists of numerous Feature Kinds, as described below.
Lightship Maps Feature Layers are derived from OpenStreetMap’s primary Map Feature types.
These are the currently supported Feature Layers in Lightship Maps:
Boundaries - Used to describe administrative and other boundaries, such as regional and national boundaries, among others.
Country Region Other Buildings - Used to identify man-made structures, including residential buildings, landmarks, commercial buildings, and more.
Agricultural Industrial Services Commercial Landmark Sports Education Religious Transportation Government Residential Unused Healthcare Retail Hotel School Land Use - Used to describe areas of land with specific purposes, such as commercial, industrial, residential, and more.
Airport Military Runway Basin National Park Sand Cemetery Nature Reserve Scrub Farm Park Taxiway Farmland Parking Valley Forest Peak Wetland Garden Prison Wood Glacier Protected Area Golf Course Quarry Grass Recreation Area Meadow Rock Places - Used to identify and detail specific locations, typically corresponding to a type of settlement, such as a city, country, or neighborhood.
Borough Hamlet Town City Neighborhood Village Country Region Roads -Used to describe roads, footpaths, and more. Derived from OpenStreetMap’s Highway features.
Highway Parking Railway Major Road Path Runway Minor Road Pedestrian Taxiway Transit - Used to describe railways, subways, and more. Derived from OpenStreetMap’s Railway features.
Light Rail Platform Railway Station Subway Water - Used to describe bodies of water, both natural and man-made.
Basin Lake Sea Bay Ocean Strait Canal Playa Stream Ditch Reef Water Drain River Fjord Riverbank Undefined - uncategorized features
For more information on features, see the Map Feature Catalog.
Lightship Maps Core Library
The Lightship Maps Core Library enables Unity developers to stream, decode, and develop with Niantic Lightship’s Map database, giving you access to real-world geographic information which can be utilized in your Unity applications.
The Lightship Maps Core Library provides a robust and accessible API for gathering Map data to use in whatever way best suits the needs of your project.