Melapisi gambar petak peta

Artikel
06/22/2024

Penting

Penghentian layanan Bing Maps for Enterprise

Layanan UWP MapControl dan peta dari namespace Windows.Services.Maps mengandalkan Bing Maps. Bing Maps for Enterprise tidak digunakan lagi dan akan dihentikan, di mana MapControl dan layanan tidak akan lagi menerima data.

Untuk informasi selengkapnya, lihat dokumentasi Pusat Pengembang Bing Maps dan Bing Maps.

Catatan

Layanan MapControl dan peta memerlukan kunci autentikasi peta yang disebut MapServiceToken. Untuk informasi selengkapnya tentang mendapatkan dan mengatur kunci autentikasi peta, lihat Meminta kunci autentikasi peta.

Overlay gambar ubin pihak ketiga atau kustom di peta dengan menggunakan sumber petak peta. Gunakan sumber petak peta untuk melapisi informasi khusus seperti data cuaca, data populasi, atau data seismik; atau gunakan sumber petak peta untuk mengganti peta default sepenuhnya.

Gambaran umum gambar berjenjang

Layanan peta seperti Bing Maps memotong peta menjadi petak peta persegi untuk pengambilan dan tampilan cepat. Petak peta ini berukuran 256 piksel dengan ukuran 256 piksel, dan telah dirender sebelumnya pada beberapa tingkat detail. Banyak layanan pihak ketiga juga menyediakan data berbasis peta yang dipotong menjadi petak peta. Gunakan sumber petak peta untuk mengambil petak peta pihak ketiga, atau untuk membuat petak peta kustom Anda sendiri, dan melapisinya di peta yang ditampilkan di MapControl.

Saat menggunakan sumber petak peta, Anda tidak perlu menulis kode untuk meminta atau memposisikan petak peta individual. MapControl meminta petak peta karena membutuhkannya. Setiap permintaan menentukan koordinat X dan Y dan tingkat zoom untuk petak peta individual. Anda cukup menentukan format Uri atau nama file yang akan digunakan untuk mengambil petak peta di properti UriFormatString . Artinya, Anda menyisipkan parameter yang dapat diganti di Uri dasar atau nama file untuk menunjukkan tempat meneruskan koordinat X dan Y dan tingkat zoom untuk setiap petak peta.

Berikut adalah contoh properti UriFormatString untuk HttpMapTileDataSource yang menunjukkan parameter yang dapat diganti untuk koordinat X dan Y dan tingkat zoom.

http://www.<web service name>.com/z={zoomlevel}&x={x}&y={y}

(Koordinat X dan Y mewakili lokasi petak peta individu dalam peta dunia pada tingkat detail yang ditentukan. Sistem penomoran petak peta dimulai dari {0, 0} di sudut kiri atas peta. Misalnya, petak peta pada {1, 2} berada di kolom kedua dari baris ketiga kisi petak peta.)

Untuk informasi selengkapnya tentang sistem petak peta yang digunakan oleh layanan pemetaan, lihat Sistem Petak Peta Bing Maps.

Petak peta overlay dari sumber petak peta

Overlay gambar petak peta dari sumber petak peta dengan menggunakan MapTileDataSource.

Buat instans salah satu dari tiga kelas sumber data petak yang mewarisi dari MapTileDataSource.
Konfigurasikan UriFormatString untuk digunakan untuk meminta petak peta dengan menyisipkan parameter yang dapat diganti di Uri dasar atau nama file.

Contoh berikut membuat instans HttpMapTileDataSource. Contoh ini menentukan nilai UriFormatString dalam konstruktor HttpMapTileDataSource.
```
    HttpMapTileDataSource dataSource = new HttpMapTileDataSource(
      "http://www.<web service name>.com/z={zoomlevel}&x={x}&y={y}");
```
Membuat instans dan mengonfigurasi MapTileSource. Tentukan MapTileDataSource yang Anda konfigurasi di langkah sebelumnya sebagai Sumber Data MapTileSource.

Contoh berikut menentukan DataSource di konstruktor MapTileSource.
```
    MapTileSource tileSource = new MapTileSource(dataSource);
```
Anda dapat membatasi kondisi di mana petak peta ditampilkan dengan menggunakan properti MapTileSource.
- Tampilkan petak peta hanya dalam area geografis tertentu dengan memberikan nilai untuk properti Batas.
- Tampilkan petak peta hanya pada tingkat detail tertentu dengan memberikan nilai untuk properti ZoomLevelRange.
Secara opsional, konfigurasikan properti Lain dari MapTileSource yang memengaruhi pemuatan atau tampilan petak peta, seperti Layer, AllowOverstretch, IsRetryEnabled, dan IsTransparencyEnabled.
Tambahkan MapTileSource ke koleksi TileSources dari MapControl.
```
     MapControl1.TileSources.Add(tileSource);
```

