Построение маршрутов

Входной точкой в API NaviKit SDK является класс YMKNavigation. В нем содержится основной функционал, связанный с навигацией и построением маршрутов.

Для создания нового экземпляра навигации используется вызов YMKNavigationFactory.createNavigation(with:).

let navigation = YMKNavigationFactory.createNavigation(with: .combined)

Запрос маршрутов

YMKNavigation предоставляет возможность строить оптимальные маршруты с помощью промежуточных точек маршрута.

Для запроса маршрутов используется метод YMKNavigation.requestRoutes(with:initialAzimuth:).

// Coordinates routes are requested for
let requestPoints = [
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.190614, longitude: 55.265616),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.187532, longitude: 55.275413),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.189279, longitude: 55.282246),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    ),
    YMKRequestPoint(
        point: YMKPoint(latitude: 25.196605, longitude: 55.280940),
        type: .waypoint,
        pointContext: nil,
        drivingArrivalPointId: nil
    )
]

navigation.requestRoutes(
    with: requestPoints,
    initialAzimuth: navigation.guidance.location?.heading
)

Первым аргументом передается список координат YMKRequestPoint, через которые будет проходить маршрут.

Точки маршрута делятся на два типа:

  • waypoint - используются для точек назначения. Например, для точек откуда, куда и точек остановок.
  • viapoint - используются для корректировки траектории маршрута. Маршрут будет проходить через все via-точки.

Вторым аргументом передается объект YMKDrivingOptions с параметрами ведения:

  • initialAzimuth - задает азимут направления пользователя в исходной точке маршрута.
  • routesCount - количество маршрутов для построения.

Примечание

Количество одновременных запросов маршрутов через YMKNavigation ограничено, активный запрос может быть только один. Если создать новый запрос до того, как предыдущий выполнится, то предыдущий будет отменен.

Как получить результат запроса маршрутов смотрите в разделе Результат запроса маршрутов.

Запрос маршрута по uri

YMKNavigation предоставляет возможность запрашивать маршрут по заранее сохраненному URI маршрута, при помощи метода YMKNavigation.resolveUri(withUri:).

Получение результатов запроса рассмотрено в разделе Результат запроса маршрутов.

Запрос альтернативных маршрутов

В ходе ведения по текущему маршруту существует возможность построить список альтернативных маршрутов. В терминологии NaviKit SDK такие маршруты называются глобальными альтернативами. Они требуют выполнения отдельного запроса.

Для этого используется асинхронный вызов YMKNavigation.requestAlternatives().

Как получить результат запроса альтернатив смотрите в разделе Результат запроса маршрутов.

События

При помощи интерфейса YMKNavigationListener существует возможность подписаться на сущность YMKNavigation, для получения событий об изменении внутреннего состояния навигации.

Результат запроса маршрутов

Вызовы YMKNavigation.requestRoutes(with:initialAzimuth:) и YMKNavigation.requestAlternatives() являются асинхронными, так как реализованы через сетевой запрос. Для обработки результата запроса нужно подписаться на события навигации при помощи YMKNavigationListener интерфейса.

class NavigationListener: NSObject, YMKNavigationListener {
    func onRoutesBuilt() {
        let routes = navigation.routes
        let fastestRoute = routes[0]
        // Routes received successfully ...
    }

    func onRoutesRequestErrorWithError(_ error: Error) {
        // An error occurred when requesting routes ...
    }

    // Override other listener's methods
}

// You have to subscribe to Navigation before calling the route/alternative request
navigation.addListener(navigationListener)

Метод-обработчик YMKNavigationListener.onRoutesBuilt() вызывается после успешного запроса маршрутов. Результат запроса маршрутов можно получить используя метод YMKNavigation.routes, который возвращает список маршрутов, соответствующих последнему запросу. Маршруты в этом списке отсортированы по возрастанию продолжительности поездки, самый быстрый маршрут будет находиться в списке первым.

О возникновении ошибки при запросе маршрутов можно узнать, реализовав метод YMKNavigationListener.onRoutesRequestErrorWithError(_:).

Создание нового запроса

При помощи YMKNavigationListener можно подписаться на события создания нового запроса к YMKNavigation, в зависимости от типа запрашиваемых маршрутов.

class NavigationListener: NSObject, YMKNavigationListener {
    func onRoutesRequested(with points: [YMKRequestPoint]) {
        // ...
    }

    func onAlternativesRequested(withCurrentRoute currentRoute: YMKDrivingRoute) {
        // ...
    }

    // Override other listener's methods
}

navigation.addListener(navigationListener)

Сброс маршрутов

При помощи метода YMKNavigationListener.onResetRoutes() можно подписаться на событие сброса состояния маршрутов.

Параметры запроса маршрутов

Существует возможность запроса маршрута с учетом дополнительных параметров, которые применяются с помощью методов YMKNavigation:

Грузовая навигация

NaviKit SDK способен запрашивать маршруты с учетом особенностей различных транспортных средств. Для применения параметров транспортных средств используйте вызов YMKNavigation.vehicleOptions.

Параметры транспортного средства передаются с помощью класса YMKDrivingVehicleOptions, в нем хранятся все данные, используемые при грузовых ограничениях. Например: габариты (высота, ширина, длина), параметры массы (фактическая, разрешенная, нагрузка на ось, грузоподъемность) и прочая информация (наличие прицепа, экологический класс и т.д.).

Пример запроса маршрутов для грузового транспортного средства с параметрами высоты 4,5 метра и общей массой 45 тонн:

navigation.vehicleOptions = {
    let options = YMKDrivingVehicleOptions()
    options.vehicleType = .truck
    options.height = 4.5,
    options.weight = 45
}()
navigation.requestRoutes(with: somePoints, initialAzimuth: nil)

После запроса маршрута с использованием YMKDrivingVehicleOptions, он будет построен с учетом переданных параметров выбранного транспортного средства.

Предыдущая
Общая архитектура
Следующая
Ведение
В этой статье: