cfasig — Librería SIG, CONSAEFA S.C.

Wrapper en español sobre geopandas/shapely (vector) y rasterio/pysheds/scipy (raster) que simplifica tareas repetidas de SIG (cargar de shapefile o de puntos CSV/Excel, recortar, disolver, buffer, combinar, convertir entre puntos/líneas/polígonos, guardar; remuestrear, hidrología, aspecto). La idea es tener una sola función clara por operación en lugar de repetir la sintaxis de cada librería en cada script.

Versión: 0.1.0 | Fecha: Julio 2026 Paquete: cfasig (Python ≥ 3.10; probado en 3.14) Ruta local: %USERPROFILE%\Downloads\cfasig\

Stack

• Base vector: geopandas ≥ 0.13 (GeoDataFrame como estructura central).
• Geometría: shapely ≥ 2.0 (unary_union, box, buffer, difference, split).
• Tablas: pandas ≥ 1.5 (concatenación de capas), openpyxl ≥ 3.1 (lectura de .xlsx en cargar_puntos).
• Raster: rasterio ≥ 1.3 (recorte, remuestreo, rasterización, poligonización), numpy ≥ 1.24 (arrays), scipy ≥ 1.10 (ndimage: etiquetado, relleno, suavizado; interpolate/spatial: interpolación de MDE por TIN/IDW), pysheds ≥ 0.3 (dirección/acumulación de flujo).
• Empaquetado: setuptools + pyproject.toml. Instalable en modo editable con pip install -e .. Licencia MIT. Expone el comando de consola cfasig (ver sección CLI). Dev: pytest ≥ 7, ruff ≥ 0.1.
• Idioma: API, funciones y docstrings en español; distancias en las unidades del CRS (metros si es UTM).
• Filosofía: wrapper delgado. Cada función es una operación conocida de las librerías base con nombre simple, valores por defecto sensatos y mensajes de aviso en consola. No reinventa; ordena. No está limitado a geopandas/shapely: cubre SIG en general (vector y raster).

Estructura de archivos

Layout src/: el paquete vive bajo src/cfasig/, así que hay que instalarlo (pip install -e .) para importarlo; evita que los tests importen el código desde la carpeta en vez del instalado.

• Raíz: pyproject.toml / README.md / CLAUDE.md (convenciones de código, estilo "ponytail")
• ejemplos/ — scripts de referencia: caminos.py, hidrologia.py, rodalizacion.py
• src/cfasig/
  • __init__.py — expone toda la API pública (import cfasig as sig)
  • archivo.py — entrada/salida de capas
  • proyeccion.py — sistemas de coordenadas (CRS)
  • geometria.py — operaciones geométricas (vector)
  • campos.py — utilidades de columnas de atributos
  • raster.py — operaciones raster (recorte, remuestreo, hidrología, aspecto)
  • cli.py — comando de consola cfasig (convierte entre formatos)
• tests/ — suite pytest (conftest.py con fixtures + un test_*.py por módulo)

API pública (import cfasig as sig)

archivo.py

