Ejecutas una conversión de Shapefiles que ha funcionado cientos de veces, y esta vez se detiene con una TransformationException. No hay salida parcial y no hay una indicación clara de qué registro causó el problema. A menudo el culpable es una única coordenada inválida enterrada entre miles de características válidas. Este artículo explica por qué la conversión de Shapefile falla con este error y cómo solucionarlo en C# usando OperationErrorCollector, introducido en Aspose.GIS for .NET 26.6. Aprenderás cómo permitir que la conversión termine, conservar cada característica válida y obtener un informe preciso de los registros que necesitan atención.

Si solo necesita el código de conversión básico, consulte Convertir Shapefile a KML en C#. Esta guía se basa en eso y se centra en el manejo de los errores.

Por qué la conversión de Shapefile lanza TransformationException

La mayoría de los formatos de destino esperan coordenadas en un sistema de coordenadas específico. KML, por ejemplo, siempre utiliza longitud y latitud WGS 84. Durante la conversión, Aspose.GIS transforma cada coordenada del sistema de coordenadas de origen al de destino. Si alguna coordenada no puede transformarse, la biblioteca lanza una TransformationException y la conversión se detiene.

Las causas más comunes son:

  • Valores de marcador de posición “no data”. Algunas herramientas escriben un valor centinela en lugar de dejar una geometría vacía. El archivo de ejemplo en este artículo contiene un punto en (-1.7976931348623157E+308, -1.7976931348623157E+308), el valor mínimo de un double, que ningún sistema de coordenadas puede transformar.
  • Coordenadas fuera de rango. Valores que caen fuera del área válida del sistema de coordenadas de origen, a menudo causados por errores de entrada de datos o conversiones de unidades incorrectas.
  • Un archivo .prj que no coincide con los datos. Si las coordenadas proyectadas en metros se declaran como coordenadas geográficas en grados, muchos valores terminan muy fuera del rango válido.
  • Registros de geometría corruptos. Exportaciones heredadas y archivos dañados pueden contener valores numéricos no válidos en registros individuales.

En cada caso, el problema suele estar limitado a un puñado de registros, pero el comportamiento predeterminado descarta toda la conversión.

Por qué esta característica es importante

Detenerse en el primer error es seguro, pero resulta costoso en pipelines reales. Un registro incorrecto obliga a limpiar el archivo manualmente antes de que se pueda convertir cualquier dato, y la excepción por sí sola no indica cuántos otros registros se ven afectados. Con la recopilación de errores habilitada, puedes:

  • Convierta todas las características válidas en lugar de perder todo el archivo por un registro defectuoso.
  • Registre el índice y las coordenadas de cada característica omitida para que los datos de origen puedan repararse.
  • Ejecute conversiones por lotes sin supervisión y trabajos ETL sin fallar con entradas sucias.
  • Acepte Shapefiles cargados por el usuario en servicios web e informe los problemas de datos al usuario.

Cómo solucionar fallas de conversión de Shapefile en C# con Aspose.GIS

Aspose.GIS for .NET es una biblioteca administrada para leer, escribir y convertir formatos geoespaciales como Shapefile, KML, GeoJSON, GML y File Geodatabase sin necesidad de instalar otro software GIS. La recopilación de errores requiere la versión 26.6 o posterior. Instale el paquete desde NuGet:

dotnet add package Aspose.GIS

O use la Consola del Administrador de paquetes:

Install-Package Aspose.GIS

