Mengonversi TopoJSON ke CSV dengan C#

TopoJSON adalah enkoding yang kompak untuk data geografis, dan biasanya setiap fitur dalam file TopoJSON membawa objek atribut alih-alih sekumpulan pasangan kunci-nilai yang datar. Mengekspor struktur itu ke CSV adalah tempat hal-hal biasanya salah: kebanyakan alat baik mengabaikan objek bersarang atau mengekspornya kembali sebagai string JSON yang ditempatkan dalam satu sel. Panduan ini menunjukkan cara mengonversi TopoJSON ke CSV di C# menggunakan Aspose.GIS, menjaga setiap atribut dapat diakses sebagai kolomnya masing-masing dan secara opsional menulis geometri bersamanya sebagai Well-Known Text.

Keuntungannya adalah bahwa dataset GIS hierarkis menjadi tabel datar yang dapat langsung dikonsumsi oleh SQL Server, Power BI, pandas, atau spreadsheet biasa, tanpa lapisan parsing JSON khusus dalam aplikasi Anda.

Mengapa Mengonversi TopoJSON ke CSV menggunakan Aspose.GIS

Pertimbangkan sebuah fitur TopoJSON yang propertinya terlihat seperti ini:

{
  "name": "North District",
  "prop1": { "this": "that" }
}

Penulis CSV yang naif memiliki tiga opsi buruk: menghapus prop1, menyerialkannya sebagai {"this":"that"} ke dalam satu sel, atau gagal. Ketiga opsi tersebut mendorong masalah ke hilir, di mana seseorang harus mengurai kembali JSON dari kolom teks sebelum mereka dapat memfilter atau melakukan join pada data tersebut.

Aspose.GIS mengambil pendekatan yang berbeda. Ketika driver TopoJSON membaca file, ia memproyeksikan objek bersarang ke dalam skema lapisan sebagai atribut datar yang dinamai berdasarkan jalurnya, menggabungkan induk dan anak dengan garis bawah. Fitur di atas ditampilkan sebagai dua kolom biasa:

Kolom	Nilai
`name`	Distrik Utara
`prop1_this`	itu

Karena proses pelurusan terjadi pada saat pembacaan, langkah konversi tidak memerlukan penanganan khusus sama sekali. Apa pun yang diekspos oleh lapisan itulah yang ditulis, sehingga prop1_this masuk ke dalam CSV sebagai kolom kelas pertama yang dapat Anda urutkan, filter, dan gabungkan.

Prasyarat Konversi TopoJSON ke CSV

.NET 6.0 atau lebih baru, atau .NET Framework 4.6.2 atau lebih baru
Aspose.GIS for .NET, diinstal dari NuGet
Sebuah file TopoJSON yang berisi setidaknya satu objek atribut bersarang

Instal paket dengan .NET CLI:

dotnet add package Aspose.GIS

Atau dari Package Manager Console:

Install-Package Aspose.GIS

Satu detail penamaan membuat orang kebingungan: paket NuGet dan assembly disebut Aspose.GIS, tetapi namespace root adalah Aspose.Gis dengan huruf kecil is. Opsi driver CSV berada di Aspose.Gis.Formats.Csv.

using Aspose.Gis;
using Aspose.Gis.Formats.Csv;

Detail produk ada di halaman produk Aspose.GIS for .NET, dengan daftar tipe lengkap di referensi API.

Periksa Skema Datar Sebelum Anda Mengonversi

Apa yang akan Anda capai: Buka lapisan TopoJSON dan cetak nama atributnya sehingga Anda tahu persis kolom apa yang akan dimiliki CSV.

Langkah ini layak dilakukan sekali pada file yang representatif. Ini memberi tahu Anda nama kolom sebenarnya yang dihasilkan oleh proses flattening, yang jauh lebih dapat diandalkan daripada menebaknya dari JSON mentah.

using System;
using Aspose.Gis;

using (VectorLayer layer = VectorLayer.Open("data/regions.topojson", Drivers.TopoJson))
{
    Console.WriteLine($"Features: {layer.Count}");

foreach (FeatureAttribute attribute in layer.Attributes)
    {
        Console.WriteLine($"  {attribute.Name} ({attribute.DataType})");
    }
}

Untuk fitur contoh yang ditunjukkan sebelumnya, ini mencetak name (String) dan prop1_this (String). Objek bersarang tidak pernah muncul sebagai atribut secara terpisah, yang merupakan apa yang Anda inginkan.

