Quick Start

This guide will help you quickly get started with MipMapEngine SDK. We provide complete example scripts that allow you to run your first 3D reconstruction task in minutes.

📋 Prerequisites

Before starting, please ensure you have:

1. ✅ Installed the SDK (see Installation Guide)
2. ✅ Activated your license

🚀 Quick Experience: Using SDK Example Scripts

The SDK provides complete examples and one-click run scripts in the example directory:

example/
├── 1_reconstruct_full_basic.json     # Basic reconstruction example
├── 2_group_cameras.json              # Multi-camera group example
├── 3_custom_image_pos.json           # Custom position example
├── sample-images/                    # Sample images
├── 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

Run Your First Reconstruction

Step3_Run_Example1_Basic_Drone_Reconstruction_EN.bat

The script will automatically:

1. Use sample images from sample-images
2. Create output directory
3. Start the 3D reconstruction process
4. Generate results in multiple formats

🎯 Example Details

Example 1: Basic Drone Reconstruction

This is the simplest way to use, suitable for standard drone aerial images.

Features:

• ✅ Minimal configuration, ready out-of-the-box, suitable for most applications
• ✅ Seamlessly compatible with mainstream DJI surveying drones

Configuration File (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"
    }
    // ... more images
  ],
  "generate_osgb": true,
  "generate_3d_tiles": true,
  "generate_las": true,
  "generate_obj": true,
  "generate_geotiff": true
}

Manual Run:

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

Example 2: Multi-Camera Group Reconstruction

Suitable for multi-lens oblique cameras or multi-drone collaborative operations.

Step4_Run_Example2_Multi_Camera_Groups_EN.bat

Application Scenarios:

• 🔸 Five-lens oblique camera systems
• 🔸 Multi-drone collaborative operations
• 🔸 Different focal length camera combinations
• 🔸 Ground + aerial joint collection

Key Configuration:

{
  "image_meta_data": [
    {
      "id": 1,
      "path": "image1.jpg",
      "group": "camera_1"  // Camera grouping
    },
    {
      "id": 2,
      "path": "image2.jpg",
      "group": "camera_2"  // Different camera group
    }
  ]
}

Example 3: Custom Image Positions

Suitable for high-precision positioning or GPS-less scenarios.

Step5_Custom_Image_Positions_EN.bat

Application Scenarios:

• 📍 PPK/RTK high-precision positioning data
• 📍 Indoor or poor GPS signal environments
• 📍 Need to customize position accuracy weights

Key Configuration:

{
  "image_meta_data": [
    {
      "id": 1,
      "path": "image.jpg",
      "meta_data": {
        "width": 4000,
        "height": 3000,
        "pos": [114.123456, 22.123456, 100.5],  // [Longitude, Latitude, Elevation]
        "pos_sigma": [0.03, 0.03, 0.06]  // [X accuracy, Y accuracy, Z accuracy] meters
      }
    }
  ]
}

Accuracy Reference:

Positioning Method	X/Y Accuracy (m)	Z Accuracy (m)	Application Scenario
RTK/PPK Fixed Solution	0.02-0.05	0.05-0.10	High-precision surveying
Regular GPS	2-5	3-8	General applications

📊 View Output Results

After reconstruction is complete, the output directory will contain:

• 📁 3D/ - 3D models
  • model-b3dm/ - 3D Tiles (Cesium)
  • model-osgb/ - OSGB 格式
  • model-obj/ - OBJ 格式
  • point-las/ - LAS point cloud
• 📁 2D/ - 2D products
  • dom_tiles/ - Orthophoto tiles
  • dsm_tiles/ - Digital surface model tiles
  • geotiffs/ - GeoTIFF format
• 📁 AT/ - AT results
• 📁 report/ - Quality report
• 📁 logs/log.txt - Processing log

🛠️ Interactive Configuration Generator

If you don't want to manually write JSON configuration files, you can use our interactive tool to quickly generate them:

🔧 交互式配置生成器

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

基本设置

工作目录

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

🎯 Customize Your First Project

Based on the examples, create your own configuration file:

1. Copy Example Configuration

copy 1_reconstruct_full_basic.json my_project.json

2. Modify Image Paths

Edit my_project.json and change the image paths to your images:

{
  "image_meta_data": [
    {
      "id": 1,
      "path": "C:/MyImages/DJI_0001.JPG"
    },
    {
      "id": 2,
      "path": "C:/MyImages/DJI_0002.JPG"
    }
    // ... add all images
  ]
}

3. Validate Configuration File

Before running reconstruction, use the task_json_check.exe tool to validate the configuration file:

task_json_check.exe my_project.json

If there are errors in the configuration file, the tool will display specific error messages. Common errors include:

• Image path does not exist
• Coordinate system parameter error
• Required fields missing

4. Run Reconstruction

After the configuration file passes validation, execute the reconstruction task:

reconstruct_full_engine.exe -reconstruct_type 0 -task_json my_project.json

📊 Monitor Progress

Console Output

Shows processing steps and progress percentage.

Log File

output/logs/log.txt contains detailed processing information.

Progress Monitoring Script

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"Current progress: {match.group(1)}%")
            time.sleep(1)

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

❓ Common Issues

Q: Reconstruction failed with "Insufficient number of images"

A: Ensure:

• At least 5 images are provided
• Sufficient overlap between images (recommended >60%)
• Images contain GPS information or manually provide positions

Q: How to improve reconstruction quality?

A: Adjust resolution level:

"resolution_level": 1  // Use highest precision

Q: Reconstruction too slow?

A: Optimization strategies:

• Use resolution_level: 3 for quick preview
• Enable fast_mode: true
• Consider using block processing

💡 Practical Tips

Batch Configuration Generation

For a large number of images, use scripts to automatically generate configurations:

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"Generated configuration file: {output_file}")
    print(f"Contains {len(images)} images")

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

🚀 Next Steps

Congratulations! You have mastered the basic usage of MipMapEngine SDK. Next you can:

• 📚 Learn Basic Concepts - Deeply understand 3D reconstruction principles
• 🔧 Check API Reference - Explore more advanced features
• 💡 Review Basic Concepts - Deeply understand 3D reconstruction principles
• 🎯 Try special scene processing - Challenging scenarios like weak texture, low overlap rate

---

Need help? Check the troubleshooting guide or contact technical support.