• cargar(ruta, capa=None, mostrar=True) — lee una capa vectorial (.shp/.gpkg/.geojson/.gpx) como GeoDataFrame; capa elige la capa en formatos multicapa (GPX: waypoints/routes/tracks; GeoPackage). Opcionalmente imprime nº de entidades y CRS.
• cargar_puntos(ruta, x="x", y="y", epsg=None, orden=None, mostrar=True) — arma una capa de puntos desde un CSV o Excel (.csv/.xlsx/.xls) con columnas de coordenadas. x/y nombran las columnas de coordenada; epsg fija el CRS (el archivo de texto no lo trae, sin él no se puede reproyectar ni medir áreas); orden ordena las filas por una columna de secuencia antes de armar la capa (importa si luego conviertes a línea/polígono). Todas las columnas del archivo quedan como atributos.
• convertir(entrada, salida, capa=None, gpx_como="track", mostrar=True) — convierte de un formato a otro (cargar + guardar) en una línea; útil para bucles de lote. Si la entrada es GPX y no se da capa, autodetecta la capa con datos (un GPX de solo tracks leído a secas sale vacío porque la capa por defecto es waypoints).
• guardar(gdf, ruta, gpx_como="track", mostrar=True) — escribe la capa; el formato se deduce de la extensión. Para .gpx/.kml/.kmz reproyecta automáticamente a EPSG:4326 (esos formatos solo aceptan lon/lat) y usa el driver adecuado (GPX / LIBKML). Convertir = cargar + guardar: p. ej. guardar(cargar("predio.shp"), "predio.kmz"). GPX no admite polígonos: se exporta su contorno como línea. gpx_como decide cómo se escriben las líneas en GPX: "track" (por defecto, como trabaja el GPS aquí) o "route".
• cargar_waypoints(ruta, mostrar=True) — lee los waypoints de un GPX con la tabla de atributos limpia (columnas NAME, LAYER, ELEVATION, time en ISO UTC, sym), descartando las ~18 columnas vacías del esquema fijo de GPX. Estilo Global Mapper.
• cargar_tracks(ruta, utc_offset=-6, mostrar=True) — lee los tracks de un GPX, una línea por tramo (<trkseg>), con columnas limpias (NAME, LAYER, gpxx_DisplayColor, START_TIME, END_TIME). Los tiempos salen del primer/último punto del tramo convertidos a hora local (utc_offset, por defecto -6 = Jalisco) con formato español. convertir usa estos dos lectores automáticamente para GPX (waypoints/tracks); las routes u otras capas caen al lector genérico.

proyeccion.py

• reproyectar(gdf, epsg) — reproyecta siempre al EPSG indicado (to_crs).
• asegurar_crs(gdf, epsg, nombre="capa") — reproyecta solo si la capa no está ya en ese EPSG; avisa cuando lo hace. Evita reproyecciones innecesarias.

geometria.py

• recortar(gdf, mascara) — recorta (clip) por otra capa; reproyecta la máscara al CRS de gdf si difieren.
• disolver(gdf, campo=None, valor=None) — une todas las geometrías en una sola (unary_union); opcionalmente etiqueta el resultado con campo=valor.
• buffer(gdf, distancia) — área de influencia por geometría (unidades del CRS); devuelve copia, no muta el original.
• quitar_solape(gdf, otro, limpiar=True) — resta de gdf lo que pise otro (difference), dando prioridad a otro; limpia vacías por defecto.
• combinar(capas) — concatena una lista de capas en una sola (toma el CRS de la primera).
• puntos_a_linea(gdf, campo=None) — une los puntos en una línea siguiendo el orden de las filas; con campo genera una línea por cada valor distinto (agrupación). Requiere ≥2 puntos por línea.
• puntos_a_poligono(gdf, campo=None, envolvente=False) — une los puntos en un polígono usándolos como vértices en orden de filas; con envolvente=True usa la envolvente convexa (útil si no vienen ordenados por el contorno); con campo, un polígono por grupo. Requiere ≥3 puntos.
• linea_a_poligono(gdf) — cierra cada línea en un polígono (sus vértices como contorno); si la línea está abierta, une el último punto con el primero. Conserva atributos.
• crear_cuadro(gdf, margen=0) — rectángulo (bounding box) alrededor de la capa, ampliado margen; útil como máscara de recorte previo rápido.
• limpiar_vacias(gdf) — elimina entidades con geometría vacía o nula.
• reparar_geometrias(gdf) — buffer(0) + descarta inválidas/vacías; el patrón de reparación que se repite tras cada operación pesada.
• calcular_superficie(gdf, campo="superficie_ha", en_hectareas=True, decimales=4) — añade una columna de área (m² del CRS, o ha si en_hectareas).
• intersectar(gdf, otro) — intersección con overlay conservando atributos de ambas capas (distinto de recortar, que solo recorta).
• unir_atributos(gdf, otro, como="left", predicado="intersects") — spatial join: pega las columnas de otro a gdf según su posición sin cortar geometrías (a diferencia de intersectar). predicado = 'intersects'/'within'/'contains'... Reproyecta otro si difiere el CRS.
• calcular_longitud(gdf, campo="longitud_m", en_km=False, decimales=4) — añade una columna con la longitud de cada geometría (unidades del CRS, o km si en_km); gemelo de calcular_superficie para líneas.
• simplificar(gdf, tolerancia, conservar_topologia=True) — reduce vértices (Douglas-Peucker); tolerancia en unidades del CRS. Con conservar_topologia (por defecto) evita auto-cruces y no rompe bordes compartidos entre polígonos vecinos.
• cerrar_microhuecos(gdf, distancia, estilo_junta=2) — closing morfológico (expandir/contraer) que cierra huecos menores a distancia.
• subdividir_por_area(gdf, area_max_ha, campo_area="superficie_ha", min_esquirla=100, max_prof=8) — parte los polígonos que superen area_max_ha por bisección recursiva del eje más largo.
• fusionar_menores(gdf, area_min_ha, area_max_ha, campo_area="superficie_ha", max_iter=30) — fusiona iterativamente los polígonos bajo el mínimo con su mejor vecino, sin superar el máximo.

