15주년을 맞이한 Google Maps Platform - 최신 뉴스 및 공지사항 확인하기

경로 및 영역을 나타내는 다중선 및 다각형

이 가이드에서는 Android 앱에 Google 지도를 추가하고 지도에서 다중선과 다각형을 사용하여 경로와 영역을 나타내는 방법을 설명합니다.

가이드의 설명에 따라 Maps SDK for Android를 사용하여 Android 앱을 빌드합니다. 권장되는 개발 환경은 Android 스튜디오입니다.

코드 가져오기

GitHub에서 Google Maps Android API v2 샘플 저장소를 복제하거나 다운로드합니다.

개발 프로젝트 설정

다음 단계에 따라 Android 스튜디오에서 가이드 프로젝트를 만듭니다.

  1. Android 스튜디오를 다운로드하여 설치합니다.
  2. Android 스튜디오에 Google Play 서비스 패키지를 추가합니다.
  3. 이 가이드를 읽기 전에 미리 하지 않은 경우 Google Maps Android API v2 샘플 저장소를 복제하거나 다운로드합니다.
  4. 가이드 프로젝트를 가져옵니다.

    • Android 스튜디오에서 File > New > Import Project를 선택합니다.
    • Google Maps Android API v2 샘플 저장소를 다운로드한 후 저장한 위치로 이동합니다.
    • 다음 위치에서 Polygons 프로젝트를 찾습니다.
      PATH-TO-SAVED-REPO/android-samples/tutorials/Polygons
    • 프로젝트 디렉터리를 선택한 다음 OK를 클릭합니다. 이제 Android 스튜디오에서 Gradle 빌드 도구를 사용하여 프로젝트를 빌드합니다.

API 키 가져오기 및 필요한 API 사용 설정

이 가이드를 완료하려면 Maps SDK for Android를 사용할 수 있도록 승인된 Google API 키가 필요합니다.

다음 버튼을 클릭하여 키를 가져오고 API를 활성화합니다.

시작하기

자세한 내용은 API 키 가져오기에 관한 전체 가이드를 참고하세요.

앱에 API 키 추가

  1. 프로젝트의 gradle.properties 파일을 수정합니다.
  2. API 키를 GOOGLE_MAPS_API_KEY 속성의 값에 붙여넣습니다. 앱을 빌드할 때 Gradle에서 아래 설명된 대로 API 키를 앱의 Android 매니페스트에 복사합니다.

    GOOGLE_MAPS_API_KEY=PASTE-YOUR-API-KEY-HERE
    

앱 빌드 및 실행

  1. 컴퓨터에 Android 기기를 연결합니다. 안내에 따라 Android 기기에서 개발자 옵션을 사용 설정하고 기기를 감지하도록 시스템을 구성합니다. (또는 Android Virtual DeviceAndroid(AVD) Manager를 사용하여 가상 기기를 구성할 수 있습니다. 에뮬레이터를 선택할 때 Google API가 포함된 이미지를 선택해야 합니다. 자세한 내용은 시작 가이드를 참고하세요.)
  2. Android 스튜디오에서 Run 메뉴 옵션(또는 재생 버튼 아이콘)을 클릭합니다. 표시되는 메시지에 따라 기기를 선택합니다.

Android 스튜디오에서 Gradle을 호출하여 앱을 빌드한 다음 기기 또는 에뮬레이터에서 앱을 실행합니다.

이 페이지의 이미지와 비슷하게, 오스트레일리아 위에 다각형 두 개가 오버레이된 지도가 표시됩니다.

문제해결:

코드 이해하기

여기에서는 유사한 앱을 빌드하는 방법을 이해할 수 있도록 Polygons 앱의 가장 중요한 부분을 설명합니다.

Android 매니페스트 확인