Petak peta overlay dari layanan web

Overlay gambar petak peta yang diambil dari layanan web dengan menggunakan HttpMapTileDataSource.

Membuat instans HttpMapTileDataSource.
Tentukan format Uri yang diharapkan layanan web sebagai nilai properti UriFormatString. Untuk membuat nilai ini, sisipkan parameter yang dapat diganti di Uri dasar. Misalnya, dalam sampel kode berikut, nilai UriFormatString adalah:
```
http://www.<web service name>.com/z={zoomlevel}&x={x}&y={y}
```
Layanan web harus mendukung Uri yang berisi parameter {x}, {y}, dan {zoomlevel} yang dapat diganti. Sebagian besar layanan web (misalnya, Nokia, Bing, dan Google) mendukung Uri dalam format ini. Jika layanan web memerlukan argumen tambahan yang tidak tersedia dengan properti UriFormatString , maka Anda harus membuat Uri kustom. Buat dan kembalikan Uri kustom dengan menangani peristiwa UriRequested. Untuk informasi selengkapnya, lihat bagian Sediakan URI kustom nanti dalam topik ini.
Kemudian, ikuti langkah-langkah yang tersisa yang dijelaskan sebelumnya dalam gambaran umum gambaran umum Petak.

Contoh berikut melapisi petak peta dari layanan web fiktif di peta Amerika Utara. Nilai UriFormatString ditentukan dalam konstruktor HttpMapTileDataSource. Dalam contoh ini, petak peta hanya ditampilkan dalam batas geografis yang ditentukan oleh properti Batas opsional.

private void AddHttpMapTileSource()
{
    // Create the bounding box in which the tiles are displayed.
    // This example represents North America.
    BasicGeoposition northWestCorner =
        new BasicGeoposition() { Latitude = 48.38544, Longitude = -124.667360 };
    BasicGeoposition southEastCorner =
        new BasicGeoposition() { Latitude = 25.26954, Longitude = -80.30182 };
    GeoboundingBox boundingBox = new GeoboundingBox(northWestCorner, southEastCorner);

    // Create an HTTP data source.
    // This example retrieves tiles from a fictitious web service.
    HttpMapTileDataSource dataSource = new HttpMapTileDataSource(
        "http://www.<web service name>.com/z={zoomlevel}&x={x}&y={y}");

    // Optionally, add custom HTTP headers if the web service requires them.
    dataSource.AdditionalRequestHeaders.Add("header name", "header value");

    // Create a tile source and add it to the Map control.
    MapTileSource tileSource = new MapTileSource(dataSource);
    tileSource.Bounds = boundingBox;
    MapControl1.TileSources.Add(tileSource);
}

...
#include <winrt/Windows.Devices.Geolocation.h>
#include <winrt/Windows.UI.Xaml.Controls.Maps.h>
...
void MainPage::AddHttpMapTileSource()
{
    Windows::Devices::Geolocation::BasicGeoposition northWest{ 48.38544, -124.667360 };
    Windows::Devices::Geolocation::BasicGeoposition southEast{ 25.26954, -80.30182 };
    Windows::Devices::Geolocation::GeoboundingBox boundingBox{ northWest, southEast };

    Windows::UI::Xaml::Controls::Maps::HttpMapTileDataSource dataSource{
        L"http://www.<web service name>.com/z={zoomlevel}&x={x}&y={y}" };

    dataSource.AdditionalRequestHeaders().Insert(L"header name", L"header value");

    Windows::UI::Xaml::Controls::Maps::MapTileSource tileSource{ dataSource };
    tileSource.Bounds(boundingBox);

    MapControl1().TileSources().Append(tileSource);
}
...

void MainPage::AddHttpMapTileSource()
{
    BasicGeoposition northWest = { 48.38544, -124.667360 };
    BasicGeoposition southEast = { 25.26954, -80.30182 };
    GeoboundingBox^ boundingBox = ref new GeoboundingBox(northWest, southEast);

    auto dataSource = ref new Windows::UI::Xaml::Controls::Maps::HttpMapTileDataSource(
        "http://www.<web service name>.com/z={zoomlevel}&x={x}&y={y}");

    dataSource->AdditionalRequestHeaders->Insert("header name", "header value");

    auto tileSource = ref new Windows::UI::Xaml::Controls::Maps::MapTileSource(dataSource);
    tileSource->Bounds = boundingBox;

    this->MapControl1->TileSources->Append(tileSource);
}