Mengonversi TopoJSON ke CSV Sambil Mempertahankan Atribut Bersarang

Apa yang akan Anda capai: Muat file TopoJSON, tulis setiap atribut yang telah diratakan ke file CSV, dan baca kembali hasilnya untuk memastikan kolom tersebut berhasil melewati proses.

Proses langkah demi langkah

Tentukan jalur TopoJSON sumber dan jalur CSV tujuan.
Buka sumber dengan VectorLayer.Open dan pastikan atribut yang diratakan ada.
Panggil overload statis VectorLayer.Convert dengan driver sumber dan tujuan.
Buka kembali CSV dengan Drivers.Csv dan periksa jumlah kolom serta nilai‑nilainya.

Contoh berikut mengonversi file TopoJSON ke CSV, meratakan properti bersarang di sepanjang proses.

using System;
using System.IO;
using Aspose.Gis;

class TopoJsonToCsv
{
    static void Main()
    {
        string sourcePath = Path.Combine("data", "regions.topojson");
        string destinationPath = Path.Combine("output", "regions.csv");

Directory.CreateDirectory("output");

// Confirm the nested property was flattened when the layer was opened.
        using (VectorLayer source = VectorLayer.Open(sourcePath, Drivers.TopoJson))
        {
            Console.WriteLine($"Source features: {source.Count}");
            Console.WriteLine($"Has prop1_this: {source.Attributes.Contains("prop1_this")}");
        }

// No options are needed. The conversion writes whatever columns the
        // source layer exposes, flattened attributes included.
        VectorLayer.Convert(sourcePath, Drivers.TopoJson, destinationPath, Drivers.Csv);

// Read the CSV back and verify the schema survived the round trip.
        using (VectorLayer csv = VectorLayer.Open(destinationPath, Drivers.Csv))
        {
            Console.WriteLine($"Rows: {csv.Count}, Columns: {csv.Attributes.Count}");

if (csv.Attributes.Contains("prop1_this"))
            {
                Console.WriteLine($"First value: {csv[0].GetValue<string>("prop1_this")}");
            }

// No WKT column was requested, so features read back without geometry.
            Console.WriteLine($"Geometry empty: {csv[0].Geometry.IsEmpty}");
        }
    }
}

Penjelasan

VectorLayer.Open(string, FileDriver) membuka file dalam mode hanya‑baca. Drivers.TopoJson mengembalikan driver untuk format TopoJSON.
FeatureAttributeCollection.Contains(string) adalah cara termurah untuk menguji keberadaan kolom berdasarkan nama. IndexOf memberikan posisi kolom tersebut jika Anda membutuhkannya.
VectorLayer.Convert(string, FileDriver, string, FileDriver) adalah pembantu statis yang menyalurkan sumber ke format tujuan dalam satu panggilan. Ada juga overload yang menerima ConversionOptions, yang digunakan pada bagian berikutnya.
Feature.GetValue<T>(string) membaca nilai atribut dengan tipe tertentu. Gunakan GetValueOrDefault<T>(string) ketika sebuah kolom mungkin tidak ada atau bernilai null, karena GetValue<T> mengasumsikan nilai tersebut ada.
Pemeriksaan terakhir adalah yang mengejutkan banyak orang. File CSV tidak memiliki kolom geometri kecuali Anda membuatnya, sehingga setiap fitur kembali dengan geometri kosong. Itu adalah perilaku default, bukan kegagalan konversi, dan bagian berikutnya memperbaikinya.

Menjalankan kedua lapisan dalam blok using penting di sini: VectorLayer mengimplementasikan IDisposable, dan file tujuan tidak dijamin akan dibersihkan dan ditutup sampai ia dibuang.

Sertakan Geometri sebagai WKT Menggunakan CsvOptions

Apa yang akan Anda capai: Hasilkan CSV yang memuat baik atribut yang diratakan dan kolom yang berisi geometri setiap fitur sebagai Well-Known Text.

Proses langkah demi langkah

Buat sebuah instance CsvOptions dan atur ColumnWkt ke nama kolom yang Anda pilih.
Tetapkan ke ConversionOptions.DestinationDriverOptions.
Panggil overload VectorLayer.Convert yang menerima opsi konversi.
Buka kembali CSV dengan CsvOptions yang sama sehingga driver mengetahui kolom mana yang akan diparse sebagai geometri.

using System;
using System.IO;
using Aspose.Gis;
using Aspose.Gis.Formats.Csv;

