MapPolylineShape

MapPolylineShape에 대한 설명 및 사용 방법.

지도 좌표상으로 특정 지점에 의미있는 선형을 표시하고자 할 때 MapPolylineShape를 사용합니다. MapPolylineShape는 하나 이상의 MapPolyline으로 구성되며, MapPolyline은 두개 이상의 점으로 구성할 수 있습니다. MapPolylineShape는 Polyline을 구성하는 점들을 레벨에 따라 디테일한 정도를 내부적으로 조정하는 LOD(Level Of Detail)처리 없이 Polyline 형태 그대로 보여주기 때문에, 길찾기 라인을 표시하기에는 적합하지 않습니다. 길찾기 라인은 Route 페이지를 참고하시기 바랍니다.

PolylineStyleSet


PolylineStyleSet은 MapPolygonShape가 어떻게 표시될지를 정의합니다. PolygonStyleSet은 ShapeManager를 통해 생성할 수 있으며, 같은 styleID로는 overwrite 할 수 없습니다. PolylineStyleSet은 하나 이상의 PolylineStyle로 이루어져 있으며, PolylineStyle은 하나 이상의 레벨별 스타일(PerLevelPolylineStyle)로 구성됩니다. 그림으로 표시하면 styleSet의 구성은 아래와 같습니다.

PolylineShapeStyleSet

StyleSet에 여러개의 Style을 추가하면 추가한 순서대로 index가 부여되고, 여러개의 MapPolyline으로 이루어진 MapPolylineShape에 해당 styleSet을 적용하여 각 MapPolyline마다 사용할 styleIndex를 지정할 수 있습니다.

PolylineStyle

PolylineStyle을 구성하는 단위 레벨별 스타일의 구성요소는 아래와 같습니다.

Property Description
bodyColor Polyline의 body color
bodyWidth Polyline의 body 두께
strokeColor Polyline의 외곽선 색깔
strokeWidth Polyline의 외곽선 두께
level 해당 단위 스타일이 표출될 레벨

PolylineStyleSet 생성하기

PolylineStyleSet을 구성하는 프로퍼티는 아래와 같습니다.

Property Description
styleSetID PolylineStyleSet의 ID. 폴리라인은 이 ID를 키로 style을 사용할 수 있다
styles StyleSet을 구성하는 1개 이상의 PolylineStyle
capType Polyline의 cap type.
- PolylineCapTypeRound: Polyline 시작/끝 지점에 Round형태의 Cap
- PolylineCapTypeSquare: Polyline 시작/끝 지점에 Square형태의 Cap
- PolylineCapTypeButt: Polyline 시작/끝지점에 Butt형태의 Cap
- PolylineCapTypeArrow:Polyline 끝지점에 Arrow형태의 Cap. 해당 타입 사용시 Polyline의 stroke는 3이하로 권장
- PolylineCapTypeArrowRound: Polyline 끝지점에 ArrowRound형태의 Cap. 해당 타입 사용시 Polyline의 stroke는 3이하로 권장

PolylineShape