Petak peta overlay dari penyimpanan lokal

Overlay gambar berjenjang yang disimpan sebagai file di penyimpanan lokal dengan menggunakan LocalMapTileDataSource. Biasanya, Anda mengemas dan mendistribusikan file-file ini dengan aplikasi Anda.

Membuat instans LocalMapTileDataSource.
Tentukan format nama file sebagai nilai properti UriFormatString. Untuk membuat nilai ini, sisipkan parameter yang dapat diganti di nama file dasar. Misalnya, dalam sampel kode berikut, nilai UriFormatString adalah:
```
    Tile_{zoomlevel}_{x}_{y}.png
```
Jika format nama file memerlukan argumen tambahan yang tidak tersedia dengan properti UriFormatString , maka Anda harus membuat Uri kustom. Buat dan kembalikan Uri kustom dengan menangani peristiwa UriRequested. Untuk informasi selengkapnya, lihat bagian Sediakan URI kustom nanti dalam topik ini.
Kemudian, ikuti langkah-langkah yang tersisa yang dijelaskan sebelumnya dalam gambaran umum gambaran umum Petak.

Anda dapat menggunakan protokol dan lokasi berikut untuk memuat petak peta dari penyimpanan lokal:

Uri	Info selengkapnya
ms-appx:///	Menunjuk ke akar folder penginstalan aplikasi.
	Ini adalah lokasi yang dirujuk oleh properti Package.InstalledLocation .
ms-appdata:///local	Menunjuk ke akar penyimpanan lokal aplikasi.
	Ini adalah lokasi yang dirujuk oleh properti ApplicationData.LocalFolder .
ms-appdata:///temp	Menunjuk ke folder sementara aplikasi.
	Ini adalah lokasi yang dirujuk oleh properti ApplicationData.TemporaryFolder .

Contoh berikut memuat petak peta yang disimpan sebagai file di folder penginstalan aplikasi dengan menggunakan ms-appx:/// protokol . Nilai untuk UriFormatString ditentukan dalam konstruktor LocalMapTileDataSource. Dalam contoh ini, petak peta hanya ditampilkan saat tingkat perbesar tampilan peta berada dalam rentang yang ditentukan oleh properti ZoomLevelRange opsional.

void AddLocalMapTileSource()
{
    // Specify the range of zoom levels
    // at which the overlaid tiles are displayed.
    MapZoomLevelRange range;
    range.Min = 11;
    range.Max = 20;

    // Create a local data source.
    LocalMapTileDataSource dataSource = new LocalMapTileDataSource(
        "ms-appx:///TileSourceAssets/Tile_{zoomlevel}_{x}_{y}.png");

    // Create a tile source and add it to the Map control.
    MapTileSource tileSource = new MapTileSource(dataSource);
    tileSource.ZoomLevelRange = range;
    MapControl1.TileSources.Add(tileSource);
}

Menyediakan URI kustom

Jika parameter yang dapat diganti tersedia dengan properti UriFormatString dari HttpMapTileDataSource atau properti UriFormatString dari LocalMapTileDataSource tidak cukup untuk mengambil petak peta Anda, maka Anda harus membuat Uri kustom. Buat dan kembalikan Uri kustom dengan menyediakan handler kustom untuk peristiwa UriRequested . Peristiwa UriRequested dinaikkan untuk setiap petak peta individual.

Di handler kustom Anda untuk peristiwa UriRequested, gabungkan argumen kustom yang diperlukan dengan properti X, Y, dan ZoomLevel dari MapTileUriRequestedEventArgs untuk membuat Uri kustom.
Kembalikan Uri kustom di properti Uri dari MapTileUriRequest, yang terkandung dalam properti Permintaan mapTileUriRequestedEventArgs.

Contoh berikut menunjukkan cara menyediakan Uri kustom dengan membuat handler kustom untuk peristiwa UriRequested . Ini juga menunjukkan cara menerapkan pola deferral jika Anda harus melakukan sesuatu secara asinkron untuk membuat Uri kustom.