앱의 AndroidManifest.xml 파일에서 다음 요소를 확인합니다.

  • meta-data 요소를 추가하여 앱이 컴파일된 Google Play 서비스의 버전을 삽입합니다.

    <meta-data
        android:name="com.google.android.gms.version"
        android:value="@integer/google_play_services_version" />
    
  • API 키를 지정하는 meta-data 요소를 추가합니다. 이 가이드에 포함된 샘플에서는 API 키의 값을 google_maps_key 문자열로 매핑합니다. 앱을 빌드할 때 Gradle에서 프로젝트의 gradle.properties 파일에 있는 API 키를 문자열 값에 복사합니다.

    <meta-data
      android:name="com.google.android.geo.API_KEY"
      android:value="@string/google_maps_key" />
    

    API 키가 문자열 값에 매핑되는 방식은 앱의 build.gradle을 확인하세요. 다음과 같이 google_maps_key 문자열을 GOOGLE_MAPS_API_KEY gradle 속성으로 매핑하는 행이 포함되어 있습니다.

    resValue "string", "google_maps_key",
            (project.findProperty("GOOGLE_MAPS_API_KEY") ?: "")
    

다음은 매니페스트의 전체 예입니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.polygons">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

        <!--
             The API key for Google Maps-based APIs.
        -->
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="@string/google_maps_key" />

        <activity
            android:name="com.example.polygons.PolyActivity"
            android:label="@string/title_activity_maps">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

지도 추가

Maps SDK for Android를 사용하여 지도를 표시합니다.

  1. 활동의 레이아웃 파일인 activity_maps.xml<fragment> 요소를 추가합니다. 이 요소는 지도의 컨테이너 역할을 하고 GoogleMap 객체에 대한 액세스 권한을 제공하도록 SupportMapFragment를 정의합니다. 이 가이드에서는 이전 버전 Android 프레임워크와의 호환성을 보장하기 위해 지도 프래그먼트의 Android 지원 라이브러리 버전을 사용합니다.

    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context="com.example.polygons.PolyActivity" />
    
    
  2. 활동의 onCreate() 메서드에서 레이아웃 파일을 콘텐츠 뷰로 설정합니다. FragmentManager.findFragmentById()를 호출하여 지도 프래그먼트의 핸들을 가져옵니다. 그런 다음 getMapAsync()를 사용하여 지도 콜백에 등록합니다.

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps);
    
        // Get the SupportMapFragment and request notification when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(map);
        mapFragment.getMapAsync(this);
    }
    
  3. OnMapReadyCallback 인터페이스를 구현하고 onMapReady() 메서드를 재정의합니다. GoogleMap 객체를 사용할 수 있을 때 API가 이 콜백을 호출하므로 지도에 객체를 추가하고 앱에 맞게 맞춤설정할 수 있습니다.

    public class PolyActivity extends AppCompatActivity
            implements
                    OnMapReadyCallback,
                    GoogleMap.OnPolylineClickListener,
                    GoogleMap.OnPolygonClickListener {
    
        // More code goes here, including the onCreate() method described above.
    
        @Override
        public void onMapReady(GoogleMap googleMap) {
    
            // Add polylines and polygons to the map. This section shows just
            // a single polyline. Read the rest of the tutorial to learn more.
            Polyline polyline1 = googleMap.addPolyline(new PolylineOptions()
                    .clickable(true)
                    .add(
                            new LatLng(-35.016, 143.321),
                            new LatLng(-34.747, 145.592),
                            new LatLng(-34.364, 147.891),
                            new LatLng(-33.501, 150.217),
                            new LatLng(-32.306, 149.248),
                            new LatLng(-32.491, 147.309)));
    
            // Position the map's camera near Alice Springs in the center of Australia,
            // and set the zoom factor so most of Australia shows on the screen.
            googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(-23.684, 133.903), 4));
    
            // Set listeners for click events.
            googleMap.setOnPolylineClickListener(this);
            googleMap.setOnPolygonClickListener(this);
        }
    }
    

다중선을 추가하여 지도에 선 그리기

