Manual de Uso - Script 1-alimentar_mongodb_openstreet.py

Descripción General

El script 1-alimentar_mongodb_openstreet.py es una herramienta diseñada para procesar imágenes desde un directorio específico y extraer metadatos relevantes, incluyendo información GPS y direcciones geocodificadas. Los datos procesados se almacenan en una base de datos MongoDB para facilitar la organización y búsqueda de imágenes.

El script incorpora las siguientes funcionalidades principales:

Escaneo recursivo de directorios en busca de archivos de imagen
Extracción de metadatos básicos (dimensiones, fecha de creación, etc.)
Procesamiento de coordenadas GPS desde metadatos EXIF
Geocodificación inversa usando la API de OpenStreetMap (Nominatim)
Almacenamiento en MongoDB usando hash SHA512 como identificador único

Requisitos del Sistema

Dependencias de Python

El script requiere las siguientes bibliotecas de Python:

pymongo
PIL (Python Imaging Library, más conocido como Pillow)
exifread
requests

Requisitos de Base de Datos

Instancia de MongoDB ejecutándose localmente (puerto 27017 por defecto)
Acceso de escritura a una base de datos llamada album_2
Colección imagenes (se creará automáticamente si no existe)

Requisitos del Sistema Operativo

Sistema operativo Linux/Windows/MacOS
Acceso de lectura al directorio que contiene las imágenes
Conexión a internet para geocodificación (opcional)

Instalación y Configuración

Instalación de Dependencias

Ejecute los siguientes comandos para instalar las bibliotecas requeridas:

pip install pymongo pillow exifread requests

Configuración del script

Antes de ejecutar el script, es necesario modificar las siguientes constantes en el archivo:

Configuración del Directorio a Escanear

DIRECTORY = '/mnt/local/datos/PROYCTO_ALBUM_SEMANTICO/IMAGENES'

Cambie esta ruta por el directorio que contiene las imágenes que desea procesar.

Configuración de MongoDB (Opcional)

MONGO_URI = "mongodb://localhost:27017"
DB_NAME = "album_2"
COLLECTION_NAME = "imagenes"

Modifique estos valores según su configuración de MongoDB si es necesario.

Advertencia: Asegúrese de que el directorio especificado existe y es accesible. El script verificará esta condición antes de iniciar el procesamiento.

Uso del Script

Ejecución Básica

Para ejecutar el script, navegue al directorio donde se encuentra el archivo y ejecute:

python 1-alimentar_mongodb_openstreet.py

Acceso al Script

El script completo está disponible en la carpeta codigo/ del proyecto:

📄 Descargar 1-alimentar_mongodb_openstreet.py

Progreso y Salidas

El script proporcionará información en tiempo real durante el procesamiento:

Archivos procesados
Imágenes con información GPS encontrada
Imágenes sin información GPS
Errores de procesamiento

Alto del Procesamiento

El script puede ser detenido en cualquier momento con Ctrl+C. Sin embargo, los datos ya procesados permanecerán en la base de datos.

Funcionalidades Detalladas

Procesamiento de Archivos

Extensiones soportadas: jpg, jpeg, png, tiff, bmp
Escaneo recursivo: Busca imágenes en subdirectorios
Control de duplicados: Usa hash SHA512 para evitar procesar archivos duplicados

Extracción de Metadatos

Dimensiones de la imagen (ancho y alto)
Fecha de modificación del archivo
Coordenadas GPS desde metadatos EXIF
Geocodificación inversa a direcciones legibles

Procesamiento GPS

Para imágenes con coordenadas GPS, el script:

Extrae las coordenadas en formato DMS de los metadatos EXIF
Convierte las coordenadas a formato decimal
Realiza geocodificación inversa usando Nominatim de OpenStreetMap
Almacena ambos las coordenadas numéricas y la dirección legible

Estructura de Datos en MongoDB

Cada documento en la colección imagenes contiene la siguiente estructura:

Campos Principales

Campo	Tipo	Descripción
`_id`	String	Hash SHA512 del archivo (identificador único)
`hash_sha512`	String	Mismo valor que _id para compatibilidad
`nombre_archivo`	String	Nombre del archivo de imagen
`ruta_completa`	String	Ruta completa al archivo
`ancho`	Integer	Ancho de la imagen en píxeles
`alto`	Integer	Alto de la imagen en píxeles

Campos de Fecha de Creación

La fecha de creación se separa en campos individuales para facilitar las consultas:

fecha_creacion_dia: Día del mes (01-31)
fecha_creacion_mes: Mes (01-12)
fecha_creacion_anio: Año (YYYY)
fecha_creacion_hora: Hora (00-23)
fecha_creacion_minuto: Minuto (00-59)

Campos de Geocodificación

Campo	Tipo	Descripción
`coordenadas`	Array	[latitud, longitud] en formato decimal (null si no GPS)
`direccion_os`	String	Dirección geocodificada (null si falla la geocodificación)

Campos de Procesamiento

La fecha de procesamiento se actualiza cada vez que se ejecuta el script:

fecha_procesamiento_dia: Día del procesamiento
fecha_procesamiento_mes: Mes del procesamiento
fecha_procesamiento_anio: Año del procesamiento
fecha_procesamiento_hora: Hora del procesamiento
fecha_procesamiento_minuto: Minuto del procesamiento

Solución de Problemas

Errores Comunes

Error: "El directorio no existe"

Causa: La ruta especificada en DIRECTORY no es válida.

Solución: Verifique la ruta del directorio y asegúrese de que existe y es accesible.

Error: "ConnectionError" o "ServerSelectionTimeoutError"

Causa: No se puede conectar a MongoDB.

Solución: Verifique que MongoDB esté ejecutándose y que la URI en MONGO_URI sea correcta.

Error de geocodificación

Causa: Problemas de conexión a internet o límites de la API.

Solución: El script manejará automáticamente este error, dejando el campo direccion_os como null.

Imágenes sin GPS

Causa: La imagen no contiene metadatos GPS en sus metadatos EXIF.

Solución: Esto es normal para muchas imágenes tomadas con dispositivos móviles más antiguos o sin GPS habilitado.

Optimizaciones de Rendimiento

Procesamiento masivo: Para grandes volúmenes de imágenes, considere dividir el procesamiento en lotes más pequeños
Control de duplicados: El script automáticamente evita reprocesar archivos idénticos gracias al hash SHA512
Geocodificación: El script respeta los límites de la API Nominatim (1 solicitud por segundo)

Consultas de Ejemplo en MongoDB

Buscar imágenes por fecha de creación

db.imagenes.find({
    "fecha_creacion_anio": "2023",
    "fecha_creacion_mes": "07"
})

Buscar imágenes con coordenadas GPS

db.imagenes.find({
    "coordenadas": { $ne: null }
})

Buscar imágenes por dirección aproximada

db.imagenes.find({
    "direccion_os": /Madrid/
})

Contar total de imágenes procesadas

db.imagenes.countDocuments()

Información de Versión y Soporte

Este script fue desarrollado para el proyecto Album Semántico y está optimizado para el procesamiento de imágenes con metadatos GPS.

Para soporte técnico o consultas adicionales, revise la documentación del proyecto o contacte al equipo de desarrollo.

Manual generado automáticamente - Última actualización: 31 de agosto de 2025