아래 예제는 위 스크린샷과 같은 형태의 1개의 Polyline을 갖는 PolylineShape를 표시하는 스타일을 생성하는 예제입니다.

    // StyleSet을 생성한다.
    // PolylineStyleSet은 한 개 이상의 PolylineStyle로 구성되고, PolylineStyle은 한 개 이상의 레벨별 스타일인 PerLevelPolylineStyle로 구성된다.
    // PerLevelPolylineStyle은 지정된 Polyline이 해당 레벨에서 어떻게 그려질지를 결정한다. 스타일이 지정되지 않았거나, 해당 레벨이 스타일이 지정되지 않은 구간이라면 Polyline은 그려지지 않는다.
    func createPolylineStyleSet() {
        let mapView = mapController?.getView("mapview") as! KakaoMap
        let manager = mapView.getShapeManager()
        let _ = manager.addShapeLayer(layerID: "PolylineLayer", zOrder: 10000)
        
        // 첫번째 슽아ㅣㄹ
        // 0 ~ 13레벨 : 빨간색의 외곽선을 가지는 파란색 선
        // 14 ~ 16레벨 : 초록색의 외곽선을 가지는 빨간색 선
        // 17 ~ 21레벨 : 빨간색의 외곽선을 가지는 녹샋선
        let polylineStyle = PolylineStyle(styles: [
            PerLevelPolylineStyle(bodyColor: UIColor.blue, bodyWidth: 4, strokeColor: UIColor.red, strokeWidth: 1, level: 0),
            PerLevelPolylineStyle(bodyColor: UIColor.red, bodyWidth: 8, strokeColor: UIColor.green, strokeWidth: 2, level: 14),
            PerLevelPolylineStyle(bodyColor: UIColor.green, bodyWidth: 16, strokeColor: UIColor.red, strokeWidth: 3, level: 17)
        ])
        
        // 두번째 스타일
        // 0 ~ 13레벨 : 검정색의 외곽선을 가지는 하얀색 선
        // 14 ~ 16레벨 : 검정색의 외곽선을 가지는 회색 선
        // 17 ~ 21레벨 : 흰색의 외곽선을 가지는 검정 선
        let polylineStyle2 = PolylineStyle(styles: [
            PerLevelPolylineStyle(bodyColor: UIColor.white, bodyWidth: 4, strokeColor: UIColor.black, strokeWidth: 1, level: 0),
            PerLevelPolylineStyle(bodyColor: UIColor.gray, bodyWidth: 8, strokeColor: UIColor.black, strokeWidth: 2, level: 14),
            PerLevelPolylineStyle(bodyColor: UIColor.black, bodyWidth: 16, strokeColor: UIColor.white, strokeWidth: 3, level: 17)
        ])
        
        // 두가지 스타일을 갖는 Set을 만든다. PolylineShape가 해당 StyleSet을 사용하면,
        // 각 폴리라인마다 스타일을 다르게 지정할 수 있다.
        manager.addPolylineStyleSet(PolylineStyleSet(styleSetID: "polylineStyleSet", styles: [polylineStyle, polylineStyle2]))
    }
    
    // MapPolylineShape를 생성한다.
    // MapPolyline은 별도의 base position없이 일련의 지도 좌표계(MapPoint)로 구성할 수 있다.
    func createMapPolylineShape() {
        let mapView: KakaoMap = mapController?.getView("mapview") as! KakaoMap
        let manager = mapView.getShapeManager()
        let layer = manager.getShapeLayer(layerID: "PolylineLayer")
        
        let size: CGSize = (mapView.viewRect.size)
        let center = mapView.getPosition(CGPoint(x: size.width/2, y: size.height/2))
        
        // line Point를 잇는 MapPolyline을 생성한다.
        // MapPolylineShape는 여러개의 MapPolyline으로 구성할 수 있다.
        let outterRect = MapPolyline(line: Primitives.getRectanglePoints(width: 100, height: 200, cw: true, center: center), capType: .both, styleIndex: 0)
        let innerRect = MapPolyline(line: Primitives.getRectanglePoints(width: 50, height: 100, cw: true, center: center), capType: .both, styleIndex: 1)
    
        // outterRect, innerRect 두개의 MapPolyline으로 구성된 MapPolylineShape를 생성한다.
        // MapPolylineShape는 id = "polylineStyleSet"인 StyleSet을 사용한다.
        // outter MapPolyline은 polylineStyleSet의 인덱스 0 인 스타일을 사용하며,
        // inner MapPolyline은 polylineStyleSet의 인덱스 1인 스타일을 사용한다.
        let options = MapPolylineShapeOptions(shapeID: "rects", styleID: "polylineStyleSet", zOrder: 1)
        options.polylines.append(outterRect)
        options.polylines.append(innerRect)
        
        // MapPolylineShape를 추가한다. 추가가 완료되었을 때의 콜백을 정의하면, 작업이 완료되었을 때 콜백을 받을 수 있다.
        let shape = layer?.addMapPolylineShape(options)
        shape?.show()
    }

MapPolylineShapeOptions


