Anda menjalankan konversi Shapefiles yang telah berhasil ratusan kali, namun kali ini berhenti dengan TransformationException. Tidak ada output parsial dan tidak ada indikasi jelas rekaman mana yang menyebabkan masalah. Seringkali penyebabnya adalah satu koordinat tidak valid yang tersembunyi di antara ribuan fitur yang valid. Artikel ini menjelaskan mengapa konversi Shapefile gagal dengan kesalahan ini dan cara memperbaikinya di C# menggunakan OperationErrorCollector, yang diperkenalkan dalam Aspose.GIS for .NET 26.6. Anda akan belajar cara membiarkan konversi selesai, mempertahankan setiap fitur yang valid, dan mendapatkan laporan yang tepat mengenai rekaman yang memerlukan perhatian.

Jika Anda hanya membutuhkan kode konversi dasar, lihat Convert Shapefile to KML in C#. Panduan ini melanjutkan itu dan berfokus pada penanganan kesalahan.

Mengapa Konversi Shapefile Melempar TransformationException

Kebanyakan format target mengharapkan koordinat dalam sistem koordinat tertentu. KML, misalnya, selalu menggunakan longitude dan latitude WGS 84. Selama konversi, Aspose.GIS mengubah setiap koordinat dari sistem koordinat sumber ke sistem koordinat target. Jika ada koordinat yang tidak dapat diubah, perpustakaan akan melempar TransformationException dan konversi berhenti.

Penyebab paling umum adalah:

  • Placeholder “no data” values. Beberapa alat menulis nilai sentinel alih-alih membiarkan geometri kosong. File contoh dalam artikel ini berisi titik pada (-1.7976931348623157E+308, -1.7976931348623157E+308), nilai minimum dari double, yang tidak dapat diubah oleh sistem koordinat mana pun.
  • Out-of-range coordinates. Nilai yang berada di luar area valid sistem koordinat sumber, sering disebabkan oleh kesalahan entri data atau konversi satuan yang buruk.
  • A .prj file that does not match the data. Jika koordinat proyeksi dalam meter dinyatakan sebagai koordinat geografis dalam derajat, banyak nilai akan berada jauh di luar rentang yang valid.
  • Corrupted geometry records. Ekspor warisan dan file yang rusak dapat berisi nilai numerik tidak valid dalam catatan individu.

Dalam setiap kasus, masalah biasanya terbatas pada beberapa catatan, namun perilaku default membuang seluruh konversi.

Mengapa Fitur Ini Penting

Berhenti pada kegagalan pertama memang aman, tetapi biayanya tinggi dalam pipeline nyata. Satu catatan yang buruk memaksa Anda membersihkan file secara manual sebelum data apa pun dapat dikonversi, dan pengecualian saja tidak memberi tahu berapa banyak catatan lain yang terpengaruh. Dengan pengumpulan kesalahan diaktifkan, Anda dapat:

  • Konversi semua fitur yang valid alih-alih kehilangan seluruh file karena satu catatan yang buruk.
  • Catat indeks dan koordinat setiap fitur yang dilewati sehingga data sumber dapat diperbaiki.
  • Jalankan konversi batch tanpa pengawasan dan pekerjaan ETL tanpa crash pada input yang kotor.
  • Terima Shapefile yang diunggah pengguna dalam layanan web dan laporkan masalah data kembali ke pengguna.

Cara Memperbaiki Kegagalan Konversi Shapefile di C# dengan Aspose.GIS

Aspose.GIS for .NET adalah pustaka terkelola untuk membaca, menulis, dan mengonversi format geospasial seperti Shapefile, KML, GeoJSON, GML, dan File Geodatabase tanpa memerlukan perangkat lunak GIS lainnya yang terpasang. Pengumpulan kesalahan memerlukan versi 26.6 atau yang lebih baru. Instal paket dari NuGet:

dotnet add package Aspose.GIS

Atau gunakan Package Manager Console:

Install-Package Aspose.GIS