campos.py

• campo_seguro(gdf, campo) — devuelve un nombre de columna que no choque con los existentes (si existe, genera una variante única campo_ab12).

raster.py

• cargar_raster(ruta, mostrar=True) — abre un raster de una banda; devuelve (array, perfil, transform, crs, resolucion_m).
• guardar_raster(arr, ruta, perfil, mostrar=True) — escribe un array 2D a raster (float32).
• recortar_raster(ruta, mascara, nodata=nan) — recorta un raster al contorno de una capa vector (reproyecta la máscara); devuelve (array, perfil, transform, crs, resolucion_m).
• rellenar_nodata(arr) — rellena NaN con el valor del píxel válido más cercano (sin interpolar).
• remuestrear(arr, transform, crs, res_destino, metodo=bilinear) — cambia la resolución; devuelve (array, transform).
• interpolar_mde(curvas, campo_elevacion, resolucion=None, equidistancia=None, intervalo_muestreo=None, cuadro=None, metodo="tin", mostrar=True) — genera un MDE continuo interpolando curvas de nivel vectoriales. Muestrea puntos a intervalos regulares sobre cada curva (evita el sesgo de densidad de vértices) e interpola sobre una malla regular: "tin" (triangulación de Delaunay, respeta quiebres de pendiente) o "idw" (distancia inversa, respaldo si el TIN falla por geometría degenerada). Fuera de la envolvente convexa devuelve NaN (no extrapola; rellena luego con rellenar_nodata). resolucion por defecto = equidistancia/4 redondeada a un valor limpio; equidistancia se autodetecta (moda de las diferencias entre cotas). Devuelve (array, transform); encaja entre el flujo vector (recortar/disolver) y acondicionar_mde/quemar_cauces.
• rasterizar(gdf, forma, transform, valor=1, relleno=0, tipo=uint8) — vector → máscara raster.
• quemar_cauces(mde, cauces, transform, profundidad) — stream burning: baja la elevación del MDE en los cauces; devuelve (array, nº_píxeles_quemados).
• combinar_categorias(a, b, factor=10) — empaqueta dos rasters categóricos en un ID único (a*factor+b); recuperar con //factor y %factor.
• poligonizar(arr, transform, crs, mascara=None, campo="valor") — raster → polígonos vector (acepta máscara booleana o entera).
• acondicionar_mde(mde_path) — pysheds: rellena pits, depresiones y zonas planas; devuelve (grid, mde_acondicionado).
• direccion_flujo(grid, dem) — dirección de flujo D8.
• acumulacion_flujo(grid, fdir) — acumulación de flujo (array numpy).
• etiquetar_cuencas(acumulacion, umbral) — laderas de no-cauce (acumulación ≤ umbral) etiquetadas como cuencas; devuelve (array, n_cuencas).
• calcular_aspecto(mde, res, suavizar=3, nodata=-9999) — orientación cardinal por píxel (0=plano/sin orientación, 1=N, 2=E, 3=S, 4=O).

Ejemplos de uso (ejemplos/)

ejemplos/caminos.py como referencia. Los otros dos (ejemplos/hidrologia.py, ejemplos/rodalizacion.py) siguen el mismo patrón.

"""
Ejemplo: buffer jerárquico de caminos (primario > secundario > saca).

Cada nivel recorta al inferior para que no se solapen. Muestra el uso
de cfasig con un patrón repetido resuelto en un bucle.
"""

import cfasig as sig