Los siguientes tipos se utilizan en este tutorial:

  • VectorLayer (Aspose.Gis): abre, crea y convierte capas vectoriales. VectorLayer.Convert realiza la conversión.
  • ConversionOptions (Aspose.Gis): contiene la configuración de conversión, incluyendo DestinationDriverOptions y DestinationSpatialReferenceSystem.
  • KmlOptions (Aspose.Gis.Formats.Kml): Opciones del controlador KML. Hereda la propiedad ErrorCollector de DriverOptions.
  • OperationErrorCollector (Aspose.Gis.Operations): almacena errores recuperables. Expone Errors, Count, HasErrors, Add y Clear.
  • OperationError y TransformationError (Aspose.Gis.Operations): cada error tiene un Message y una Exception. TransformationError agrega FeatureIndex, X, Y y Z.
  • TransformationException (Aspose.Gis.SpatialReferencing): lanzada cuando una coordenada no puede transformarse y no hay un colector adjunto.

Cómo solucionar TransformationException durante la conversión de Shapefile

La solución tiene dos partes. Primero, adjunte un OperationErrorCollector para que la conversión omita las características no válidas en lugar de fallar. Segundo, use el informe recopilado para reparar o eliminar esos registros en la fuente. Los pasos a continuación utilizan una conversión de Shapefile a KML como ejemplo.

1. Preparar el entorno

  1. Crea un proyecto de consola .NET y agrega el paquete NuGet Aspose.GIS 26.6+.
  2. Copia el Shapefile y sus archivos complementarios (.shp, .shx, .dbf y .prj) en una carpeta. Este ejemplo usa data/light-traffics.shp.
  3. Agrega los espacios de nombres requeridos:
using System;
using System.IO;
using Aspose.Gis;
using Aspose.Gis.Formats.Kml;
using Aspose.Gis.Operations;
using Aspose.Gis.SpatialReferencing;

2. Crear un OperationErrorCollector

El recopilador registra cada error recuperable generado durante la conversión. Cree una nueva instancia para cada conversión de modo que los errores de diferentes archivos no se mezclen.

// Registra errores recuperables en lugar de lanzarlos.
var errors = new OperationErrorCollector();

3. Adjuntar el Collector a través de ConversionOptions

Asignar el recolector a KmlOptions.ErrorCollector, luego pasar las opciones KML como DestinationDriverOptions. Configurar DestinationSpatialReferenceSystem a WGS 84 es opcional para KML, pero hace que el sistema de coordenadas de destino sea explícito en su 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. Ejecutar la conversión

Llame a VectorLayer.Convert con la ruta de origen, el controlador Shapefile, la ruta de destino, el controlador KML y las opciones que acaba 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);

Cuando una característica no puede ser transformada, el controlador KML agrega un error al recopilador, omite esa característica y continúa con la siguiente. No se lanza TransformationException.

5. Informar características omitidas y verificar la salida

Una conversión que devuelve normalmente puede haber omitido características, así que siempre verifica el colector después. Convierte cada error a TransformationError para obtener el índice de la característica y la coordenada que falló, luego abre el archivo de salida para confirmar cuántas características se escribieron.

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 el archivo de muestra, el recopilador registra un error para el punto de marcador de posición, y las características restantes (al menos 444) se escriben en el archivo KML.

El índice de características y las coordenadas en este informe completan la corrección. Abra el Shapefile de origen en su flujo de trabajo de limpieza de datos, localice los registros reportados y corríjalos o elimínelos. Si muchos registros fallan con valores que parecen razonables, verifique primero el archivo .prj, ya que una discrepancia en el sistema de coordenadas es la causa probable.

6. Código de muestra completo

La aplicación de consola completa a continuación ejecuta la conversión dos veces. La primera ejecución usa la configuración predeterminada y reproduce la TransformationException. La segunda ejecución adjunta un OperationErrorCollector, omite la característica no válida y muestra un informe.

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. Errores comunes y cómo evitarlos

