경로

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

추가 및 삭제

지도 위에 경로를 추가하려면 InvRoute 객체를 생성한 다음 반드시 links 속성을 설정해주어야 합니다. links 속성은 setLinks() 함수를 사용하거나, 경로 객체 생성자를 통해 설정할 수 있습니다.

생성된 경로 객체의 map 속성을 표출하고자 하는 지도 객체로 설정하면 경로가 지도 위에 표출됩니다.

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
}

지도 위에 경로를 추가한 모습

반대로 지도에서 경로를 제거하려면 map 속성을 null로 설정하면 됩니다.

Kotlin

route.map = null // 지도에서 경로 제거

링크열

links 속성으로 경로의 링크열을 가져오거나 새로 설정할 수 있습니다. 링크열의 원소 개수는 1 이상이어야 합니다. links 속성을 설정하지 않았거나, 링크열의 원소 개수가 1 미만이면 InvalidLatLngException이 발생합니다.

links 속성을 설정하는데 사용한 객체 또는 이미 설정된 links 속성 객체의 원소를 추가하거나 삭제하더라도 지도에 변경사항이 반영되지 않습니다. 반드시 links 속성을 다시 설정해주어야 링크열의 변경사항이 반영됩니다.

Kotlin

val myLinks2 = mutableListOf(link1, link2, link3)
route.links = myLinks2

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

링크

경로의 링크열을 구성하기 위해서는 InvRoute.INVRouteLink 객체를 생성한 다음 반드시 coords 속성을 설정해주어야 합니다. coords 속성은 setCoords() 함수를 사용하거나, 링크 객체 생성자를 통해 설정할 수 있습니다.

좌표열

coords 속성으로 링크의 좌표열을 가져오거나 새로 설정할 수 있습니다. 좌표열의 원소 개수는 2 이상이어야 합니다. 좌표열의 원소 개수가 1 미만이거나, 좌표열 중 null인 좌표가 존재할 경우 InvalidLatLngException이 발생합니다.

색상

lineColor 속성으로 링크의 선 색상을, strokeColor 속성으로 링크의 테두리 색상을 각각 가져오거나 새로 설정할 수 있습니다. 이 속성으로 경로를 구간별로 다르게 표출할 수 있습니다.

경로 객체의 links 속성을 설정하는 데 사용한 각각의 링크는 속성을 변경하더라도 지도에 변경사항이 반영되지 않습니다. 반드시 경로 객체의 links 속성을 다시 설정해주어야 링크의 변경사항이 반영됩니다.

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)

경로의 선 및 테두리 색상을 링크별로 다르게 설정한 모습

선 두께

lineWidth 속성으로 경로의 선 두께를 가져오거나 새로 설정할 수 있습니다.

Kotlin

// 경로의 두께를 20px로 설정
route.lineWidth = 20

경로에 선 두께를 설정한 모습

테두리 두께

strokeWidth 속성으로 경로의 테두리 두께를 가져오거나 새로 설정할 수 있습니다.

Kotlin

// 경로의 두께를 10px로 설정
route.strokeWidth = 10

경로에 테두리 두께를 설정한 모습

경로 패턴

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

이미지 설정

patternImage 속성으로 패턴 이미지를 설정할 수 있습니다.

Kotlin

route.patternImage = InvImage(R.drawable.pattern_image)

간격 설정

patternMargin 속성으로 패턴 간격을 설정할 수 있습니다.

Kotlin

// 패턴의 간격을 35px로 설정
route.patternMargin = 35

크기 설정

patternScale 속성으로 이미지 크기를 경로의 두께 대비 배율로 설정할 수 있습니다.

Kotlin

// 이미지 크기를 경로 두께의 0.5 배로 설정
route.patternScale = 0.5

진행률

passRatio 속성으로 경로의 첫 지점으로부터 얼만큼 지나왔는지를 설정할 수 있습니다. 0.0~1.0 사이의 값으로 설정하며, 값이 0.0이면 경로의 모든 영역이 지나갈 구간으로, 1.0이면 경로의 모든 영역이 지나온 구간으로 간주됩니다. 지나온 구간과 선 색상과 테두리 색상을 다르게 설정하여 시각적으로 이동한 거리를 표출할 수도 있습니다.

Kotlin

// 경로의 진행률을 0.5로 설정
route.passRatio = 0.5

경로에 진행률을 설정한 모습

지나간 구간의 색상

passLineColor 속성과 passStrokeColor 속성으로 경로상 지나간 구간의 선 및 테두리 색상을 각각 가져오거나 새로 설정할 수 있습니다. 지나간 구간을 제외한 나머지 구간의 선 및 테두리 색상은 링크에 설정된 선 및 테두리 색상을 따릅니다.

Kotlin

route.passLineColor = Color.GRAY  // 경로상 지나간 구간의 선 색상을 회색으로 설정
route.passStrokeColor = Color.LTGRAY // 경로상 지나간 구간의 테두리 색상을 밝은 회색으로 설정

경로에 지나간 구간의 선과 테두리 색상을 설정한 모습

진행률 변경 이벤트

onRouteChangeListener 속성으로 경로의 진행률이 변경될 때의 이벤트를 감지할 수 있습니다. 이 리스너는 경로의 진행률이 특정 값으로 변경되었을 때 지도상의 위치, 각도, 지나온 거리를 콜백 함수의 파라미터로 전달합니다. 이 값들을 활용하여 경로를 따라 움직이는 마커를 지도에 그릴 수 있습니다.

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

경로 위를 따라 움직이는 마커를 추가한 모습