Polyline은 일련의 연결된 선분입니다. 다중선은 지도에서 경로 또는 기타 위치 간 연결을 나타내는 데 유용합니다.

  1. PolylineOptions 객체를 만들고 여기에 점을 추가합니다. 각 점은 위도 및 경도 값이 포함된 LatLng 객체를 사용하여 정의하는 지도상의 한 위치를 나타냅니다. 아래의 코드 샘플에서는 점 6개로 다중선을 만듭니다.

  2. GoogleMap.addPolyline()을 호출하여 지도에 다중선을 추가합니다.

    Polyline polyline1 = googleMap.addPolyline(new PolylineOptions()
            .clickable(true)
            .add(
                    new LatLng(-35.016, 143.321),
                    new LatLng(-34.747, 145.592),
                    new LatLng(-34.364, 147.891),
                    new LatLng(-33.501, 150.217),
                    new LatLng(-32.306, 149.248),
                    new LatLng(-32.491, 147.309)));
    

다중선의 클릭 이벤트를 처리하려면 다중선의 clickable 옵션을 true로 설정합니다. 이 가이드의 뒷부분에 이벤트 처리에 대해 자세히 설명되어 있습니다.

다중선과 함께 임의의 데이터 저장

다중선 및 기타 도형 객체와 함께 임의의 데이터 객체를 저장할 수 있습니다.

  1. Polyline.setTag()를 호출하여 다중선과 함께 데이터 객체를 저장합니다. 아래 코드에서는 다중선의 유형을 나타내는 임의의 태그(A)를 정의합니다.

    Polyline polyline1 = googleMap.addPolyline(new PolylineOptions()
            .clickable(true)
            .add(
                    new LatLng(-35.016, 143.321),
                    new LatLng(-34.747, 145.592),
                    new LatLng(-34.364, 147.891),
                    new LatLng(-33.501, 150.217),
                    new LatLng(-32.306, 149.248),
                    new LatLng(-32.491, 147.309)));
    // Store a data object with the polyline, used here to indicate an arbitrary type.
    polyline1.setTag("A");
    
  2. 다음 섹션에 설명된 대로 Polyline.getTag()를 사용하여 데이터를 가져옵니다.

다중선에 맞춤 스타일 추가

PolylineOptions 객체에서 다양한 스타일 속성을 지정할 수 있습니다. 스타일 지정 옵션에는 획 색상, 획 너비, 획 패턴, 연결부 유형, 시작 및 끝 모양이 있습니다. 특정 속성을 지정하지 않으면 API에서 해당 속성에 기본값을 사용합니다.

다음 코드에서는 선 끝에 둥근 모양을 적용하고, 선의 시작 부분에는 다중선의 유형에 따라 다른 모양을 적용합니다. 여기에서 유형은 다중선의 데이터 객체에 저장된 임의의 속성입니다. 샘플에서는 또한 획 너비, 획 색상, 연결부 유형을 지정합니다.

private static final int COLOR_BLACK_ARGB = 0xff000000;
private static final int POLYLINE_STROKE_WIDTH_PX = 12;

private void stylePolyline(Polyline polyline) {
    String type = "";
    // Get the data object stored with the polyline.
    if (polyline.getTag() != null) {
        type = polyline.getTag().toString();
    }

    switch (type) {
        // If no type is given, allow the API to use the default.
        case "A":
            // Use a custom bitmap as the cap at the start of the line.
            polyline.setStartCap(
                    new CustomCap(
                            BitmapDescriptorFactory.fromResource(R.drawable.ic_arrow), 10));
            break;
        case "B":
            // Use a round cap at the start of the line.
            polyline.setStartCap(new RoundCap());
            break;
    }

    polyline.setEndCap(new RoundCap());
    polyline.setWidth(POLYLINE_STROKE_WIDTH_PX);
    polyline.setColor(COLOR_BLACK_ARGB);
    polyline.setJointType(JointType.ROUND);
}