MapPolylineShape는 사용자가 직접 생성할 수 없습니다. ShapeManager를 통해 생성한 ShapeLayer에 아래와 같이 addMapPolylineShape를 호출하면서 생성 옵션을 넘기면, API 내부적으로 생성된 MapPolylineShape객체를 받아올 수 있습니다.

        // line Point를 잇는 MapPolyline을 생성한다.
        // MapPolylineShape는 여러개의 MapPolyline으로 구성할 수 있다.
        let outterRect = MapPolyline(line: Primitives.getRectanglePoints(width: 100, height: 200, cw: true, center: center), capType: .both, styleIndex: 0)
        let innerRect = MapPolyline(line: Primitives.getRectanglePoints(width: 50, height: 100, cw: true, center: center), capType: .both, styleIndex: 1)
    
        // outterRect, innerRect 두개의 MapPolyline으로 구성된 MapPolylineShape를 생성한다.
        // MapPolylineShape는 id = "polylineStyleSet"인 StyleSet을 사용한다.
        // outter MapPolyline은 polylineStyleSet의 인덱스 0 인 스타일을 사용하며,
        // inner MapPolyline은 polylineStyleSet의 인덱스 1인 스타일을 사용한다.
        let options = MapPolylineShapeOptions(shapeID: "rects", styleID: "polylineStyleSet", zOrder: 1)
        options.polylines.append(outterRect)
        options.polylines.append(innerRect)
        
        // MapPolylineShape를 추가한다. 추가가 완료되었을 때의 콜백을 정의하면, 작업이 완료되었을 때 콜백을 받을 수 있다.
        let shape = layer?.addMapPolylineShape(options)
        shape?.show()

MapPolylineShapeOptions의 속성은 아래와 같습니다. 각 Property를 지정하여 다양한 형태의 MapPolylineShape를 생성할 수 있습니다.

Property Description
shapeID PolylineShape 고유 ID. 같은 Layer안에서 중복 ID를 가질 수 없습니다. ID는 Layer 범위 내에서 유니크합니다.
styleID PolylineShape가 사용할 styleID.
PolylineShape를 생성하는 시점에서 style은 미리 생성되어 있어야 합니다.
zOrder PolylineShape의 렌더링 우선순위. Layer내에서 먼저 그려질지 결정하는 기준이 됩니다.
polylines MapPolylineShape를 구성할 하나 이상의 MapPolyline 배열.
MapPolyline은 두개 이상의 위경도 좌표로 구성된 Line으로 구성할 수 있습니다.

MapPolyline

MapPolyline은 MapPolylineShape의 구성요소입니다. MapPolylineShape는 하나 이상의 MapPolyline으로 이루어져 있습니다. MapPolyline의 Property는 아래와 같습니다.

Property Description
line MapPolyline을 구성하는 2개 이상의 Point. 위경도 좌표로 구성한다.
styleIndex MapPolyline이 StyleSet에서 사용할 스타일 인덱스

MapPolylineShape Properties


생성된 MapPolylineShape는 아래와 같은 종류의 Property를 가지고 있습니다. get only property를 제외하고는, property값을 바꾸면 새로운 값으로 반영됩니다.

Property Description
layerID MapPolylineShape가 속한 layerID
shapeID MapPolylineShape의 고유 ID
orientation shape의 orientation. 값을 변경하면 업데이트됩니다.
isShow PolylineShape가 현재 뷰에 표시되고 있는지 여부

Style 및 Polyline 바꾸기


MapPolylineShape는 style과 MapPolylineShape를 구성하는 MapPolyline을 함께 바꾸는 인터페이스를 제공합니다. 사용 방법은 PolylineShape를 바꾸는 방법과 동일합니다.

Animator


MapPolylineShape는 Animator를 이용하여 애니메이션 효과를 적용할 수 있습니다. 특정 애니메이션 효과 옵션을 적용하여 ShapeManager를 통해 Animator를 생성할 수 있습니다. ShapeManager에서는 ShapeAnimator의 추가 및 삭제등의 관리를 하고 있습니다. 한번 생성한 Animator는 지우기 전까지 ShapeManager에서 관리하고 있으므로, ID를 이용해서 ShapeManager에서 가져올 수 있습니다.

MapPolylineShape에 Animator를 적용하는 방법은 PolylineShape Animator 사용방법과 동일합니다.