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

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

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

val navigation = NavigationFactory.createNavigation(DrivingRouterType.COMBINED)

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

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

Для запроса маршрутов используется метод Navigation.requestRoutes.

// Coordinates routes are requested for
val requestPoints = listOf(
    RequestPoint(Point(25.190614, 55.265616), RequestPointType.Waypoint, null),
    RequestPoint(Point(25.187532, 55.275413), RequestPointType.Waypoint, null),
    RequestPoint(Point(25.189279, 55.282246), RequestPointType.Viapoint, null),
    RequestPoint(Point(25.196605, 55.280940), RequestPointType.Waypoint, null),
)
navigation.requestRoutes(
    requestPoints,
    navigation.guidance.location?.heading,
    3,
)

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

События

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

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

Вызовы Navigation.requestRoutes и Navigation.requestAlternatives являются асинхронными, так как реализованы через сетевой запрос. Для обработки результата запроса нужно подписаться на события навигации при помощи NavigationListener интерфейса.

val navigationListener = object : NavigationListener {
    override fun onRoutesBuilt() {
        val routes = navigation.routes
        val fastestRoute = routes[0]
        // Routes received successfully ...
    }

    override fun onRoutesRequestError(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)

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

О возникновении ошибки при запросе маршрутов можно узнать, реализовав метод NavigationListener.onRoutesRequestError.

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

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

val navigationListener = object : NavigationListener {
    override fun onRoutesRequested(requestPoints: List<RequestPoint>) {
        // ...
    }

    override fun onAlternativesRequested(currentRoute: DrivingRoute) {
        // ...
    }

    // Override other listener's methods
}
navigation.addListener(navigationListener)

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

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

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

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

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

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

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

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

navigation.vehicleOptions = VehicleOptions().apply {
    vehicleType = VehicleType.TRUCK,
    height = 4.5f,
    weight = 45f,
}
navigation.requestRoutes(somePoints, someDrivingOptions)

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

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