Jenis-jenis berikut digunakan dalam tutorial ini:

  • VectorLayer (Aspose.Gis): membuka, membuat, dan mengonversi lapisan vektor. VectorLayer.Convert melakukan konversi.
  • ConversionOptions (Aspose.Gis): menyimpan pengaturan konversi, termasuk DestinationDriverOptions dan DestinationSpatialReferenceSystem.
  • KmlOptions (Aspose.Gis.Formats.Kml): opsi driver KML. Ini mewarisi properti ErrorCollector dari DriverOptions.
  • OperationErrorCollector (Aspose.Gis.Operations): menyimpan kesalahan yang dapat dipulihkan. Ini mengekspos Errors, Count, HasErrors, Add, dan Clear.
  • OperationError dan TransformationError (Aspose.Gis.Operations): setiap kesalahan memiliki Message dan Exception. TransformationError menambahkan FeatureIndex, X, Y, dan Z.
  • TransformationException (Aspose.Gis.SpatialReferencing): dilemparkan ketika koordinat tidak dapat diubah dan tidak ada kolektor yang terpasang.

Cara Mengatasi TransformationException Saat Konversi Shapefile

Perbaikan ini memiliki dua bagian. Pertama, lampirkan OperationErrorCollector sehingga konversi melewati fitur yang tidak valid alih‑alih gagal. Kedua, gunakan laporan yang dikumpulkan untuk memperbaiki atau menghapus catatan tersebut di sumber. Langkah‑langkah di bawah ini menggunakan konversi Shapefile ke KML sebagai contoh.

1. Siapkan Lingkungan

  1. Buat proyek konsol .NET dan tambahkan paket NuGet Aspose.GIS 26.6+.
  2. Salin Shapefile dan file pendampingnya (.shp, .shx, .dbf, dan .prj) ke dalam satu folder. Contoh ini menggunakan data/light-traffics.shp.
  3. Tambahkan namespace yang diperlukan:
using System;
using System.IO;
using Aspose.Gis;
using Aspose.Gis.Formats.Kml;
using Aspose.Gis.Operations;
using Aspose.Gis.SpatialReferencing;

2. Buat OperationErrorCollector

Pengumpul mencatat setiap kesalahan yang dapat dipulihkan yang muncul selama konversi. Buat instance baru untuk setiap konversi sehingga kesalahan dari file yang berbeda tidak tercampur.

// Records recoverable errors instead of throwing them.
var errors = new OperationErrorCollector();

3. Lampirkan Collector Melalui ConversionOptions

Tetapkan kolektor ke KmlOptions.ErrorCollector, lalu berikan opsi KML sebagai DestinationDriverOptions. Menetapkan DestinationSpatialReferenceSystem ke WGS 84 bersifat opsional untuk KML, tetapi membuat sistem koordinat target menjadi eksplisit dalam kode Anda.

var options = new ConversionOptions
{
    // KML always uses WGS 84; stating it makes the reprojection explicit.
    DestinationSpatialReferenceSystem = SpatialReferenceSystem.Wgs84,
    DestinationDriverOptions = new KmlOptions
    {
        ErrorCollector = errors // Skip and record features that fail transformation.
    }
};

4. Jalankan Konversi

Panggil VectorLayer.Convert dengan jalur sumber, driver Shapefile, jalur tujuan, driver KML , dan opsi yang baru saja Anda konfigurasikan.

string sourcePath = Path.Combine("data", "light-traffics.shp");
string destinationPath = Path.Combine("output", "light-traffics.kml");
Directory.CreateDirectory(Path.GetDirectoryName(destinationPath));

VectorLayer.Convert(sourcePath, Drivers.Shapefile, destinationPath, Drivers.Kml, options);

Ketika sebuah fitur tidak dapat diubah, driver KML menambahkan kesalahan ke kolektor, melewatkan fitur tersebut, dan melanjutkan dengan yang berikutnya. Tidak ada TransformationException yang dilempar.

5. Laporkan Fitur yang Dilewati dan Verifikasi Output

Konversi yang kembali secara normal mungkin masih melewatkan fitur, jadi selalu periksa kolektor setelahnya. Cast setiap error ke TransformationError untuk mendapatkan indeks fitur dan koordinat yang gagal, kemudian buka file output untuk mengonfirmasi berapa banyak fitur yang ditulis.

if (errors.HasErrors)
{
    Console.WriteLine($"Skipped {errors.Count} feature(s):");

foreach (var error in errors.Errors)
    {
        if (error is TransformationError transformationError)
        {
            Console.WriteLine(
                $"  Feature #{transformationError.FeatureIndex} at " +
                $"({transformationError.X}, {transformationError.Y}, {transformationError.Z}): {error.Message}");
        }
        else
        {
            Console.WriteLine($"  {error.Message}");
        }
    }
}

