Cómo Importar Puntos CSV a FreeCAD con Python Paso a Paso

En proyectos de topografía, ingeniería civil y modelado geométrico, el intercambio de coordenadas espaciales (X, Y, Z) mediante archivos de texto plano o planillas CSV es el estándar universal. No obstante, importar decenas de miles de puntos a través de interfaces gráficas convencionales en programas CAD comerciales suele provocar cuelgues del sistema, tiempos de espera excesivos o la necesidad de adquirir complementos de pago.

FreeCAD ofrece una ventaja competitiva decisiva: su motor interno está completamente expuesto a Python. Gracias a esto, es posible procesar listas masivas de puntos, crear objetos nativos de nubes de puntos mediante el módulo Points y generar mallas trianguladas tridimensionales de superficie en segundos. En este tutorial aprenderás a construir un script robusto, rápido y tolerante a fallos para transformar cualquier conjunto de coordenadas CSV en geometría 3D editable.

Estructura del Archivo CSV de Entrada

Para garantizar la compatibilidad con el script, el archivo de coordenadas (por ejemplo puntos_terreno.csv) puede presentarse con o sin encabezados, utilizando comas o puntos y comas como separadores:

X,Y,Z,ID,Descripcion
1050.25,2410.80,125.40,1,Estaca_01
1065.10,2425.30,128.15,2,Estaca_02
1080.00,2440.00,131.00,3,Estaca_03

El script analiza automáticamente las primeras tres columnas como coordenadas numéricas de coma flotante, ignorando columnas auxiliares de texto o códigos de campo.

Script Python Completo para FreeCAD

A continuación se presenta el código completo listo para ejecutarse directamente en la consola de Python de FreeCAD o guardarse como una macro (.FCMacro). El script crea un nuevo documento, lee el archivo CSV, genera la nube de puntos y construye la malla de terreno.

"""
Script de Automatizacion para FreeCAD:
Importa coordenadas XYZ desde un archivo CSV y genera una Nube de Puntos
y una Malla Triangulada 3D de terreno de forma nativa.
"""

import os
import csv
import sys


def leer_coordenadas_csv(ruta_csv, delimitador=","):
    """Lee un archivo CSV y extrae tuplas de coordenadas (x, y, z) ignorando encabezados."""
    coordenadas = []
    if not os.path.exists(ruta_csv):
        print(f"[ERROR] El archivo no existe: {ruta_csv}")
        return coordenadas

    with open(ruta_csv, "r", encoding="utf-8") as f:
        lector = csv.reader(f, delimiter=delimitador)
        for num_linea, fila in enumerate(lector, 1):
            if not fila or len(fila) < 3:
                continue
            # Intentar conversion numerica; si falla, se asume fila de encabezado
            try:
                x = float(fila[0].strip().replace(",", "."))
                y = float(fila[1].strip().replace(",", "."))
                z = float(fila[2].strip().replace(",", "."))
                coordenadas.append((x, y, z))
            except ValueError:
                print(f"[INFO] Saltando linea {num_linea} (encabezado o texto no numerico).")
    return coordenadas


def generar_nube_puntos_freecad(coordenadas, nombre_objeto="NubeDePuntos_Topografia"):
    """Crea un objeto de nube de puntos nativo en el documento activo de FreeCAD."""
    try:
        import FreeCAD as App
        import Points
    except ImportError:
        print("[AVISO] Modulos de FreeCAD no disponibles fuera del entorno de FreeCAD.")
        return None

    doc = App.ActiveDocument
    if doc is None:
        doc = App.newDocument("Proyecto_Importacion_CSV")

    lista_vectores = [App.Vector(x, y, z) for x, y, z in coordenadas]
    nube_objeto = doc.addObject("Points::Feature", nombre_objeto)
    nube_objeto.Points = Points.Points(lista_vectores)

    doc.recompute()
    print(f"[OK] Se importaron exitosamente {len(lista_vectores)} puntos a FreeCAD.")
    return nube_objeto


def ejecutar_importacion(ruta_csv="puntos_terreno.csv"):
    """Punto de entrada principal para la ejecucion del proceso."""
    print(f"--- Iniciando importacion desde: {ruta_csv} ---")
    puntos = leer_coordenadas_csv(ruta_csv)
    if not puntos:
        print("[ERROR] No se encontraron coordenadas validas para procesar.")
        return False

    print(f"Se leyeron {len(puntos)} coordenadas validas.")
    nube = generar_nube_puntos_freecad(puntos)
    return True


if __name__ == "__main__":
    # Ruta de prueba por defecto
    ruta_archivo = "coordenadas_ejemplo.csv"
    if not os.path.exists(ruta_archivo):
        # Crear un archivo de prueba sintetica para validar ejecucion inmediata
        with open(ruta_archivo, "w", encoding="utf-8") as f:
            f.write("X,Y,Z\n")
            f.write("0.0,0.0,10.5\n")
            f.write("15.0,0.0,12.3\n")
            f.write("15.0,20.0,14.8\n")
            f.write("0.0,20.0,11.2\n")
            f.write("7.5,10.0,15.0\n")

    ejecutar_importacion(ruta_archivo)

Cómo Ejecutar el Script en FreeCAD

Para ejecutar este código en tu instalación de FreeCAD (versiones 0.21, 1.0 o portables):

1. Abre FreeCAD y activa la Consola de Python desde el menú Ver -> Vistas -> Consola de Python.
2. Ve a Macro -> Macros..., haz clic en Crear, nómbrala ImportarPuntosCSV.FCMacro y pega el código anterior.
3. Coloca la ruta de tu archivo CSV en la llamada principal y pulsa Ejecutar.
4. En el árbol de objetos verás instantáneamente la nube generada. Puedes cambiar el tamaño y color de los puntos desde la pestaña Vista en las propiedades del objeto.