# ── CONFIG ───────────────────────────────────────────────────
EPSG_UTM = 32613

# nombre, ruta, buffer (en metros). Orden = prioridad (mayor a menor).
NIVELES = [
    ("PRIMARIO",   "/home/user/Downloads/es/EJ_ESTANCIA_F13_D51_CAMINO_PRIM_1.shp", 5.0),
    ("SECUNDARIO", "/home/user/Downloads/es/EJ_ESTANCIA_F13_D51_CAMINO_SEC_1.shp",  3.0),
    ("SACA",       "/home/user/Downloads/es/EJ_ESTANCIA_F13_D51_CAMINO_SACA_1.shp", 1.75),
]
CAMPO_TIPO = "camino"

SALIDA_COMBINADO = "/home/user/Downloads/CAMINOS_BUFFER_COMBINADO.shp"
SALIDA_DISUELTO = "/home/user/Downloads/CAMINOS_BUFFER_DISUELTO.shp"

# ── 1. CARGAR, ASEGURAR CRS, DISOLVER Y BUFFER CADA NIVEL ────
capas = []
for nombre, ruta, dist in NIVELES:
    gdf = sig.cargar(ruta)
    gdf = sig.asegurar_crs(gdf, EPSG_UTM, nombre)
    gdf = sig.disolver(gdf, campo=CAMPO_TIPO, valor=nombre)
    gdf = sig.buffer(gdf, dist)
    capas.append(gdf)

# ── 2. QUITAR SOLAPE: cada nivel pierde contra el inmediato superior ──
for i in range(1, len(capas)):
    capas[i] = sig.quitar_solape(capas[i], capas[i - 1])

# ── 3. COMBINAR Y GUARDAR ────────────────────────────────────
combinado = sig.combinar(capas)
sig.guardar(combinado, SALIDA_COMBINADO)

# ── 4. VERSIÓN DISUELTA (una sola geometría) ─────────────────
sig.guardar(sig.disolver(combinado, campo="caminos", valor="caminos"), SALIDA_DISUELTO)

Estilo y estructura de un script (confirmado contra los tres scripts de ejemplos/):

• Docstring corto al inicio: qué hace y por qué (una frase de "qué", una de "por qué" si no es obvio).
• Bloque CONFIG arriba de todo, en mayúsculas: rutas, EPSG, distancias, campos. Nada de esto va suelto en medio de la lógica; si hay que tocar un valor para correrlo en otro predio, se toca aquí y solo aquí.
• Cuando hay una lista de "cosas parecidas" y vale la pena (3+ niveles/casos), se modela como lista de tuplas (NIVELES en caminos.py) y se recorre con un for, en vez de repetir el bloque una vez por elemento; el orden puede codificar prioridad. Con solo 2 casos (perenne/intermitente en hidrologia.py) no se generaliza: se escriben los dos bloques directo, sin loop ni lista, porque el loop no ahorra nada con dos ramas. Loop si repites de verdad, directo si no (YAGNI).
• Pasos numerados con comentarios # ── N. VERBO EN MAYÚSCULAS ──: cada bloque es una etapa clara del flujo (cargar, quitar solape, combinar, guardar). Sirve para ubicarse en scripts de 40-100 líneas sin funciones propias.
• El script encadena funciones de cfasig (sig.cargar, sig.buffer, ...); no reimplementa nada que la librería ya resuelva. La única lógica que vive en el script es la específica del caso (qué niveles hay, qué prioridad tienen, claves de dominio como UMM).
• print() como reporte, no logging: además de los avisos que ya imprimen funciones como cargar (nº de entidades, CRS), el script puede imprimir sus propios diagnósticos a media ejecución (valores únicos de un campo, tamaño de un raster, píxeles quemados) y, si el resultado tiene métricas que valen la pena, un resumen al final (conteos, sumas, rangos) — ver rodalizacion.py. Si el script ya va a imprimir lo suyo, usa mostrar=False en cargar/cargar_raster para no duplicar el aviso.
• Sin funciones ni clases propias salvo que el script se vuelva a llamar con distintos parámetros; un script de un solo uso es lineal de arriba a abajo, reutilizando el mismo nombre de variable al reasignar (gdf = sig.algo(gdf)) en vez de encadenar nombres nuevos por paso.
• Nombres de variable en español, cortos y descriptivos (gdf, capas, combinado); constantes de config en mayúsculas.

