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

# 클러스터링

## 개요 <a href="#introduction" id="introduction"></a>

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

### 아이템 <a href="#introduction-item" id="introduction-item"></a>

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

![아이템에 대한 마커가 지도에 표출된 모습](https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-MI1_FBONBrYLolDBxLT%2F-MI1aLy-ny16N2NNhL7j%2Fclustering-1.png?alt=media\&token=70f39273-835f-4624-9eea-a4e2eb09bf33)

### 클러스터 <a href="#introduction-cluster" id="introduction-cluster"></a>

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

![클러스터에 대한 마커가 지도에 표출된 모습](https://2296596695-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LjEmbGuGnOchPVUb5Zs%2F-MI1_FBONBrYLolDBxLT%2F-MI1aVQRFMqNE1QobbA4%2Fclustering-2.png?alt=media\&token=846013f4-8f38-4db7-83dc-9daef2e0ee02)

## 클러스터링 구성 <a href="#clustering-configuration" id="clustering-configuration"></a>

### 아이템 구성 <a href="#item-configuration" id="item-configuration"></a>

지도 위에 클러스터링을 적용하기 위해서는 먼저 [`ClusterItem`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterItem.html) 인터페이스를 구현한 데이터 클래스를 만들어야 합니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
data class MyItem(private val position: LatLng, val title: String) : ClusterItem {
  override fun getPosition() = position
}
```
{% endtab %}
{% endtabs %}

[`ClusterManager`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html) 클래스는 지도의 클러스터링을 관리합니다. 아이템 추가/삭제, 지도 위에 그려질 마커의 형태, 클릭 이벤트 등을 설정할 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```kotlin
private var clusterManager: ClusterManager<MyItem>? = null

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

### 아이템 관리 <a href="#item-settings" id="item-settings"></a>

[`ClusterManager`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html) 클래스에서 제공하는 함수로 클러스터링할 아이템을 추가하거나 삭제할 수 있습니다. 아이템의 구성요소가 변경되면 변경된 아이템들을 바탕으로 다시 클러스터링을 수행합니다.

| 구분           | 함수명                                                                                                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 단일 아이템 추가    | [`addItem()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html#addItem-T-)                      |
| 여러 개의 아이템 추가 | [`addItems()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html#addItems-java.util.List-)       |
| 단일 아이템 삭제    | [`removeItem()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html#removeItem-T-)                |
| 여러 개의 아이템 삭제 | [`removeItems()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html#removeItems-java.util.List-) |
| 모든 아이템 삭제    | [`clearItems()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html#clearItems--)                 |

### 지도에 그려질 마커 속성 <a href="#marker-properties" id="marker-properties"></a>

[`ClusterManager`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html) 객체에 [`onRenderListener`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html#setOnRenderListener-com.inavi.mapsdk.style.clustering.ClusterManager.OnRenderListener-) 속성을 설정하여 지도 위에 그려질 아이템 및 클러스터에 대한 **마커**의 아이콘 이미지, 타이틀 등을 설정할 수 있습니다.

[`ClusterManager.OnRenderListener`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.OnRenderListener.html)에는 **클러스터**가 그려지는 시점에 호출되는 [`onRenderCluster()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.OnRenderListener.html#onRenderCluster-com.inavi.mapsdk.style.clustering.Cluster-com.inavi.mapsdk.style.shapes.InvMarkerOptions-) 함수, **아이템**이 그려지는 시점에 호출되는 [`onRenderClusterItem()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.OnRenderListener.html#onRenderClusterItem-T-com.inavi.mapsdk.style.shapes.InvMarkerOptions-) 함수 두 가지가 있습니다.  두 콜백 함수 모두 파라미터로 [`InvMarkerOptions`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvMarkerOptions.html) 인터페이스를 구현한 객체가 전달되며, 이 객체를 통해 지도 위에 그려질 **마커**의 속성을 변경할 수 있습니다.

{% tabs %}
{% tab title="Kotlin" %}
```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}"
}
```
{% endtab %}
{% endtabs %}

### 마커 클릭 이벤트 <a href="#marker-click-event" id="marker-click-event"></a>

[`ClusterManager`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html) 객체에 [`onClickListener`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.html#setOnClickListener-com.inavi.mapsdk.style.clustering.ClusterManager.OnClickListener-)를 설정하면 지도에 표출된 아이템 또는 클러스터에 대한 마커를 클릭했을 때의 이벤트를 감지할 수 있습니다.&#x20;

[`ClusterManager.OnClickListener`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.OnClickListener.html)에는 **클러스터 마커**가 클릭된 시점에 호출되는 [`onClusterClick()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.OnClickListener.html#onClusterClick-com.inavi.mapsdk.style.clustering.Cluster-com.inavi.mapsdk.style.shapes.InvMarkerOptions-) 함수, **아이템 마커**가 클릭된 시점에 호출되는 [`onClusterItemClick()`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/clustering/ClusterManager.OnClickListener.html#onClusterItemClick-T-com.inavi.mapsdk.style.shapes.InvMarkerOptions-) 함수 두 가지가 있습니다.  두 콜백 함수 모두 파라미터로 [`InvMarkerOptions`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvMarkerOptions.html) 인터페이스를 구현한 객체가 전달되며, 이 객체를 통해 클릭된 **마커**의 속성을 변경할 수 있습니다.&#x20;

{% tabs %}
{% tab title="Kotlin" %}
```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이면 지도로 이벤트가 전달됨
}
```
{% endtab %}
{% endtabs %}

