Draw points of interest using the Mapbox Vision SDK for iOS
Familiarity with Xcode and Swift, and completion of the Mapbox Vision SDK for iOS Install and configure
guide.
The Mapbox Vision SDK for iOS is a library for interpreting road scenes in real time directly on iOS devices using the device’s built-in camera. The Vision SDK detects many types of objects including cars, people, road signs, and more.
In this tutorial, you'll learn how to use geo-to-world and world-to-screen coordinate transformations available in the Mapbox Vision SDK and apply it to rendering points of interest (POIs) on the screen.
Getting started
Here are the resources that you need before getting started:
- An application including Mapbox Vision SDK for iOS. Before starting this tutorial, go through the Install and configure steps in the Vision SDK for iOS documentation. This will walk you through how to install the Vision SDK and configure your application.
- Recorded session. This tutorial is based on a recorded driving session through a city and the replay capabilities of
MapboxVision
. You may useVisionManager
andVisionReplayManager
interchangeably for live and recorded session respectively.- Check our Testing and development guide to familiarize yourself with record and replay functionality.
- You can download the recorded session used in this tutorial below.
Coordinate systems
The Vision SDK uses three coordinate systems: frame, world, and geo. You can translate your coordinates from one system to another with help of the VisionManager
and VisionReplayManager
methods geoToWorld(geoCoordinate:)
, worldToPixel(worldCoordinate:)
and inverse ones worldToGeo(worldCoordinates:)
, pixelToWorld(screenCoordinate:)
.
Camera.isCalibrated
value becomes true
.Frame coordinates
In the Mapbox Vision SDK for iOS, frame coordinates are represented by the Point2D
object.
This coordinate system represents the position of an object relative to the frame received from the camera. The origin is the left top corner of the frame. The position of an object is an x, y
pair where x
is the horizontal distance from the origin to the object in pixels, and y
is the vertical distance from the origin to the object in pixels.
World coordinates
In the Mapbox Vision SDK for iOS, the world coordinate is represented by the WorldCoordinate
object.
This coordinate system represents the position of an object relative to the device camera in the physical world. The origin of the system is a point projected from the camera to a road plane. The coordinate of the object is a triplet x, y, z
where x
is a distance to the object in front of the origin, y
is a distance on the left of the origin, and z
is a distance above the origin. Distance in the world coordinate system is expressed in meters.
Geographic coordinate
In the Mapbox Vision SDK for iOS, the geographic coordinate is represented by the GeoCoordinate
object.
This coordinate system is used to locate an object's geographic position as it would appear on a map. Each point is specified using longitude, latitude
pair.
Longitude ranges from -180
to 180
degrees, where 0
is the Greenwich meridian, the positive direction (+
) is to the East
, and the negative direction (-
) is to the West
.
Latitude ranges from -90
to +90
degrees, where 0
is the equator, the positive direction (+
) is to the North
, and the negative direction (-
) is to the South
.
Set up the recorded session
To configure your application with a prerecorded session (see Getting started to download the sample session used in this tutorial):
- Unzip the contents to a folder on your local machine.
- Go your Xcode project
Info.plist
and setYES
forUIFileSharingEnabled
thus enabling file sharing through Finder. - Install the app to the device (
⌘
+R
). - Connect your device, choose it in Finder under
Locations
section, and selectFiles
tab. - Drag and drop the folder with the recorded session onto your app. Now the session is available in the
Documents
folder inside the app container. - In the code use
VisionReplayManager.create(recordPath:)
method to create an instance ofVisionReplayManager
by providing a path to a recorded session.
Configure Vision SDK lifecycle
In this tutorial, you'll use VisionReplayManager
to run a prerecorded session (which includes video and telemetry data) and find POIs in the video. The VisionReplayManager
class is the main object for registering for events from the Vision SDK and controlling its delivery. For production applications or testing in a live environment, use VisionManager
instead of VisionReplayManager
. See the Next steps section for details.
To set up the Vision SDK:
- Create a
VisionReplayManager
instance with a recorded session path. - Register its
delegate
. - Create
VisionPresentationViewController
and configure it withVisionReplayManager
to display camera frames.
- Start delivering events by calling
start
onVisionReplayManager
.
- Stop delivering events by calling
stop
onVisionReplayManager
.