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:

🔧 交互式配置生成器

使用下面的表单生成您的配置文件：

基本设置

工作目录

GDAL 数据目录

处理参数

图像类型RGB 图像多光谱图像红外图像

重建精度超高精度（慢）高精度（推荐）标准精度（快）

快速模式

坐标系设置

坐标系类型LocalENULocalGeographic (WGS84)ProjectedECEF

EPSG 代码

输出格式

3D 模型

OBJPLYOSGB3D TilesFBX

点云

LASPLYOSGBPNTSGS-PLYSplats

2D 正射

GeoTIFFDOM瓦片DSM瓦片从3D生成

其他格式

连接点LAS

高级选项

使用图像位置约束

最小可用内存 (GB)

输出 Block XML

保留去畸变图像

3D Tiles 选项

使用 Draco 压缩

纹理格式JPEGWebP（更高压缩率）

2D 瓦片选项

转换为 GCJ02 坐标系（中国地图）

地面控制点 (GCP)

使用地面控制点

输出坐标系（可选）

自定义 3D 坐标系

自定义 2D 坐标系

生成的配置文件

将下面的 JSON 保存为 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"
    }
  ]
}

验证并运行

1. 首先验证配置文件：

task_json_check.exe -task_json task.json

2. 验证通过后运行重建：

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.