> 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 %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://inavimaps-android.gitbook.io/sdkguide/guide/shapes/introduction.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.