class TopoJsonToCsvWithGeometry
{
    static void Main()
    {
        string sourcePath = Path.Combine("data", "regions.topojson");
        string destinationPath = Path.Combine("output", "regions-wkt.csv");

Directory.CreateDirectory("output");

// Ask the CSV driver for a geometry column named "GeometryWkt".
        var csvOptions = new CsvOptions
        {
            ColumnWkt = "GeometryWkt"
        };

var conversionOptions = new ConversionOptions
        {
            DestinationDriverOptions = csvOptions
        };

VectorLayer.Convert(
            sourcePath,
            Drivers.TopoJson,
            destinationPath,
            Drivers.Csv,
            conversionOptions);

// Pass the same options when reading, or the WKT column is just text.
        using (VectorLayer layer = VectorLayer.Open(destinationPath, Drivers.Csv, csvOptions))
        {
            foreach (Feature feature in layer)
            {
                string name = feature.GetValueOrDefault<string>("name");
                string wkt = feature.Geometry.IsEmpty ? "(empty)" : feature.Geometry.AsText();

Console.WriteLine($"{name}: {wkt}");
            }
        }
    }
}

Penjelasan

CsvOptions.ColumnWkt menamai kolom yang menyimpan geometri setiap fitur dalam bentuk WKT. Nilainya default null, dan membiarkannya null atau kosong adalah alasan tepat mengapa contoh sebelumnya tidak menghasilkan geometri.
ConversionOptions.DestinationDriverOptions bertipe DriverOptions, kelas dasar untuk setiap objek pengaturan driver. Mengirimkan CsvOptions ketika driver tujuan adalah Drivers.Csvlah yang membuat pengaturan tersebut berlaku; mengirimkan opsi dengan tipe yang salah untuk sebuah driver akan memunculkan ArgumentException.
Instansi CsvOptions yang sama digunakan kembali pada sisi pembacaan. Tanpa itu, driver CSV tidak memiliki alasan untuk memperlakukan GeometryWkt sebagai selain kolom string lainnya.
IGeometry.AsText() mengembalikan representasi ISO WKT, sehingga output yang dicetak cocok dengan apa yang ditulis ke file.

Simetri adalah intinya: kolom atribut berperilaku identik baik geometry disertakan maupun tidak, sehingga Anda dapat mengaktifkan atau menonaktifkan kolom WKT tanpa menyentuh bagian lain dari pipeline Anda.

Proyeksikan Ulang Selama Konversi

Jika sistem yang menggunakan mengharapkan sistem koordinat tertentu, mintalah itu sebagai bagian dari konversi daripada memproses CSV setelahnya. ConversionOptions membawa referensi spasial bersama opsi driver:

var conversionOptions = new ConversionOptions
{
    DestinationDriverOptions = new CsvOptions { ColumnWkt = "GeometryWkt" },
    DestinationSpatialReferenceSystem = SpatialReferenceSystem.Wgs84
};

VectorLayer.Convert(sourcePath, Drivers.TopoJson, destinationPath, Drivers.Csv, conversionOptions);

Tidak setiap driver tujuan mendukung setiap sistem referensi spasial. Panggil Drivers.Csv.SupportsSpatialReferenceSystem(...) terlebih dahulu jika sistem target dapat dikonfigurasi pada waktu berjalan, dan gunakan objek opsi null sebagai fallback ketika tidak didukung.

Konversi Batch Folder Berkas TopoJSON

API-nya identik untuk satu file maupun seribu. Satu-satunya aturan yang perlu diingat saat Anda memparalelkan adalah setiap pekerja membutuhkan objek lapisan dan opsi masing-masing.

using System;
using System.IO;
using System.Threading.Tasks;
using Aspose.Gis;
using Aspose.Gis.Formats.Csv;

static void ConvertFolder(string inputFolder, string outputFolder)
{
    Directory.CreateDirectory(outputFolder);

var files = Directory.GetFiles(inputFolder, "*.topojson");

Parallel.ForEach(files, file =>
    {
        string destination = Path.Combine(
            outputFolder,
            Path.GetFileNameWithoutExtension(file) + ".csv");

// Fresh options per iteration: nothing is shared across threads.
        var options = new ConversionOptions
        {
            DestinationDriverOptions = new CsvOptions { ColumnWkt = "GeometryWkt" }
        };

try
        {
            VectorLayer.Convert(file, Drivers.TopoJson, destination, Drivers.Csv, options);
        }
        catch (GisException ex)
        {
            Console.Error.WriteLine($"Skipped {Path.GetFileName(file)}: {ex.Message}");
        }
    });
}

