---
description: >-
  링크 리스트를 이용하여 지도 위에 경로를 그릴 수 있습니다. 폴리라인이 단순히 지도 위에 선을 배치하는 개념이었다면, 경로는 테두리 색상 및
  두께, 진행률 등 경로에 더욱 특화된 기능을 제공합니다.
---

# 경로

## 추가 및 삭제 <a href="#add-and-remove" id="add-and-remove"></a>

지도 위에 경로를 추가하려면 [`InvRoute`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html) 객체를 생성한 다음 반드시 [`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 속성을 설정해주어야 합니다. [`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 속성은 [`setLinks()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 함수를 사용하거나, [경로 객체 생성자](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#InvRoute-java.util.List-)를 통해 설정할 수 있습니다.

생성된 경로 객체의  [`map`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#setMap-com.inavi.mapsdk.maps.InaviMap-) 속성을 표출하고자 하는 지도 객체로 설정하면 경로가 지도 위에 표출됩니다.&#x20;

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 첫 번째 링크
val link1 = InvRoute.InvRouteLink(
  listOf(
    LatLng(37.40235, 127.10970),
    LatLng(37.40248, 127.10970),
    LatLng(37.40262, 127.10970),
    LatLng(37.40277, 127.10970)
  )
)

// 두 번째 링크
val link2 = InvRoute.InvRouteLink(
  listOf(
    LatLng(37.40277, 127.10970),
    LatLng(37.40310, 127.10970),
    LatLng(37.40314, 127.10973),
    LatLng(37.40321, 127.10983),
    LatLng(37.40323, 127.10994),
    LatLng(37.40323, 127.11021)
  )
)

// 세 번째 링크
val link3 = InvRoute.InvRouteLink(
  listOf(
    LatLng(37.40323, 127.11021),
    LatLng(37.40323, 127.11039),
    LatLng(37.40323, 127.11050),
    LatLng(37.40323, 127.11072)
  )
)

val myLinks = listOf(link1, link2, link3)

// 지도 위에 경로 추가
val route = InvRoute().apply {
  links = myLinks
  map = inaviMap
}
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-M0QKUCtqQUhSVdGcRQ5%2F-M-99QG81d8xlAvwVJJz%2Fshapes-route-1.png?alt=media&#x26;token=f0b4bd7c-37a5-4ff8-a5fc-52cbdc916566" alt="지도 위에 경로를 추가한 모습"></div>

반대로 지도에서 경로를 제거하려면 [`map`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#setMap-com.inavi.mapsdk.maps.InaviMap-) 속성을 `null`로 설정하면 됩니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
route.map = null // 지도에서 경로 제거
```
{% endtab %}
{% endtabs %}

## 링크열 <a href="#links" id="links"></a>

[`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#getLinks--) 속성으로 경로의 링크열을 가져오거나 새로 설정할 수 있습니다. 링크열의 원소 개수는 `1` 이상이어야 합니다. [`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 속성을 설정하지 않았거나, 링크열의 원소 개수가 `1` 미만이면 [`InvalidLatLngException`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/exceptions/InvalidLatLngException.html)이 발생합니다.

[`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 속성을 설정하는데 사용한 객체 또는 이미 설정된 [`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#getLinks--) 속성 객체의 원소를 추가하거나 삭제하더라도 지도에 변경사항이 반영되지 않습니다. 반드시 [`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 속성을 다시 설정해주어야 링크열의 변경사항이 반영됩니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
val myLinks2 = mutableListOf(link1, link2, link3)
route.links = myLinks2

myLinks2.removeAt(myLinks2.size - 1) // 링크열의 마지막 원소 삭제
route.links = myLinks2 // links 속성을 다시 설정해주어야 지도에 반영된다.
```
{% endtab %}
{% endtabs %}

## 링크 <a href="#link" id="link"></a>

경로의 링크열을 구성하기 위해서는 [`InvRoute.INVRouteLink`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html) 객체를 생성한 다음 반드시 [`coords`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html#setCoords-java.util.List-) 속성을 설정해주어야 합니다. [`coords`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html#setCoords-java.util.List-) 속성은 [`setCoords()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html#setCoords-java.util.List-) 함수를 사용하거나, [링크 객체 생성자](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html#InvRouteLink-java.util.List-)를 통해 설정할 수 있습니다.

### 좌표열 <a href="#link-coords" id="link-coords"></a>

[`coords`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html#getCoords--) 속성으로 링크의 좌표열을 가져오거나 새로 설정할 수 있습니다. 좌표열의 원소 개수는  `2` 이상이어야 합니다.  좌표열의 원소 개수가 `1` 미만이거나, 좌표열 중 `null`인 좌표가 존재할 경우 [`InvalidLatLngException`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/exceptions/InvalidLatLngException.html)이 발생합니다.

### 색상 <a href="#link-color" id="link-color"></a>

[`lineColor`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html#getLineColor--) 속성으로 링크의 선 색상을, [`strokeColor`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.InvRouteLink.html#getStrokeColor--) 속성으로 링크의 테두리 색상을 각각 가져오거나 새로 설정할 수 있습니다. 이 속성으로 경로를 구간별로 다르게 표출할 수 있습니다.

경로 객체의 [`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 속성을 설정하는 데 사용한 각각의 링크는 속성을 변경하더라도 지도에 변경사항이 반영되지 않습니다. 반드시 경로 객체의 [`links`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setLinks-java.util.List-) 속성을 다시 설정해주어야 링크의 변경사항이 반영됩니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 첫 번째 링크를 선 색상 빨강, 테두리 색상 밝은 회색으로 설정
link1.lineColor = Color.RED
link1.strokeColor = Color.LTGRAY

// 두 번째 링크를 선 색상 초록, 테두리 색상 밝은 회색으로 설정
link2.lineColor = Color.GREEN
link2.strokeColor = Color.LTGRAY

// 세 번째 링크를 선 색상 파랑, 테두리 색상 밝은 회색으로 설정
link3.lineColor = Color.BLUE
link3.strokeColor = Color.LTGRAY

// links 속성을 다시 설정해주어야 지도에 반영된다.
route.links = listOf(link1, link2, link3)
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-M0QKUCtqQUhSVdGcRQ5%2F-M-D6j6SoAjYvrdHNlKw%2Fshapes-route-2.png?alt=media&#x26;token=24ff61f0-4de0-46f4-8b9b-ed1af65359dc" alt="경로의 선 및 테두리 색상을 링크별로 다르게 설정한 모습"></div>

## 선 두께 <a href="#line-width" id="line-width"></a>

[`lineWidth`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#getLineWidth--) 속성으로 경로의 선 두께를 가져오거나 새로 설정할 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 경로의 두께를 20px로 설정
route.lineWidth = 20
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-M0QKUCtqQUhSVdGcRQ5%2F-M-DYe2EuirDmTLYyPfA%2Fshapes-route-3.png?alt=media&#x26;token=a46a9550-62ae-487a-9048-6b29d243c1bb" alt="경로에 선 두께를 설정한 모습"></div>

## 테두리 두께  <a href="#stroke-width" id="stroke-width"></a>

[`strokeWidth`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#getStrokeWidth--) 속성으로 경로의 테두리 두께를 가져오거나 새로 설정할 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 경로의 두께를 10px로 설정
route.strokeWidth = 10
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-M0QKUCtqQUhSVdGcRQ5%2F-M-DnYxNtuKQuwtD-KQg%2Fshapes-route-4.png?alt=media&#x26;token=10de9c82-9f4a-4f0f-af34-319d858b5495" alt="경로에 테두리 두께를 설정한 모습"></div>

## 경로 패턴 <a href="#pattern" id="pattern"></a>

이미지를 일정 간격으로 패턴 처리하여 경로의 방향이나 다양한 모양의 경로를 표현할 수 있습니다.

### 이미지 설정 <a href="#patternimage" id="patternimage"></a>

[patternImage](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setPatternImage-com.inavi.mapsdk.style.shapes.InvImage-) 속성으로 패턴 이미지를 설정할 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
route.patternImage = InvImage(R.drawable.pattern_image)
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-MFYtdl3g1ZV1rOhTafT%2F-MFZO7z8DXWjMgqg4CIy%2Fimage.png?alt=media&#x26;token=af9251ac-24db-4a48-b18e-96a01faabdb5" alt=""></div>

### 간격 설정 <a href="#patternmargin" id="patternmargin"></a>

[patternMargin](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setPatternMargin-int-) 속성으로 패턴 간격을 설정할 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 패턴의 간격을 35px로 설정
route.patternMargin = 35
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-MFZP3JUQ-5esqiSyoJz%2F-MFZQI8JePO7ey-LAXPQ%2Fimage.png?alt=media&#x26;token=c27e4998-ef73-44bf-a30a-9271672d3992" alt=""></div>

### 크기 설정 <a href="#patternscale" id="patternscale"></a>

[patternScale](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setPatternScale-float-) 속성으로 이미지 크기를 경로의 두께 대비 배율로 설정할 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 이미지 크기를 경로 두께의 0.5 배로 설정
route.patternScale = 0.5
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-MFZP3JUQ-5esqiSyoJz%2F-MFZTzOx3fRKIBNQ4KH9%2Fimage.png?alt=media&#x26;token=999ccd5a-35cb-4a0f-8c78-2d74f151311e" alt=""></div>

## 진행률 <a href="#progress" id="progress"></a>

[`passRatio`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setPassRatio-double-) 속성으로 경로의 첫 지점으로부터 얼만큼 지나왔는지를 설정할 수 있습니다. `0.0`\~`1.0` 사이의 값으로 설정하며, 값이 `0.0`이면 경로의 모든 영역이 **지나갈 구간**으로, `1.0`이면 경로의 모든 영역이 **지나온 구간**으로 간주됩니다. 지나온 구간과 선 색상과 테두리 색상을 다르게 설정하여 시각적으로 이동한 거리를 표출할 수도 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 경로의 진행률을 0.5로 설정
route.passRatio = 0.5
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-M0QKUCtqQUhSVdGcRQ5%2F-M-E9poHIzEy2dK0PGrw%2Fshapes-route-5.png?alt=media&#x26;token=4723d425-af7f-47bc-ad45-8e72399af1e4" alt="경로에 진행률을 설정한 모습"></div>

### 지나간 구간의 색상 <a href="#pass-color" id="pass-color"></a>

[`passLineColor`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#getPassLineColor--) 속성과 [`passStrokeColor`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#getPassStrokeColor--) 속성으로 경로상 지나간 구간의 선 및 테두리 색상을 각각 가져오거나 새로 설정할 수 있습니다. 지나간 구간을 제외한 나머지 구간의 선 및 테두리 색상은 링크에 설정된 선 및 테두리 색상을 따릅니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
route.passLineColor = Color.GRAY  // 경로상 지나간 구간의 선 색상을 회색으로 설정
route.passStrokeColor = Color.LTGRAY // 경로상 지나간 구간의 테두리 색상을 밝은 회색으로 설정
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-M0QKUCtqQUhSVdGcRQ5%2F-M-EIOAl0AZHvQVllShf%2Fshapes-route-6.png?alt=media&#x26;token=9125f404-bd9e-4b62-a8ee-ef704da486c5" alt="경로에 지나간 구간의 선과 테두리 색상을 설정한 모습"></div>

### 진행률 변경 이벤트 <a href="#progress-change-event" id="progress-change-event"></a>

[`onRouteChangeListener`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html#setOnRouteChangeListener-com.inavi.mapsdk.style.shapes.InvRoute.OnRouteChangeListener-) 속성으로 경로의 진행률이 변경될 때의 이벤트를 감지할 수 있습니다. 이 리스너는 경로의 진행률이 특정 값으로 변경되었을 때 **지도상의 위치**, **각도**, **지나온 거리**를 콜백 함수의 파라미터로 전달합니다. 이 값들을 활용하여 경로를 따라 움직이는 마커를 지도에 그릴 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
// 경로 위에 배치될 마커 생성
val marker = InvMarker().apply {
  iconImage = InvImage(R.drawable.flat_marker_image)
  anchor = PointF(0.5f, 0.5f)
  isIconFlat = true
}

// 경로에 진행률 변경 리스너 설정
route.setOnRouteChangeListener { passPosition, passAngle, passDistance ->
  marker.position = passPosition
  marker.angle = passAngle.toFloat()
  if (!marker.isAttached) {
    marker.map = inaviMap
  }
}

// 경로의 진행률을 0.5로 설정
route.passRatio = 0.5
```
{% endtab %}
{% endtabs %}

<div align="left"><img src="https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-M0QKUCtqQUhSVdGcRQ5%2F-M-EPshepyhUgsjDp-2N%2Fshapes-route-7.png?alt=media&#x26;token=d6714713-f7d8-46f2-8d1a-4ac595ae237e" alt="경로 위를 따라 움직이는 마커를 추가한 모습"></div>
