Por que sua conversão de Shapefile falha e como corrigi‑la em C#

Você executa uma conversão de Shapefiles que funcionou centenas de vezes, e desta vez ela para com uma TransformationException. Não há saída parcial e nenhuma indicação clara de qual registro causou o problema. Frequentemente o culpado é uma única coordenada inválida enterrada entre milhares de recursos válidos. Este artigo explica por que a conversão de Shapefile falha com esse erro e como corrigi‑lo em C# usando OperationErrorCollector, introduzido no Aspose.GIS for .NET 26.6. Você aprenderá como permitir que a conversão termine, manter cada recurso válido e obter um relatório preciso dos registros que precisam de atenção.

Se você só precisa do código básico de conversão, veja Convert Shapefile to KML in C#. Este guia se baseia nisso e foca no tratamento dos erros.

Por que a conversão de Shapefile lança TransformationException

A maioria dos formatos de destino espera coordenadas em um sistema de coordenadas específico. KML, por exemplo, sempre usa longitude e latitude WGS 84. Durante a conversão, Aspose.GIS transforma cada coordenada do sistema de coordenadas de origem para o de destino. Se alguma coordenada não puder ser transformada, a biblioteca lança um TransformationException e a conversão é interrompida.

As causas mais comuns são:

• Valores de placeholder “no data”. Algumas ferramentas gravam um valor sentinela em vez de deixar a geometria vazia. O arquivo de exemplo neste artigo contém um ponto em (-1.7976931348623157E+308, -1.7976931348623157E+308), o valor mínimo de um double, que nenhum sistema de coordenadas pode transformar.
• Coordenadas fora do intervalo. Valores que ficam fora da área válida do sistema de coordenadas de origem, frequentemente causados por erros de entrada de dados ou conversões de unidades incorretas.
• Um arquivo .prj que não corresponde aos dados. Se coordenadas projetadas em metros forem declaradas como coordenadas geográficas em graus, muitos valores ficam muito fora do intervalo válido.
• Registros de geometria corrompidos. Exportações legadas e arquivos danificados podem conter valores numéricos inválidos em registros individuais.

Em todos os casos, o problema geralmente está limitado a um pequeno número de registros, porém o comportamento padrão descarta toda a conversão.

Por que este recurso importa

Parar na primeira falha é seguro, mas é custoso em pipelines reais. Um registro com erro obriga você a limpar o arquivo manualmente antes que qualquer dado possa ser convertido, e a exceção por si só não informa quantos outros registros são afetados. Com a coleta de erros habilitada, você pode:

• Converta todos os recursos válidos em vez de perder todo o arquivo por causa de um registro inválido.
• Registre o índice e as coordenadas de cada recurso ignorado para que os dados de origem possam ser corrigidos.
• Execute conversões em lote não supervisionadas e trabalhos ETL sem travar com entrada suja.
• Aceite Shapefiles enviados pelos usuários em serviços web e relate os problemas de dados de volta ao usuário.

Como corrigir falhas de conversão de Shapefile em C# com Aspose.GIS

Aspose.GIS for .NET é uma biblioteca gerenciada para leitura, gravação e conversão de formatos geoespaciais como Shapefile, KML, GeoJSON, GML e File Geodatabase sem a necessidade de nenhum outro software GIS instalado. A coleta de erros requer a versão 26.6 ou posterior. Instale o pacote via NuGet:

dotnet add package Aspose.GIS

Ou use o Console do Gerenciador de Pacotes:

Install-Package Aspose.GIS

Os seguintes tipos são usados neste tutorial:

• VectorLayer (Aspose.Gis): abre, cria e converte camadas vetoriais. VectorLayer.Convert realiza a conversão.
• ConversionOptions (Aspose.Gis): contém as configurações de conversão, incluindo DestinationDriverOptions e DestinationSpatialReferenceSystem.
• KmlOptions (Aspose.Gis.Formats.Kml): opções do driver KML. Herda a propriedade ErrorCollector de DriverOptions.
• OperationErrorCollector (Aspose.Gis.Operations): armazena erros recuperáveis. Expõe Errors, Count, HasErrors, Add e Clear.
• OperationError e TransformationError (Aspose.Gis.Operations): cada erro possui uma Message e uma Exception. TransformationError adiciona FeatureIndex, X, Y e Z.
• TransformationException (Aspose.Gis.SpatialReferencing): lançada quando uma coordenada não pode ser transformada e nenhum coletor está anexado.

Como corrigir TransformationException durante a conversão de Shapefile

A correção tem duas partes. Primeiro, anexe um OperationErrorCollector para que a conversão ignore recursos inválidos em vez de falhar. Segundo, use o relatório coletado para reparar ou remover esses registros na origem. As etapas abaixo usam uma conversão de Shapefile para KML como exemplo.

1. Prepare o Ambiente

1. Crie um projeto de console .NET e adicione o pacote NuGet Aspose.GIS 26.6+.
2. Copie o Shapefile e seus arquivos acompanhantes (.shp, .shx, .dbf e .prj) para uma pasta. Este exemplo usa data/light-traffics.shp.
3. Adicione os namespaces necessários:

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

2. Criar um OperationErrorCollector