Menangkap GisException per file daripada di sekitar seluruh loop berarti satu file TopoJSON yang rusak akan mencatat peringatan alih‑alih menghentikan batch.

Dapatkan Lisensi Gratis

Aspose.GIS berjalan dalam mode evaluasi hingga lisensi diterapkan. Minta lisensi sementara gratis dari halaman lisensi sementara Aspose dan terapkan sekali saat aplikasi dimulai, sebelum panggilan Aspose.GIS lainnya:

var license = new Aspise.Gis.License();
license.SetLicense("Aspose.GIS.NET.lic");

Sumber Daya Tambahan Gratis

Kesimpulan

Mengonversi TopoJSON dengan properti bersarang ke CSV di .NET pada dasarnya bergantung pada satu perilaku berguna: Aspose.GIS meratakan objek atribut bersarang menjadi kolom bernama seperti prop1_this saat lapisan dibaca, sehingga VectorLayer.Convert tidak memerlukan logika khusus untuk mempertahankannya. Tambahkan CsvOptions.ColumnWkt ketika sistem hilir memerlukan geometri, tambahkan DestinationSpatialReferenceSystem ketika diperlukan proyeksi tertentu, dan ulangi panggilan yang sama ketika Anda perlu memproses sebuah folder. Hasilnya adalah tabel datar yang siap untuk analisis yang dihasilkan oleh beberapa baris kode C#, tanpa lapisan parsing JSON milik Anda sendiri yang harus dipelihara.

FAQ

Bisakah Aspose.GIS meratakan objek JSON bersarang saat mengonversi ke CSV? Ya. Driver TopoJSON menampilkan objek atribut bersarang sebagai kolom terpisah ketika lapisan dibuka, menggabungkan nama induk dan anak dengan garis bawah, sehingga perataan sudah dilakukan sebelum konversi dijalankan.
Apakah saya perlu menulis kode khusus untuk menangani properti bersarang? Tidak. VectorLayer.Convert menulis semua kolom yang diekspose oleh lapisan sumber, sehingga properti bersarang tidak memerlukan kode parsing tambahan dari Anda.
Bagaimana saya dapat menyertakan geometri dalam output CSV? Buat instance CsvOptions, atur properti ColumnWkt-nya ke nama kolom yang Anda inginkan, tetapkan ke ConversionOptions.DestinationDriverOptions, dan berikan itu ke VectorLayer.Convert.
Mengapa geometri kosong ketika saya membaca kembali CSV saya? CSV tidak memiliki kolom geometri kecuali Anda memintanya. Atur ColumnWkt pada CsvOptions yang Anda berikan baik saat menulis maupun saat membaca, jika tidak driver tidak memiliki kolom untuk membangun geometri.
Pengecualian apa yang harus saya tangani selama konversi? Pengecualian yang didokumentasikan adalah ArgumentNullException untuk jalur yang null, ArgumentException ketika objek opsi tidak cocok dengan driver, GisException ketika fitur tidak dapat dibaca dari file, dan IOException untuk kegagalan I/O yang mendasari.
Apakah saya dapat mengonversi sekumpulan file TopoJSON sekaligus? Ya. Lakukan iterasi pada daftar file dan panggil VectorLayer.Convert untuk setiap file. Jika Anda memparallelkan loop, berikan setiap pekerja instance VectorLayer dan opsi masing‑masing daripada berbagi satu instance di antara thread.
Apakah konversi mengubah sistem koordinat? Tidak secara default. Untuk melakukan reproyeksi selama konversi, atur ConversionOptions.DestinationSpatialReferenceSystem ke sistem target sebelum memanggil Convert.

Baca Selengkapnya

Konversi GEOJSON ke Topojson di .NET: Panduan Contoh

Mengapa Mengonversi TopoJSON ke CSV menggunakan Aspose.GIS#

Prasyarat Konversi TopoJSON ke CSV#

Periksa Skema Datar Sebelum Anda Mengonversi#

Mengonversi TopoJSON ke CSV Sambil Mempertahankan Atribut Bersarang#

Sertakan Geometri sebagai WKT Menggunakan CsvOptions#

Proyeksikan Ulang Selama Konversi#

Konversi Batch Folder Berkas TopoJSON#

Dapatkan Lisensi Gratis#

Sumber Daya Tambahan Gratis#

Kesimpulan#

FAQ#

Baca Selengkapnya#