Instalación / uso

# desde la carpeta que contiene pyproject.toml
pip install -e .

# luego, desde cualquier script:
import cfasig as sig

Con layout src/, la instalación (pip install -e .) es obligatoria: sin ella import cfasig no encuentra el paquete.

CLI (cfasig)

La instalación registra el comando de consola cfasig (project.scripts → cli.main). Hoy hace una sola cosa: convertir archivos entre formatos, uno o varios en la misma llamada (proceso por lote). La salida se autonombra (misma carpeta y nombre, extensión nueva).

cfasig predio.shp kmz            # crea predio.kmz
cfasig ruta.gpx shp              # crea ruta.shp
cfasig a.shp b.shp c.shp kmz     # lote: crea a.kmz, b.kmz, c.kmz
cfasig ayuda                     # muestra la ayuda

Uso: cfasig ARCHIVO [ARCHIVO ...] TIPO. Para el lote se pasan varios archivos y el TIPO al final; pensado para arrastrar los archivos a la terminal (quedan separados por espacios), sin glob ni comodines porque el usuario no técnico los arrastra. Con varios archivos imprime un resumen final (Listo: N convertidos, M con error) y sigue con los demás si uno falla. Un archivo que ya está en el formato destino se salta.

Tipos válidos: shp, gpkg, geojson, gpx, kml, kmz. Opciones avanzadas: --capa NOMBRE (capa a leer en archivos multicapa) y --gpx-como {track,route}. Pide confirmación antes de sobrescribir cada archivo. Ayuda y errores en español; la ayuda no carga geopandas (import perezoso). # ponytail: sin subcomandos porque solo convierte; migra a subparsers si crecen las operaciones.

Tests

Suite en tests/, un archivo por módulo/tema (test_archivo, test_campos, test_proyeccion, test_geometria, test_raster, más test_conversion para el ida y vuelta entre formatos, test_puntos para carga de puntos CSV/Excel y su conversión a línea/polígono, test_gpx para los lectores limpios de waypoints/tracks, y test_cli para el comando de consola), con fixtures compartidas en conftest.py. Cubre la lógica determinista de vector y raster; los helpers de flujo de pysheds (acondicionar_mde, direccion_flujo, acumulacion_flujo) quedan pendientes hasta tener un MDE de prueba.

pip install -e ".[dev]"   # instala pytest
pytest

Convenciones y decisiones

• Wrapper delgado: una función = una operación de la librería base (vector o raster), con nombre simple en español.
• La lógica de dominio (claves UMM, valores calibrados) se queda en los scripts; la librería solo aporta operaciones SIG genéricas.
• Raster: las funciones trabajan sobre arrays 2D (numpy) más su transform/crs, que es como rasterio maneja los datos. Los scripts no necesitan importar numpy para el flujo normal.
• Las funciones que devuelven capa (buffer, quitar_solape, limpiar_vacias) trabajan sobre una copia; no mutan la entrada.
• Distancias y márgenes en unidades del CRS activo (usar UTM para metros).
• disolver y combinar conservan el CRS de origen; recortar alinea CRS automáticamente.
• Prioridad entre capas modelada con quitar_solape (la capa otro gana el solape).
• Mensajes informativos por consola (print); sin logging formal todavía.
• Seguros implementados dentro de cada función: un helper compartido, _exigir_crs(gdf, nombre) (proyeccion.py, usado en proyeccion/geometria/raster), más chequeos en línea (campo inexistente, ruta inexistente, lista/capa vacía, factor que colisiona, máscara que no intersecta). Fallan con raise ValueError de mensaje claro.
• EPSG de trabajo típico: 32613 (UTM 13N, WGS84) para la zona de operación.

Pendientes / ideas para crecer

• Completar los tests de flujo hidrológico (pysheds) con un MDE pequeño de prueba: es lo único de la API que aún no tiene cobertura.
• validar_mde(mde, curvas, campo_elevacion): comparar el MDE interpolado contra las cotas originales de las curvas (percentiles/residuales) para medir la calidad. Quedó fuera de interpolar_mde; sería función aparte.