using Windows.UI.Xaml.Controls.Maps;
using System.Threading.Tasks;
...
            var httpTileDataSource = new HttpMapTileDataSource();
            // Attach a handler for the UriRequested event.
            httpTileDataSource.UriRequested += HandleUriRequestAsync;
            MapTileSource httpTileSource = new MapTileSource(httpTileDataSource);
            MapControl1.TileSources.Add(httpTileSource);
...
        // Handle the UriRequested event.
        private async void HandleUriRequestAsync(HttpMapTileDataSource sender,
            MapTileUriRequestedEventArgs args)
        {
            // Get a deferral to do something asynchronously.
            // Omit this line if you don't have to do something asynchronously.
            var deferral = args.Request.GetDeferral();

            // Get the custom Uri.
            var uri = await GetCustomUriAsync(args.X, args.Y, args.ZoomLevel);

            // Specify the Uri in the Uri property of the MapTileUriRequest.
            args.Request.Uri = uri;

            // Notify the app that the custom Uri is ready.
            // Omit this line also if you don't have to do something asynchronously.
            deferral.Complete();
        }

        // Create the custom Uri.
        private async Task<Uri> GetCustomUriAsync(int x, int y, int zoomLevel)
        {
            // Do something asynchronously to create and return the custom Uri.        }
        }

Petak peta overlay dari sumber kustom

Overlay ubin kustom dengan menggunakan CustomMapTileDataSource. Buat petak peta secara terprogram dalam memori dengan cepat, atau tulis kode Anda sendiri untuk memuat petak peta yang ada dari sumber lain.

Untuk membuat atau memuat petak peta kustom, berikan handler kustom untuk peristiwa BitmapRequested. Peristiwa BitmapRequested dinaikkan untuk setiap petak peta individual.

Di handler kustom Anda untuk peristiwa BitmapRequested, gabungkan argumen kustom yang diperlukan dengan properti X, Y, dan ZoomLevel dari MapTileBitmapRequestedEventArgs untuk membuat atau mengambil petak kustom.
Mengembalikan petak peta kustom di properti PixelData dari MapTileBitmapRequest, yang terkandung dalam properti Permintaan mapTileBitmapRequestedEventArgs. Properti PixelData berjenis IRandomAccessStreamReference.

Contoh berikut menunjukkan cara menyediakan petak peta kustom dengan membuat handler kustom untuk peristiwa BitmapRequested . Contoh ini membuat petak peta merah identik yang sebagian buram. Contoh mengabaikan properti X, Y, dan ZoomLevel dari MapTileBitmapRequestedEventArgs. Meskipun ini bukan contoh dunia nyata, contoh menunjukkan bagaimana Anda dapat membuat petak peta kustom dalam memori dengan cepat. Contohnya juga menunjukkan cara mengimplementasikan pola deferral jika Anda harus melakukan sesuatu secara asinkron untuk membuat ubin kustom.

using Windows.UI.Xaml.Controls.Maps;
using Windows.Storage.Streams;
using System.Threading.Tasks;
...
        CustomMapTileDataSource customDataSource = new CustomMapTileDataSource();
        // Attach a handler for the BitmapRequested event.
        customDataSource.BitmapRequested += customDataSource_BitmapRequestedAsync;
        customTileSource = new MapTileSource(customDataSource);
        MapControl1.TileSources.Add(customTileSource);
...
        // Handle the BitmapRequested event.
        private async void customDataSource_BitmapRequestedAsync(
            CustomMapTileDataSource sender,
            MapTileBitmapRequestedEventArgs args)
        {
            var deferral = args.Request.GetDeferral();
            args.Request.PixelData = await CreateBitmapAsStreamAsync();
            deferral.Complete();
        }

        // Create the custom tiles.
        // This example creates red tiles that are partially opaque.
        private async Task<RandomAccessStreamReference> CreateBitmapAsStreamAsync()
        {
            int pixelHeight = 256;
            int pixelWidth = 256;
            int bpp = 4;

            byte[] bytes = new byte[pixelHeight * pixelWidth * bpp];

            for (int y = 0; y < pixelHeight; y++)
            {
                for (int x = 0; x < pixelWidth; x++)
                {
                    int pixelIndex = y * pixelWidth + x;
                    int byteIndex = pixelIndex * bpp;

                    // Set the current pixel bytes.
                    bytes[byteIndex] = 0xff;        // Red
                    bytes[byteIndex + 1] = 0x00;    // Green
                    bytes[byteIndex + 2] = 0x00;    // Blue
                    bytes[byteIndex + 3] = 0x80;    // Alpha (0xff = fully opaque)
                }
            }

            // Create RandomAccessStream from byte array.
            InMemoryRandomAccessStream randomAccessStream =
                new InMemoryRandomAccessStream();
            IOutputStream outputStream = randomAccessStream.GetOutputStreamAt(0);
            DataWriter writer = new DataWriter(outputStream);
            writer.WriteBytes(bytes);
            await writer.StoreAsync();
            await writer.FlushAsync();
            return RandomAccessStreamReference.CreateFromStream(randomAccessStream);
        }