using (var layer = VectorLayer.Open(destinationPath, Drivers.Kml))
{
    Console.WriteLine($"Features written to KML: {layer.Count}");
}

Untuk file contoh, kolektor mencatat satu kesalahan untuk titik placeholder, dan fitur yang tersisa (setidaknya 444) ditulis ke file KML.

Indeks fitur dan koordinat dalam laporan ini melengkapi perbaikan. Buka Shapefile sumber dalam alur kerja pembersihan data Anda, temukan catatan yang dilaporkan, dan perbaiki atau hapus mereka. Jika banyak catatan gagal dengan nilai yang tampak wajar, periksa file .prj terlebih dahulu, karena sistem koordinat yang tidak cocok kemungkinan besar penyebabnya.

6. Kode Contoh Lengkap

Aplikasi konsol lengkap di bawah ini menjalankan konversi dua kali. Jalur pertama menggunakan pengaturan default dan menghasilkan TransformationException. Jalur kedua melampirkan OperationErrorCollector, melewati fitur yang tidak valid, dan mencetak laporan.

using System;
using System.IO;
using Aspose.Gis;
using Aspose.Gis.Formats.Kml;
using Aspose.Gis.Operations;
using Aspose.Gis.SpatialReferencing;

namespace ShapefileTransformationErrors
{
    internal class Program
    {
        private static void Main()
        {
            string sourcePath = Path.Combine("data", "light-traffics.shp");
            string outputFolder = "output";
            Directory.CreateDirectory(outputFolder);

// -----------------------------------------------------------------
            // Run 1: default behavior. The first failed transformation aborts
            // the whole conversion with a TransformationException.
            // -----------------------------------------------------------------
            string failFastPath = Path.Combine(outputFolder, "fail-fast.kml");
            try
            {
                VectorLayer.Convert(sourcePath, Drivers.Shapefile, failFastPath, Drivers.Kml);
                Console.WriteLine("Default conversion finished without transformation errors.");
            }
            catch (TransformationException ex)
            {
                Console.WriteLine($"Default conversion aborted: {ex.Message}");
                Console.WriteLine($"Failing coordinate: ({ex.X}, {ex.Y}, {ex.Z})");
            }

// -----------------------------------------------------------------
            // Run 2: error-tolerant conversion. Invalid features are skipped
            // and recorded in the collector; valid features are written.
            // -----------------------------------------------------------------
            string destinationPath = Path.Combine(outputFolder, "light-traffics.kml");

var errors = new OperationErrorCollector();
            var options = new ConversionOptions
            {
                DestinationSpatialReferenceSystem = SpatialReferenceSystem.Wgs84,
                DestinationDriverOptions = new KmlOptions
                {
                    ErrorCollector = errors
                }
            };

VectorLayer.Convert(sourcePath, Drivers.Shapefile, destinationPath, Drivers.Kml, options);

// Report every skipped feature so the source data can be repaired.
            if (errors.HasErrors)
            {
                Console.WriteLine($"Conversion completed with {errors.Count} skipped feature(s):");

foreach (var error in errors.Errors)
                {
                    if (error is TransformationError transformationError)
                    {
                        Console.WriteLine(
                            $"  Feature #{transformationError.FeatureIndex} at " +
                            $"({transformationError.X}, {transformationError.Y}, {transformationError.Z}): {error.Message}");
                    }
                    else
                    {
                        Console.WriteLine($"  {error.Message}");
                    }
                }
            }
            else
            {
                Console.WriteLine("Conversion completed with no errors.");
            }

// Verify the output file.
            using (var layer = VectorLayer.Open(destinationPath, Drivers.Kml))
            {
                Console.WriteLine($"Features written to KML: {layer.Count}");
            }
        }
    }
}

7. Jebakan Umum dan Cara Menghindarinya