위 코드에서는 유형 A 다중선의 시작 모양에 적용할 맞춤 비트맵을 지정하고 10픽셀의 참조 획 너비를 지정합니다. API에서는 참조 획 너비에 따라 비트맵의 크기를 조절합니다. 참조 획 너비를 지정하는 경우 이미지의 원래 크기에서 비트맵 이미지를 디자인할 때 사용한 너비를 입력하세요. 참고: 이미지 편집기에서 비트맵 이미지를 100% 크기로 열고 이미지를 기준으로 원하는 너비의 선 획을 그립니다.

선 시작/끝 모양 및 기타 도형 맞춤설정 옵션에 대해 자세히 알아보세요.

다중선의 클릭 이벤트 처리

  1. Polyline.setClickable()을 호출하여 다중선을 클릭 가능하도록 설정합니다. (기본적으로 다중선은 클릭할 수 없으며 사용자가 다중선을 탭할 때 앱에서 알림을 수신하지 않습니다.)

  2. OnPolylineClickListener 인터페이스를 구현하고 GoogleMap.setOnPolylineClickListener()를 호출하여 지도에 리스너를 설정합니다.

    public class PolyActivity extends AppCompatActivity
            implements
                    OnMapReadyCallback,
                    GoogleMap.OnPolylineClickListener,
                    GoogleMap.OnPolygonClickListener {
    
        @Override
        public void onMapReady(GoogleMap googleMap) {
            // Add a polyline to the map.
            Polyline polyline1 = googleMap.addPolyline((new PolylineOptions())
                    .clickable(true)
                    .add(new LatLng(-35.016, 143.321),
                            new LatLng(-34.747, 145.592),
                            new LatLng(-34.364, 147.891),
                            new LatLng(-33.501, 150.217),
                            new LatLng(-32.306, 149.248),
                            new LatLng(-32.491, 147.309)));
    
            // Set listeners for click events.
            googleMap.setOnPolylineClickListener(this);
            googleMap.setOnPolygonClickListener(this);
        }
    }
    
  3. onPolylineClick() 콜백 메서드를 재정의합니다. 다음 예에서는 사용자가 다중선을 클릭할 때마다 실선과 점선 간에 선의 획 패턴을 바꿉니다.

    private static final PatternItem DOT = new Dot();
    private static final PatternItem GAP = new Gap(PATTERN_GAP_LENGTH_PX);
    //
    // Create a stroke pattern of a gap followed by a dot.
    private static final List<PatternItem> PATTERN_POLYLINE_DOTTED = Arrays.asList(GAP, DOT);
    
    @Override
    public void onPolylineClick(Polyline polyline) {
        // Flip from solid stroke to dotted stroke pattern.
        if ((polyline.getPattern() == null) || (!polyline.getPattern().contains(DOT))) {
            polyline.setPattern(PATTERN_POLYLINE_DOTTED);
        } else {
            // The default pattern is a solid stroke.
            polyline.setPattern(null);
        }
    
        Toast.makeText(this, "Route type " + polyline.getTag().toString(),
                Toast.LENGTH_SHORT).show();
    }
    

지도에서 영역을 나타내는 다각형 추가

PolygonPolyline과 마찬가지로 순서가 지정된 일련의 좌표로 구성된 도형입니다. 차이점은 다각형은 내부를 채울 수 있는 닫힌 영역을 정의하고 다중선은 끝이 열려 있다는 것입니다.

  1. PolygonOptions 객체를 만들고 여기에 점을 추가합니다. 각 점은 위도 및 경도 값이 포함된 LatLng 객체를 사용하여 정의하는 지도상의 한 위치를 나타냅니다. 아래의 코드 샘플에서는 점 4개로 다각형을 만듭니다.

  2. Polygon.setClickable()을 호출하여 다각형을 클릭 가능하도록 설정합니다. (기본적으로 다각형은 클릭할 수 없으며 사용자가 다각형을 탭할 때 앱에서 알림을 수신하지 않습니다.) 다각형 클릭 이벤트는 이 가이드의 앞부분에서 설명한 다중선의 이벤트와 유사하게 처리됩니다.

  3. GoogleMap.addPolygon()을 호출하여 지도에 다각형을 추가합니다.

  4. Polygon.setTag()를 호출하여 다각형과 함께 데이터 객체를 저장합니다. 아래 코드에서는 다각형에 임의의 유형(alpha)을 정의합니다.

    Polygon polygon1 = googleMap.addPolygon(new PolygonOptions()
            .clickable(true)
            .add(
                    new LatLng(-27.457, 153.040),
                    new LatLng(-33.852, 151.211),
                    new LatLng(-37.813, 144.962),
                    new LatLng(-34.928, 138.599)));
    // Store a data object with the polygon, used here to indicate an arbitrary type.
    polygon1.setTag("alpha");
    