ProblemaRazónSolución
ErrorCollector o OperationErrorCollector no compilaAmbos se añadieron en Aspose.GIS for .NET 26.6.Actualice el paquete NuGet a 26.6 o posterior.
La conversión aún lanza TransformationExceptionNo se adjunta ningún colector a las opciones del controlador de destino.Establezca ErrorCollector en el objeto de opciones del controlador asignado a ConversionOptions.DestinationDriverOptions.
Una conversión “exitosa” carece de característicasEl colector suprime la excepción, por lo que Convert devuelve normalmente.Verifique errors.HasErrors después de cada llamada y registre los resultados.
Tratar las características omitidas como corregidasEl colector omite los registros inválidos; no los repara.Utilice el índice de característica y coordenadas reportados para corregir o eliminar los registros en los datos de origen.
Cientos de características fallan de una vezProbablemente el archivo .prj no coincide con las coordenadas reales.Verifique el sistema de coordenadas de origen antes de investigar registros individuales.
Los errores de varios archivos aparecen en un solo informeSe reutilizó la misma instancia del colector en varias conversiones.Cree un nuevo OperationErrorCollector por archivo, o llame a Clear() entre ejecuciones.
Errores de bloqueo de archivo en ejecuciones repetidasUna capa abierta con VectorLayer.Open no se liberó.Envuelva VectorLayer.Open en un bloque using.

Obtén una licencia gratuita

Puede obtener una licencia temporal gratuita para Aspose.GIS desde la página de licencia temporal de Aspose: https://purchase.aspose.com/temporary-license/

Recursos adicionales gratuitos

Conclusión

Una TransformationException durante la conversión de Shapefile generalmente significa que un pequeño número de registros contiene coordenadas que no pueden transformarse, como valores de marcador de posición, números fuera de rango o datos que no coinciden con su archivo .prj. Solucionarlo en C# requiere dos pasos: adjuntar un OperationErrorCollector para que Aspose.GIS for .NET omita las características inválidas y complete la conversión, luego usar los índices y coordenadas de las características recopiladas para reparar los datos de origen. El resultado es una canalización que sigue entregando salida válida mientras convierte fallos críticos en informes de calidad de datos accionables.

Preguntas frecuentes

  1. ¿Por qué ocurre TransformationException al convertir un Shapefile? Ocurre cuando una coordenada no puede transformarse del sistema de coordenadas de origen al de destino. Las causas comunes son valores de marcador de posición “no data”, coordenadas fuera del rango válido de su sistema de coordenadas, un archivo .prj que no coincide con los datos reales y registros de geometría corruptos.

  2. ¿Qué ocurre por defecto cuando una coordenada no puede ser transformada? VectorLayer.Convert lanza una TransformationException y la conversión se detiene. A partir de la versión 26.6, la excepción también expone los valores X, Y y Z de la coordenada que falló.

  3. ¿Qué versión de Aspose.GIS for .NET admite OperationErrorCollector? OperationErrorCollector y la propiedad DriverOptions.ErrorCollector se introdujeron en Aspose.GIS for .NET 26.6. Las versiones anteriores no los incluyen.

  4. ¿OperationErrorCollector repara coordenadas inválidas? No. Omite las características que fallan la transformación y las registra, por lo que la salida contiene solo características válidas. Utilice el índice de característica y las coordenadas informados para corregir o eliminar los registros incorrectos en los datos de origen.

  5. ¿Puedo usar OperationErrorCollector con formatos de salida diferentes a KML? ErrorCollector está definido en la clase base DriverOptions, por lo que cada clase de opciones de controlador lo expone. Los ejemplos documentados cubren destinos KML y MapInfo TAB; pruebe el comportamiento con su propio controlador de destino antes de confiar en él en producción.

  6. ¿Qué detalles contiene cada error recopilado? Cada OperationError proporciona un Message y la Exception subyacente. Los fallos de transformación se informan como objetos TransformationError, que añaden el FeatureIndex y los valores X, Y y Z de la coordenada que falla.

  7. ¿Cómo sé si una conversión se completó sin errores? Verifique la propiedad HasErrors o Count del recolector después de que VectorLayer.Convert devuelva. Una conversión que finaliza sin lanzar una excepción aún puede haber omitido características.

Leer más