클러스터링

클러스터링 기능을 이용하여 여러 개의 데이터를 그룹화하여 지도 위에 표출할 수 있습니다.

개요

클러스터링이란 주어진 개체들을 여러 개의 그룹으로 묶는 일련의 작업을 의미합니다. 아이나비 지도 SDK는 지도의 줌 레벨에 따라 지도상에 표출된 인접한 마커들을 묶어 클러스터를 만들고, 지도 위에 마커로 표출하는 기능을 제공합니다.

아이템

클러스터링할 최소한의 데이터 단위를 의미합니다. 지점을 기반으로 클러스터링이 이루어지기 때문에 지점 위치 속성이 반드시 필요합니다. 지도 위에 마커 형태로 표출됩니다.

아이템에 대한 마커가 지도에 표출된 모습

클러스터

그룹화 된 아이템 또는 클러스터를 의미합니다. 클러스터 역시 줌 레벨에 따라 인접한 아이템 또는 클러스터와 묶여질 수 있습니다. 지도 위에 마커 형태로 표출됩니다.

클러스터에 대한 마커가 지도에 표출된 모습

클러스터링 구성

아이템 구성

지도 위에 클러스터링을 적용하기 위해서는 먼저 ClusterItem 인터페이스를 구현한 데이터 클래스를 만들어야 합니다.

Kotlin

data class MyItem(private val position: LatLng, val title: String) : ClusterItem {
  override fun getPosition() = position
}

ClusterManager 클래스는 지도의 클러스터링을 관리합니다. 아이템 추가/삭제, 지도 위에 그려질 마커의 형태, 클릭 이벤트 등을 설정할 수 있습니다.

Kotlin

private var clusterManager: ClusterManager<MyItem>? = null

override fun onMapReady(inaviMap: InaviMap) {
    clusterManager = ClusterManager<MyItem>(this, inaviMap)
}

아이템 관리

ClusterManager 클래스에서 제공하는 함수로 클러스터링할 아이템을 추가하거나 삭제할 수 있습니다. 아이템의 구성요소가 변경되면 변경된 아이템들을 바탕으로 다시 클러스터링을 수행합니다.

구분	함수명
단일 아이템 추가	addItem()
여러 개의 아이템 추가	addItems()
단일 아이템 삭제	removeItem()
여러 개의 아이템 삭제	removeItems()
모든 아이템 삭제	clearItems()

지도에 그려질 마커 속성

ClusterManager 객체에 onRenderListener 속성을 설정하여 지도 위에 그려질 아이템 및 클러스터에 대한 마커의 아이콘 이미지, 타이틀 등을 설정할 수 있습니다.

ClusterManager.OnRenderListener에는 클러스터가 그려지는 시점에 호출되는 onRenderCluster() 함수, 아이템이 그려지는 시점에 호출되는 onRenderClusterItem() 함수 두 가지가 있습니다. 두 콜백 함수 모두 파라미터로 InvMarkerOptions 인터페이스를 구현한 객체가 전달되며, 이 객체를 통해 지도 위에 그려질 마커의 속성을 변경할 수 있습니다.

Kotlin

// Activity가 ClusterManager.OnRenderListener를 구현함

// OnRenderListener 설정
override fun onMapReady(inaviMap: InaviMap) {
  // ...
  clusterManager?.onRenderListener = this
}

// 콜백 함수 구현
// '클러스터'가 그려지는 시점에 호출되는 콜백 함수
override fun onRenderCluster(cluster: Cluster<MyItem>, markerOptions: InvMarkerOptions) {
  markerOptions.position = cluster.position
}

// '아이템'이 그려지는 시점에 호출되는 콜백 함수
override fun onRenderClusterItem(clusterItem: MyItem, markerOptions: InvMarkerOptions) {
  markerOptions.position = clusterItem.position
  markerOptions.iconImage = InvMarkerIcons.RED
  markerOptions.title = "${clusterItem.title}"
}

마커 클릭 이벤트

ClusterManager 객체에 onClickListener를 설정하면 지도에 표출된 아이템 또는 클러스터에 대한 마커를 클릭했을 때의 이벤트를 감지할 수 있습니다.

ClusterManager.OnClickListener에는 클러스터 마커가 클릭된 시점에 호출되는 onClusterClick() 함수, 아이템 마커가 클릭된 시점에 호출되는 onClusterItemClick() 함수 두 가지가 있습니다. 두 콜백 함수 모두 파라미터로 InvMarkerOptions 인터페이스를 구현한 객체가 전달되며, 이 객체를 통해 클릭된 마커의 속성을 변경할 수 있습니다.

Kotlin

// Activity가 ClusterManager.OnClickListener를 구현함

// ClusterManager.OnClickListener 설정
clusterManager?.onClickListener = this

// 콜백 함수 구현
// '클러스터'가 클릭된 시점에 호출되는 콜백 함수
override fun onClusterClick(cluster: Cluster<MyItem>, markerOptions: InvMarkerOptions): Boolean {
    Toast.makeText(this, "클러스터 클릭", Toast.LENGTH_SHORT).show()
    return true // 이벤트 소비 여부. false이면 지도로 이벤트가 전달됨
  }

// '아이템'이 클릭된 시점에 호출되는 콜백 함수
override fun onClusterItemClick(clusterItem: MyItem, markerOptions: InvMarkerOptions): Boolean {
  Toast.makeText(this, "아이템 클릭", Toast.LENGTH_SHORT).show()
  return true // 이벤트 소비 여부. false이면 지도로 이벤트가 전달됨
}