다각형에 맞춤 스타일 추가

PolygonOptions 객체에서 다양한 스타일 속성의 수를 지정할 수 있습니다. 스타일 지정 옵션에는 획 색상, 획 너비, 획 패턴, 획 연결부 유형, 채우기 색상이 있습니다. 특정 속성을 지정하지 않으면 API에서 해당 속성에 기본값을 사용합니다.

다음 코드에서는 다각형의 유형에 따라 특정 색상과 획 패턴을 적용합니다. 여기에서 유형은 다각형의 데이터 객체에 저장된 임의의 속성입니다.

private static final int COLOR_BLACK_ARGB = 0xff000000;
private static final int COLOR_WHITE_ARGB = 0xffffffff;
private static final int COLOR_GREEN_ARGB = 0xff388E3C;
private static final int COLOR_PURPLE_ARGB = 0xff81C784;
private static final int COLOR_ORANGE_ARGB = 0xffF57F17;
private static final int COLOR_BLUE_ARGB = 0xffF9A825;

private static final int POLYGON_STROKE_WIDTH_PX = 8;
private static final int PATTERN_DASH_LENGTH_PX = 20;
private static final int PATTERN_GAP_LENGTH_PX = 20;
private static final PatternItem DOT = new Dot();
private static final PatternItem DASH = new Dash(PATTERN_DASH_LENGTH_PX);
private static final PatternItem GAP = new Gap(PATTERN_GAP_LENGTH_PX);

// Create a stroke pattern of a gap followed by a dash.
private static final List<PatternItem> PATTERN_POLYGON_ALPHA = Arrays.asList(GAP, DASH);

// Create a stroke pattern of a dot followed by a gap, a dash, and another gap.
private static final List<PatternItem> PATTERN_POLYGON_BETA =
        Arrays.asList(DOT, GAP, DASH, GAP);

private void stylePolygon(Polygon polygon) {
    String type = "";
    // Get the data object stored with the polygon.
    if (polygon.getTag() != null) {
        type = polygon.getTag().toString();
    }

    List<PatternItem> pattern = null;
    int strokeColor = COLOR_BLACK_ARGB;
    int fillColor = COLOR_WHITE_ARGB;

    switch (type) {
        // If no type is given, allow the API to use the default.
        case "alpha":
            // Apply a stroke pattern to render a dashed line, and define colors.
            pattern = PATTERN_POLYGON_ALPHA;
            strokeColor = COLOR_GREEN_ARGB;
            fillColor = COLOR_PURPLE_ARGB;
            break;
        case "beta":
            // Apply a stroke pattern to render a line of dots and dashes, and define colors.
            pattern = PATTERN_POLYGON_BETA;
            strokeColor = COLOR_ORANGE_ARGB;
            fillColor = COLOR_BLUE_ARGB;
            break;
    }

    polygon.setStrokePattern(pattern);
    polygon.setStrokeWidth(POLYGON_STROKE_WIDTH_PX);
    polygon.setStrokeColor(strokeColor);
    polygon.setFillColor(fillColor);
}

획 패턴 및 기타 도형 맞춤설정 옵션에 대해 자세히 알아보세요.

다음 단계

객체에 대해 자세히 알아보세요. 원은 다각형과 유사하지만 원의 모양이 반영된 속성을 갖습니다.