> For the complete documentation index, see [llms.txt](https://inavimaps-android.gitbook.io/sdkguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://inavimaps-android.gitbook.io/sdkguide/guide/shapes/introduction.md). # 개요 지도 위에 다양한 종류의 셰이프를 추가, 삭제 및 관리하는 방법에 대해 설명합니다. ## 셰이프 셰이프란 지도 위에 그려지는 모든 요소들을 의미합니다. 아이나비 지도 SDK는 개발자가 다양한 형태의 셰이프를 지도 위에 그릴 수 있는 기능을 지원합니다. 지도 위에 그릴 수 있는 셰이프 객체는 다음과 같습니다. 각 셰이프를 담당하는 클래스는 기본적으로 [`InvShape`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html) 클래스를 상속받습니다. * [**마커**](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvMarker.html)\ 지도 위에 특정 지점에 아이콘을 배치합니다. 기본적인 배치는 물론 이미지 회전, 타이틀, 앵커 등 다양한 속성들을 제공합니다. * [**정보 창**](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvInfoWindow.html)\ 지도 위 또는 마커 위에 아이콘을 배치합니다. 기본적으로 말풍선 아이콘에 텍스트가 포함된 형태가 제공되며, 개발자 편의에 따라 `View` 형태로 커스터마이징 할 수 있습니다. * [**폴리곤**](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvPolygon.html)\ 지도 위에 다각형 형태의 면을 배치합니다. * [**폴리라인**](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvPolyline.html)\ 지도 위에 선형을 배치합니다. * [**원**](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvCircle.html)\ 지도 위에 원 형태의 면을 배치합니다. * [**경로**](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvRoute.html)\ 지도 위에 경로에 특화된 선형을 배치합니다. ## 추가 및 삭제 ### 추가 지도 위에 그리고자 하는 셰이프의 객체를 생성하고, 그리고자 하는 지도의 객체를 [`map`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#setMap-com.inavi.mapsdk.maps.InaviMap-) 속성으로 설정하면 지도 위에 셰이프가 그려집니다. {% tabs %} {% tab title="Kotlin" %} ```kotlin // 지도상 (37.40219, 127.11077) 좌표에 위치하고, // 타이틀이 "타이틀"인 마커를 지도에 추가한다. val marker = InvMarker().apply { position = LatLng(37.40219, 127.11077) title = "타이틀" map = inaviMap } ``` {% endtab %} {% endtabs %} ### 삭제 셰이프 객체의 [`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 marker.map = null // 마커를 지도에서 삭제한다. ``` {% endtab %} {% endtabs %} ## 비트맵 사용 일부(마커, 정보 창 등) 셰이프는 비트맵 이미지를 사용합니다. 셰이프에서 비트맵 이미지를 사용하려면 `InvImage` 객체를 생성해야 합니다. ### 이미지 객체 생성 [`InvImage`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html)는 아이콘으로 사용될 수 있는 비트맵 이미지를 나타내는 불변 클래스입니다. [`InvImage`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html) 클래스의 생성자를 이용해 [드로어블 리소스](https://developer.android.com/guide/topics/resources/drawable-resource), Asset, 비트맵 등으로부터 인스턴스를 생성할 수 있습니다. [`InvImage`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html) 생성자에 들어갈 수 있는 인자는 다음과 같습니다. * [`InvImage(int resId)`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html#InvImage-int-) : 드로어블 리소스 ID로 객체 생성 * [`InvImage(String assetPath)`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html#InvImage-java.lang.String-) : Asset 영역에 존재하는 이미지로 객체 생성 * [`InvImage(Bitmap bitmap)`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html#InvImage-android.graphics.Bitmap-) : 비트맵 객체로 객체 생성 * [`InvImage(File file)`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html#InvImage-java.io.File-) : File 객체로 객체 생성 생성된 [`InvImage`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html) 객체를 비트맵 이미지를 사용하는 셰이프의 속성으로 설정하면 이미지가 지도에 반영됩니다. {% tabs %} {% tab title="Kotlin" %} ```kotlin // 드로어블 리소스 ID로 이미지 객체 생성 val image = InvImage(R.drawable.marker_icon) // 이미지를 지정하여 마커를 생성하고 지도에 배치 InvMarker().apply { position = LatLng(37.40219, 127.11077) iconImage = image map = inaviMap } ``` {% endtab %} {% endtabs %} {% hint style="danger" %} [`InvImage`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html)객체는 비트맵을 다루므로 사용 시 메모리 관리에 유의해야 합니다. 비트맵 이미지로 [`InvImage`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html) 객체를 생성할 때 동일한 이미지를 사용하는 여러 셰이프가 있을 경우 [`InvImage`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvImage.html)객체를 매번 생성하지 않도록 해야합니다. 그렇지 않으면 메모리 사용량 증가로 인해 지도 성능 저하가 발생할 수 있으며, 메모리 부족으로 프로세스가 강제 종료될 수 있습니다. {% endhint %} {% tabs %} {% tab title="Kotlin" %} ```kotlin // 올바른 예) // InvImage 객체를을 한 번만 생성하고 marker1, 2에서 이미지를 동일한 인스턴스로 설정 val image = InvImage(bitmap) marker1.iconImage = image marker2.iconImage = image // 잘못된 예) // marker3, 4에서 이미지를 설정할 때마다 InvImage 객체가 생성되어 메모리 사용량 증가의 원인이 됨 marker3.iconImage = InvImage(bitmap) marker4.iconImage = InvImage(bitmap) ``` {% endtab %} {% endtabs %} ## 겹침 우선순위 지도 위에 그려진 여러 셰이프에서 겹침이 발생하면 우선순위에 따라 위로 올라오는 셰이프가 결정됩니다. 겹침 우선순위는 셰이프의 유형에 따라 지정되지만 개발자가 임의로 변경할 수 있습니다. ### 전역 Z 인덱스 셰이프끼리 겹침이 발생할 경우, [`globalZIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getGlobalZIndex--) 속성에 따라 우선순위가 결정됩니다. 기본적으로 [`globalZIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getGlobalZIndex--)가 높은 셰이프가 낮은 셰이프를 덮게 됩니다. [`globalZIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getGlobalZIndex--)가 `0` 이상이면 심볼 위에, `0` 미만이면 심볼 아래에 그려지며, 값에 상관없이 지도 배경보다는 위에 그려집니다. 셰이프별 [`globalZIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getGlobalZIndex--) 기본값은 다음과 같습니다. * 정보 창 : `3000` * 위치 아이콘 : `2000` * 마커 : `1000` * *(지도 심볼)* * 폴리곤, 폴리라인, 원, 경로 : `-1000` * *(지도 배경)* 예를 들어 폴리곤은 기본적으로 지도 배경의 위, 지도 심볼의 아래에 그려집니다. 그러나 폴리곤의 [`globalZIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getGlobalZIndex--)를 `1000`으로 설정하면 지도 심볼의 위, 정보 창의 아래에 그려집니다. {% tabs %} {% tab title="Kotlin" %} ```kotlin // 셰이프별로 전역 Z 인덱스 변경 circle.globalZIndex = 3000 polyline.globalZIndex = 1000 marker.globalZIndex = -2000 ``` {% endtab %} {% endtabs %}
셰이프별로 전역 Z 인덱스를 변경한 모습
### 보조 Z 인덱스 겹침이 발생한 셰이프의 [`globalZIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getGlobalZIndex--)가 동일하다면, 기본적으로는 **나중에 추가된 셰이프**가 **먼저 추가된 셰이프**를 덮게 됩니다. [`zIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getZIndex--) 속성을 설정하여 우선순위를 변경할 수 있으며, 두 셰이프의 [`globalZIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getGlobalZIndex--) 값이 동일하다는 전제 하에 [`zIndex`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getZIndex--)의 값이 큰 셰이프가 작은 셰이프를 덮게 됩니다. {% tabs %} {% tab title="Kotlin" %} ```kotlin // 마커별로 보조 Z 인덱스 설정 redMarker.zIndex = 100 greenMarker.zIndex = 0 blueMarker.zIndex = -10 ``` {% endtab %} {% endtabs %}
마커별로 보조 Z 인덱스를 설정한 모습
## 표출상태 제어 각 셰이프는 상황에 따라 표출상태를 변경할 수 있는 속성들을 제공합니다. ### 표출 및 숨김 [`isVisible`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#isVisible--) 속성으로 지도에 셰이프를 표출할지 여부를 가져오거나 새로 설정할 수 있습니다. `false`로 설정하면 셰이프가 지도에서 표출되지 않습니다. 셰이프를 지도에서 제거하지 않으면서 표출 상태만 변경합니다. {% tabs %} {% tab title="Kotlin" %} ```kotlin // 마커를 지도에서 숨김 marker.isVisible = false ``` {% endtab %} {% endtabs %} ### 표출 줌 레벨 [`visibleMinZoom`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getVisibleMinZoom--) 및 [`visibleMaxZoom`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getVisibleMaxZoom--) 속성으로 지도에서 셰이프가 표출되는 최소/최대 줌 레벨을 가져오거나 새로 설정할 수 있습니다. 이 속성을 이용하여 특정 줌 레벨 범위에서만 셰이프가 표출되도록 할 수 있습니다. {% tabs %} {% tab title="Kotlin" %} ```kotlin // 마커가 줌 레벨 10~15 사이에서만 표출되도록 설정 marker.visibleMinZoom = 10.0f marker.visibleMaxZoom = 15.0f ``` {% endtab %} {% endtabs %} ## 태그 [`tag`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getTag--) 속성으로 셰이프에 부가적인 정보를 가져오거나 새로 설정할 수 있습니다. 예를 들면 마커의 클릭 횟수를 [`tag`](https://inavi-systems.github.io/inavi-maps-sdk-reference/android/com/inavi/mapsdk/style/shapes/InvShape.html#getTag--) 속성에 저장해두었다가 마커 클릭 리스너가 호출될 때마다 해당 값을 이용하여 클릭 횟수를 시각적으로 표출할 수 있습니다. {% tabs %} {% tab title="Kotlin" %} ```kotlin // 마커의 클릭 횟수를 0으로 초기화 marker.tag = 0 // 마커를 클릭할 때마다 tag 속성 값을 1씩 더하여 타이틀로 표출 marker.setOnClickListener { marker.tag = (it.tag as Int) + 1 marker.title = "마커 ${it.tag}회 클릭" true }� ``` {% endtab %} {% endtabs %}