...
#include <winrt/Windows.Storage.Streams.h>
...
Windows::Foundation::IAsyncOperation<Windows::Storage::Streams::InMemoryRandomAccessStream> MainPage::CustomRandomAccessStream()
{
    constexpr int pixelHeight{ 256 };
    constexpr int pixelWidth{ 256 };
    constexpr int bpp{ 4 };

    std::array<uint8_t, pixelHeight * pixelWidth * bpp> bytes;

    for (int y = 0; y < pixelHeight; y++)
    {
        for (int x = 0; x < pixelWidth; x++)
        {
            int pixelIndex{ y * pixelWidth + x };
            int byteIndex{ pixelIndex * bpp };

            // Set the current pixel bytes.
            bytes[byteIndex] = (byte)(std::rand() % 256);        // Red
            bytes[byteIndex + 1] = (byte)(std::rand() % 256);    // Green
            bytes[byteIndex + 2] = (byte)(std::rand() % 256);    // Blue
            bytes[byteIndex + 3] = (byte)((std::rand() % 56) + 200);    // Alpha (0xff = fully opaque)
        }
    }

    // Create RandomAccessStream from byte array.
    Windows::Storage::Streams::InMemoryRandomAccessStream randomAccessStream;
    Windows::Storage::Streams::IOutputStream outputStream{ randomAccessStream.GetOutputStreamAt(0) };
    Windows::Storage::Streams::DataWriter writer{ outputStream };
    writer.WriteBytes(bytes);

    co_await writer.StoreAsync();
    co_await writer.FlushAsync();

    co_return randomAccessStream;
}
...

InMemoryRandomAccessStream^ TileSources::CustomRandomAccessStream::get()
{
    int pixelHeight = 256;
    int pixelWidth = 256;
    int bpp = 4;

    Array<byte>^ bytes = ref new Array<byte>(pixelHeight * pixelWidth * bpp);

    for (int y = 0; y < pixelHeight; y++)
    {
        for (int x = 0; x < pixelWidth; x++)
        {
            int pixelIndex = y * pixelWidth + x;
            int byteIndex = pixelIndex * bpp;

            // Set the current pixel bytes.
            bytes[byteIndex] = (byte)(std::rand() % 256);        // Red
            bytes[byteIndex + 1] = (byte)(std::rand() % 256);    // Green
            bytes[byteIndex + 2] = (byte)(std::rand() % 256);    // Blue
            bytes[byteIndex + 3] = (byte)((std::rand() % 56) + 200);    // Alpha (0xff = fully opaque)
        }
    }

    // Create RandomAccessStream from byte array.
    InMemoryRandomAccessStream^ randomAccessStream = ref new InMemoryRandomAccessStream();
    IOutputStream^ outputStream = randomAccessStream->GetOutputStreamAt(0);
    DataWriter^ writer = ref new DataWriter(outputStream);
    writer->WriteBytes(bytes);

    create_task(writer->StoreAsync()).then([writer](unsigned int)
    {
        create_task(writer->FlushAsync());
    });

    return randomAccessStream;
}

Ganti peta default

Untuk mengganti peta default sepenuhnya dengan petak peta pihak ketiga atau kustom:

Tentukan MapTileLayer.BackgroundReplacement sebagai nilai properti Layer dari MapTileSource.
Tentukan MapStyle.Tidak ada sebagai nilai properti Gaya dari MapControl.

Bagikan melalui

Melapisi gambar petak peta

Gambaran umum gambar berjenjang

Petak peta overlay dari sumber petak peta

Petak peta overlay dari layanan web

Petak peta overlay dari penyimpanan lokal

Menyediakan URI kustom

Petak peta overlay dari sumber kustom

Ganti peta default

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Melapisi gambar petak peta

Gambaran umum gambar berjenjang

Petak peta overlay dari sumber petak peta

Petak peta overlay dari layanan web

Petak peta overlay dari penyimpanan lokal

Menyediakan URI kustom

Petak peta overlay dari sumber kustom

Ganti peta default

Topik terkait

Saran dan Komentar

Sumber Daya Tambahan: