Inicio Rápido

Esta guía te ayudará a comenzar rápidamente con el SDK de MipMapEngine. Proporcionamos scripts de ejemplo completos que te permiten ejecutar tu primera tarea de reconstrucción 3D en minutos.

📋 Prerrequisitos

Antes de comenzar, asegúrate de tener:

1. ✅ SDK instalado (ver Guía de Instalación)
2. ✅ Licencia activada

🚀 Experiencia Rápida: Usando Scripts de Ejemplo del SDK

El SDK proporciona ejemplos completos y scripts de ejecución con un clic en el directorio example:

example/
├── 1_reconstruct_full_basic.json     # Ejemplo de reconstrucción básica
├── 2_group_cameras.json              # Ejemplo de grupos de cámaras múltiples
├── 3_custom_image_pos.json           # Ejemplo de posición personalizada
├── sample-images/                    # Imágenes de muestra
├── Step1_Hardware_Check_EN.bat
├── Step2_License_Manager_EN.bat
├── Step3_Run_Example1_Basic_Drone_Reconstruction_EN.bat
├── Step4_Run_Example2_Multi_Camera_Groups_EN.bat
└── Step5_Custom_Image_Positions_EN.bat

Ejecuta tu Primera Reconstrucción

Step3_Run_Example1_Basic_Drone_Reconstruction_EN.bat

El script automáticamente:

1. Usará imágenes de muestra de sample-images
2. Creará el directorio de salida
3. Iniciará el proceso de reconstrucción 3D
4. Generará resultados en múltiples formatos

🎯 Detalles de los Ejemplos

Ejemplo 1: Reconstrucción Básica con Dron

Esta es la forma más simple de usar, adecuada para imágenes aéreas estándar de drones.

Características:

• ✅ Configuración mínima, lista para usar, adecuada para la mayoría de aplicaciones
• ✅ Compatible sin problemas con drones topográficos DJI principales

Archivo de Configuración (1_reconstruct_full_basic.json):

{
  "working_dir": "./output/reconstruct_full_basic",
  "gdal_folder": "../gdal_data",
  "input_image_type": 1,
  "resolution_level": 3,
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  "image_meta_data": [
    {
      "id": 1,
      "path": "../sample-images/DJI_20250507103417_0124_V.JPG"
    },
    {
      "id": 2,
      "path": "../sample-images/DJI_20250507103421_0125_V.JPG"
    }
    // ... más imágenes
  ],
  "generate_osgb": true,
  "generate_3d_tiles": true,
  "generate_las": true,
  "generate_obj": true,
  "generate_geotiff": true
}

Ejecución Manual:

reconstruct_full_engine.exe -reconstruct_type 0 -task_json 1_reconstruct_full_basic.json

Ejemplo 2: Reconstrucción con Grupos de Cámaras Múltiples

Adecuado para cámaras oblicuas multi-lente u operaciones colaborativas con múltiples drones.

Step4_Run_Example2_Multi_Camera_Groups_EN.bat

Escenarios de Aplicación:

• 🔸 Sistemas de cámaras oblicuas de cinco lentes
• 🔸 Operaciones colaborativas con múltiples drones
• 🔸 Combinaciones de cámaras con diferentes distancias focales
• 🔸 Recolección conjunta terrestre + aérea

Configuración Clave:

{
  "image_meta_data": [
    {
      "id": 1,
      "path": "image1.jpg",
      "group": "camera_1"  // Agrupación de cámaras
    },
    {
      "id": 2,
      "path": "image2.jpg",
      "group": "camera_2"  // Grupo de cámara diferente
    }
  ]
}

Ejemplo 3: Posiciones de Imagen Personalizadas

Adecuado para posicionamiento de alta precisión o escenarios sin GPS.

Step5_Custom_Image_Positions_EN.bat

Escenarios de Aplicación:

• 📍 Datos de posicionamiento de alta precisión PPK/RTK
• 📍 Ambientes interiores o con señal GPS deficiente
• 📍 Necesidad de personalizar pesos de precisión de posición

Configuración Clave:

{
  "image_meta_data": [
    {
      "id": 1,
      "path": "image.jpg",
      "meta_data": {
        "width": 4000,
        "height": 3000,
        "pos": [114.123456, 22.123456, 100.5],  // [Longitud, Latitud, Elevación]
        "pos_sigma": [0.03, 0.03, 0.06]  // [Precisión X, Precisión Y, Precisión Z] metros
      }
    }
  ]
}

Referencia de Precisión:

Método de Posicionamiento	Precisión X/Y (m)	Precisión Z (m)	Escenario de Aplicación
Solución Fija RTK/PPK	0.02-0.05	0.05-0.10	Topografía de alta precisión
GPS Regular	2-5	3-8	Aplicaciones generales

📊 Ver Resultados de Salida

Después de completar la reconstrucción, el directorio de salida contendrá:

• 📁 3D/ - Modelos 3D
  • model-b3dm/ - 3D Tiles (Cesium)
  • model-osgb/ - Formato OSGB
  • model-obj/ - Formato OBJ
  • point-las/ - Nube de puntos LAS
• 📁 2D/ - Productos 2D
  • dom_tiles/ - Mosaicos de ortofoto
  • dsm_tiles/ - Mosaicos del modelo digital de superficie
  • geotiffs/ - Formato GeoTIFF
• 📁 AT/ - Resultados AT
• 📁 report/ - Informe de calidad
• 📁 logs/log.txt - Registro de procesamiento

🛠️ Generador de Configuración Interactivo

Si no deseas escribir manualmente archivos de configuración JSON, puedes usar nuestra herramienta interactiva para generarlos rápidamente:

🔧 Generador interactivo de configuración

Utiliza el formulario a continuación para generar tu archivo de configuración:

Configuración básica

Directorio de trabajo

Directorio de datos GDAL

Parámetros de procesamiento

Tipo de imagenImagen RGBImagen multiespectralImagen infrarroja

Precisión de reconstrucciónUltra alta (lenta)Alta (recomendada)Estándar (rápida)

Modo rápido

Configuración del sistema de coordenadas

Tipo de sistema de coordenadasLocalENULocalGeográfico (WGS84)ProyectadoECEF

Código EPSG

Formatos de salida

Modelo 3D

OBJPLYOSGB3D TilesFBX

Nube de puntos

LASPLYOSGBPNTSGS-PLYSplats

Ortofoto 2D

GeoTIFFMosaicos DOMMosaicos DSMGenerar desde 3D

Otros formatos

Tie Point LAS

Opciones avanzadas

Usar restricción de posición de imagen

Memoria mínima disponible (GB)

XML de bloque de salida

Mantener imágenes sin distorsión

Opciones de teselas 3D

Usar compresión Draco

Formato de texturaJPEGWebP (mayor compresión)

Opciones de teselas 2D

Convertir al sistema de coordenadas GCJ02 (mapa de China)

Puntos de control en tierra (GCP)

Usar puntos de control en tierra

Sistema de coordenadas de salida (opcional)

Sistema de coordenadas 3D personalizado

Sistema de coordenadas 2D personalizado

Archivo de configuración generado

Guarda el siguiente JSON como task.json：

task.json

{
  "license_id": 9200,
  "working_dir": "C:/Projects/MyProject",
  "gdal_folder": "C:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 2,
  "coordinate_system": {
    "type": 2,
    "type_name": "Geographic",
    "label": "WGS 84",
    "epsg_code": 4326
  },
  "generate_obj": false,
  "generate_ply": false,
  "generate_osgb": true,
  "generate_3d_tiles": true,
  "generate_fbx": false,
  "generate_las": false,
  "generate_pc_ply": false,
  "generate_pc_osgb": false,
  "generate_pc_pnts": false,
  "generate_gs_ply": false,
  "generate_gs_splats": false,
  "generate_geotiff": true,
  "generate_tile_2D": true,
  "generate_2D_from_3D_model": false,
  "generate_dsm_tile": false,
  "fast_mode": false,
  "use_image_position_constraint": true,
  "min_avali_memory_size": 16,
  "output_block_change_xml": false,
  "output_tie_point_las": false,
  "keep_undistort_images": false,
  "use_draco_compression": true,
  "tex_image_type_3dtiles": 0,
  "use_gcj02": false,
  "image_meta_data": [
    {
      "id": 1,
      "path": "path/to/image1.jpg"
    },
    {
      "id": 2,
      "path": "path/to/image2.jpg"
    }
  ]
}

Validar y ejecutar

1. Primero valida el archivo de configuración:

task_json_check.exe -task_json task.json

2. Después de validar, ejecuta la reconstrucción:

reconstruct_full_engine.exe -reconstruct_type 0 -task_json task.json

🎯 Personaliza tu Primer Proyecto

Basándote en los ejemplos, crea tu propio archivo de configuración:

1. Copiar Configuración de Ejemplo

copy 1_reconstruct_full_basic.json my_project.json

2. Modificar Rutas de Imágenes

Edita my_project.json y cambia las rutas de imagen a tus imágenes:

{
  "image_meta_data": [
    {
      "id": 1,
      "path": "C:/MyImages/DJI_0001.JPG"
    },
    {
      "id": 2,
      "path": "C:/MyImages/DJI_0002.JPG"
    }
    // ... agrega todas las imágenes
  ]
}

3. Validar Archivo de Configuración

Antes de ejecutar la reconstrucción, usa la herramienta task_json_check.exe para validar el archivo de configuración:

task_json_check.exe my_project.json

Si hay errores en el archivo de configuración, la herramienta mostrará mensajes de error específicos. Los errores comunes incluyen:

• La ruta de la imagen no existe
• Error en los parámetros del sistema de coordenadas
• Campos obligatorios faltantes

4. Ejecutar Reconstrucción

Después de que el archivo de configuración pase la validación, ejecuta la tarea de reconstrucción:

reconstruct_full_engine.exe -reconstruct_type 0 -task_json my_project.json

📊 Monitorear Progreso

Salida de Consola

Muestra los pasos de procesamiento y el porcentaje de progreso.

Archivo de Registro

output/logs/log.txt contiene información detallada del procesamiento.

Script de Monitoreo de Progreso

import re
import time

def monitor_progress(log_file):
    with open(log_file, 'r') as f:
        while True:
            line = f.readline()
            if '[PROGRESS]' in line:
                match = re.search(r'\[PROGRESS\] (\d+)%', line)
                if match:
                    print(f"Progreso actual: {match.group(1)}%")
            time.sleep(1)

monitor_progress("output/logs/log.txt")

❓ Problemas Comunes

P: La reconstrucción falló con "Número insuficiente de imágenes"

R: Asegúrate de:

• Se proporcionan al menos 5 imágenes
• Suficiente superposición entre imágenes (recomendado >60%)
• Las imágenes contienen información GPS o proporcionas posiciones manualmente

P: ¿Cómo mejorar la calidad de reconstrucción?

R: Ajusta el nivel de resolución:

"resolution_level": 1  // Usar la máxima precisión

P: ¿Reconstrucción demasiado lenta?

R: Estrategias de optimización:

• Usa resolution_level: 3 para vista previa rápida
• Habilita fast_mode: true
• Considera usar procesamiento por bloques

💡 Consejos Prácticos

Generación de Configuración por Lotes

Para un gran número de imágenes, usa scripts para generar automáticamente configuraciones:

import json
import os
from glob import glob

def create_task_json(image_folder, output_file):
    images = glob(os.path.join(image_folder, "*.JPG"))
    
    task_config = {
        "working_dir": "./output/my_project",
        "gdal_folder": "../gdal_data",
        "input_image_type": 1,
        "resolution_level": 2,
        "coordinate_system": {
            "type": 2,
            "label": "WGS 84",
            "epsg_code": 4326
        },
        "image_meta_data": []
    }
    
    for idx, img_path in enumerate(images, 1):
        task_config["image_meta_data"].append({
            "id": idx,
            "path": img_path.replace("\\", "/")
        })
    
    with open(output_file, 'w', encoding='utf-8') as f:
        json.dump(task_config, f, indent=2, ensure_ascii=False)
    
    print(f"Archivo de configuración generado: {output_file}")
    print(f"Contiene {len(images)} imágenes")

# Uso
create_task_json("C:/MyImages", "batch_task.json")

🚀 Próximos Pasos

¡Felicitaciones! Has dominado el uso básico del SDK de MipMapEngine. A continuación puedes:

• 📚 Aprender Conceptos Básicos - Comprender profundamente los principios de reconstrucción 3D
• 🔧 Revisar Referencia API - Explorar más funciones avanzadas
• 💡 Repasar Conceptos Básicos - Comprender profundamente los principios de reconstrucción 3D
• 🎯 Probar procesamiento de escenas especiales - Escenarios desafiantes como textura débil, baja tasa de superposición

---

¿Necesitas ayuda? Consulta la guía de solución de problemas o contacta el soporte técnico.