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 format
  • model-obj/ - OBJ format
  • 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:

🔧 Interactive Configuration Generator

Use the form below to generate your configuration file:

Basic Settings

Working Directory

GDAL Data Directory

Processing Parameters

Image TypeRGB ImageMultispectral ImageInfrared Image

Reconstruction AccuracyUltra High (Slow)High (Recommended)Standard (Fast)

Fast Mode

Coordinate System Settings

Coordinate System TypeLocalENULocalGeographic (WGS84)ProjectedECEF

EPSG Code

Output Formats

3D Model

OBJPLYOSGB3D TilesFBX

Point Cloud

LASPLYOSGBPNTSGS-PLYSplats

2D Orthophoto

GeoTIFFDOM TilesDSM TilesGenerate from 3D

Other Formats

Tie Point LAS

Advanced Options

Use Image Position Constraint

Minimum Available Memory (GB)

Output Block XML

Keep Undistorted Images

3D Tiles Options

Use Draco Compression

Texture FormatJPEGWebP (Higher Compression)

2D Tiles Options

Convert to GCJ02 Coordinate System (China Map)

Ground Control Points (GCP)

Use Ground Control Points

Output Coordinate System (Optional)

Custom 3D Coordinate System

Custom 2D Coordinate System

Generated Configuration File

Save the JSON below as 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"
    }
  ]
}

Validate and Run

1. First validate the configuration file:

task_json_check.exe -task_json task.json

2. After validation, run the reconstruction:

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.