JebakanAlasanPerbaikan
ErrorCollector atau OperationErrorCollector tidak dapat dikompilasiKeduanya ditambahkan di Aspose.GIS for .NET 26.6.Perbarui paket NuGet ke 26.6 atau yang lebih baru.
Konversi masih melempar TransformationExceptionTidak ada kolektor yang terpasang pada opsi driver tujuan.Setel ErrorCollector pada objek opsi driver yang ditetapkan ke ConversionOptions.DestinationDriverOptions.
Konversi “berhasil” tidak menyertakan fiturKolektor menekan pengecualian, sehingga Convert mengembalikan nilai secara normal.Periksa errors.HasErrors setelah setiap pemanggilan dan catat hasilnya.
Menganggap fitur yang dilewati sebagai sudah diperbaikiKolektor melewatkan catatan yang tidak valid; ia tidak memperbaikinya.Gunakan indeks fitur dan koordinat yang dilaporkan untuk memperbaiki atau menghapus catatan dalam data sumber.
Ratusan fitur gagal sekaligusFile .prj kemungkinan tidak cocok dengan koordinat sebenarnya.Verifikasi sistem koordinat sumber sebelum menyelidiki catatan individu.
Kesalahan dari beberapa file muncul dalam satu laporanInstansi kolektor yang sama digunakan kembali di seluruh konversi.Buat OperationErrorCollector baru per file, atau panggil Clear() di antara proses.
Kesalahan penguncian file pada menjalankan berulangSebuah lapisan yang dibuka dengan VectorLayer.Open tidak dibuang.Bungkus VectorLayer.Open dalam blok using.

Dapatkan Lisensi Gratis

Anda dapat memperoleh lisensi gratis sementara untuk Aspose.GIS dari halaman lisensi sementara Aspose: https://purchase.aspose.com/temporary-license/

Sumber Daya Tambahan Gratis

Kesimpulan

A TransformationException selama konversi Shapefile biasanya berarti sejumlah kecil record berisi koordinat yang tidak dapat diubah, seperti nilai placeholder, angka di luar jangkauan, atau data yang tidak cocok dengan file .prj‑nya. Memperbaikinya di C# memerlukan dua langkah: melampirkan OperationErrorCollector sehingga Aspose.GIS for .NET melewati fitur yang tidak valid dan menyelesaikan konversi, kemudian gunakan indeks fitur dan koordinat yang dikumpulkan untuk memperbaiki data sumber. Hasilnya adalah pipeline yang terus menghasilkan output yang valid sambil mengubah kegagalan keras menjadi laporan kualitas data yang dapat ditindaklanjuti.

FAQs

  1. Mengapa TransformationException terjadi saat mengonversi Shapefile? Ini terjadi ketika sebuah koordinat tidak dapat diubah dari sistem koordinat sumber ke sistem koordinat target. Penyebab umum meliputi nilai placeholder “no data”, koordinat di luar rentang valid sistem koordinat mereka, file .prj yang tidak cocok dengan data sebenarnya, dan catatan geometri yang rusak.

  2. Apa yang terjadi secara default ketika sebuah koordinat tidak dapat diubah?
    VectorLayer.Convert melempar TransformationException dan konversi berhenti. Mulai dengan versi 26.6, pengecualian juga menampilkan nilai X, Y, dan Z dari koordinat yang gagal.

  3. Versi mana dari Aspose.GIS for .NET yang mendukung OperationErrorCollector? OperationErrorCollector dan properti DriverOptions.ErrorCollector diperkenalkan di Aspose.GIS for .NET 26.6. Versi sebelumnya tidak menyertakannya.

  4. Apakah OperationErrorCollector memperbaiki koordinat yang tidak valid? Tidak. Ini melewatkan fitur yang gagal transformasi dan mencatatnya, sehingga output hanya berisi fitur yang valid. Gunakan indeks fitur dan koordinat yang dilaporkan untuk memperbaiki atau menghapus catatan yang buruk dalam data sumber.

  5. Bisakah saya menggunakan OperationErrorCollector dengan format output selain KML? ErrorCollector didefinisikan pada kelas dasar DriverOptions, sehingga setiap kelas opsi driver mengekspose-nya. Contoh yang didokumentasikan mencakup tujuan KML dan MapInfo TAB; uji perilaku dengan driver target Anda sendiri sebelum mengandalkannya dalam produksi.

  6. Detail apa yang dimiliki setiap error yang dikumpulkan? Setiap OperationError menyediakan Message dan Exception yang mendasarinya. Kegagalan transformasi dilaporkan sebagai objek TransformationError, yang menambahkan FeatureIndex serta nilai X, Y, dan Z dari koordinat yang gagal.

  7. Bagaimana saya tahu apakah konversi selesai tanpa ada kesalahan? Periksa properti HasErrors atau Count pada collector setelah VectorLayer.Convert mengembalikan. Sebuah konversi yang selesai tanpa melempar exception masih mungkin memiliki fitur yang dilewati.

Baca Selengkapnya