O coletor registra cada erro recuperável gerado durante a conversão. Crie uma nova instância para cada conversão, de modo que os erros de diferentes arquivos não sejam misturados.

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

3. Anexar o Coletor por meio de ConversionOptions

Atribua o coletor a KmlOptions.ErrorCollector, então passe as opções KML como DestinationDriverOptions. Definir DestinationSpatialReferenceSystem para WGS 84 é opcional para KML, mas torna o sistema de coordenadas de destino explícito no seu código.

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. Executar a Conversão

Chame VectorLayer.Convert com o caminho de origem, o driver Shapefile, o caminho de destino, o driver KML e as opções que você acabou de configurar.

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);

Quando um elemento não pode ser transformado, o driver KML adiciona um erro ao coletor, ignora esse elemento e continua com o próximo. Nenhuma TransformationException é lançada.

5. Relatar Recursos Ignorados e Verificar a Saída

Uma conversão que retorna normalmente ainda pode ter pulado recursos, portanto sempre verifique o coletor depois. Converta cada erro para TransformationError para obter o índice do recurso e a coordenada que falhou, então abra o arquivo de saída para confirmar quantos recursos foram gravados.

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}");
}

Para o arquivo de exemplo, o coletor registra um erro para o ponto de espaço reservado, e os recursos restantes (pelo menos 444) são gravados no arquivo KML.

O índice de recursos e as coordenadas neste relatório completam a correção. Abra o Shapefile de origem em seu fluxo de trabalho de limpeza de dados, localize os registros relatados e corrija‑os ou remova‑os. Se muitos registros falharem com valores aparentemente razoáveis, verifique o arquivo .prj primeiro, pois um sistema de coordenadas incompatível é a causa provável.

6. Código de Exemplo Completo

A aplicação console completa abaixo executa a conversão duas vezes. A primeira execução usa as configurações padrão e reproduz a TransformationException. A segunda execução anexa um OperationErrorCollector, ignora o recurso inválido e imprime um relatório.

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. Armadilhas Comuns e Como Evitá‑las

Obtenha uma Licença Gratuita

Você pode obter uma licença temporária gratuita para Aspose.GIS na página de licença temporária da Aspose: https://purchase.aspose.com/temporary-license/.

Recursos Adicionais Gratuitos

• Documentação: https://docs.aspose.com/gis/net/
• Referência da API: https://reference.aspose.com/gis/net/
• Aplicativos Web Gratuitos: https://products.aspose.app/gis/family

Conclusão

Um TransformationException durante a conversão de Shapefile geralmente significa que um pequeno número de registros contém coordenadas que não podem ser transformadas, como valores de espaço reservado, números fora do intervalo ou dados que não correspondem ao seu arquivo .prj. Corrigir isso em C# requer duas etapas: anexar um OperationErrorCollector para que Aspose.GIS for .NET ignore recursos inválidos e conclua a conversão, depois usar os índices de recursos e coordenadas coletados para reparar os dados de origem. O resultado é um pipeline que continua entregando saída válida enquanto transforma falhas críticas em relatórios acionáveis de qualidade de dados.

FAQs

1. Por que a exceção TransformationException ocorre ao converter um Shapefile? Isso ocorre quando uma coordenada não pode ser transformada do sistema de coordenadas de origem para o de destino. As causas comuns são valores de espaço reservado “no data”, coordenadas fora do intervalo válido do seu sistema de coordenadas, um arquivo .prj que não corresponde aos dados reais e registros de geometria corrompidos.

2. O que acontece por padrão quando uma coordenada não pode ser transformada? VectorLayer.Convert lança uma TransformationException e a conversão é interrompida. A partir da versão 26.6, a exceção também expõe os valores X, Y e Z da coordenada que falhou.

3. Qual versão do Aspose.GIS for .NET suporta OperationErrorCollector? OperationErrorCollector e a propriedade DriverOptions.ErrorCollector foram introduzidos no Aspose.GIS for .NET 26.6. Versões anteriores não os incluem.

4. O OperationErrorCollector repara coordenadas inválidas? Não. Ele ignora os recursos que falham na transformação e os registra, de modo que a saída contém apenas recursos válidos. Use o índice de recurso e as coordenadas relatados para corrigir ou remover os registros problemáticos nos dados de origem.

5. Posso usar OperationErrorCollector com formatos de saída diferentes de KML? ErrorCollector é definido na classe base DriverOptions, portanto cada classe de opções de driver a expõe. Exemplos documentados cobrem destinos KML e MapInfo TAB; teste o comportamento com seu próprio driver de destino antes de confiar nele em produção.

6. Quais detalhes cada erro coletado contém? Cada OperationError fornece uma Message e a Exception subjacente. Falhas de transformação são relatadas como objetos TransformationError, que adicionam o FeatureIndex e os valores X, Y e Z da coordenada com falha.

7. Como sei se uma conversão foi concluída sem erros?
   Verifique a propriedade HasErrors ou Count do coletor após o retorno de VectorLayer.Convert. Uma conversão que termina sem lançar exceções ainda pode ter ignorado recursos.

Leia Mais

• Converter Shapefile para KML em C#
• Conversão de GEOJSON para Topojson em .NET: Guia de Exemplo