Troubleshooting

This page provides diagnosis and solutions for common issues when using MipMapEngine SDK.

🔍 Diagnostic Tools

When encountering issues, please first use the following diagnostic tools:

1. Configuration File Validation

task_json_check.exe -task_json your_config.json

2. Hardware Check

hardware_check.exe

3. License Status

license_manager.exe -info

📋 Common Errors and Solutions

Configuration File Errors

Error: JSON Parse Failed

Error Message:

[ERROR] JSON parse failed: expected ',' or '}' at line 45

Cause: JSON format error, usually missing comma or extra comma.

Solution:

1. Use JSON formatting tools to check syntax
2. Ensure there is no comma after the last element
3. Check for unclosed brackets or quotes

Example Fix:

// Wrong
{
  "image_meta_data": [
    {"id": 1, "path": "image1.jpg"},  // Last element should not have comma
  ]
}

// Correct
{
  "image_meta_data": [
    {"id": 1, "path": "image1.jpg"}
  ]
}

Error: Image File Not Found

Error Message:

[ERROR] Image file not found: C:/images/DJI_0001.JPG

Cause: Specified image path is incorrect or file does not exist.

Solution:

1. Check file path spelling
2. Confirm file actually exists
3. Use correct path separator (recommend using /)
4. Try using absolute path

Path Examples:

// Windows - Recommended
"path": "C:/Projects/Images/DJI_0001.JPG"

// Windows - Also works
"path": "C:\\Projects\\Images\\DJI_0001.JPG"

// Relative path
"path": "../images/DJI_0001.JPG"

Error: Parameter Out of Range

Error Message:

[ERROR] Invalid resolution_level: 5 (should be 1-3)

Cause: Parameter value is not within allowed range.

Solution: Check and correct parameter values:

• resolution_level: 1 (High), 2 (Medium), 3 (Low)
• input_image_type: 1 (RGB), 2 (Multispectral), 3 (Infrared)
• coordinate_system.type: 1 (Projected), 2 (Geographic), 3 (Geocentric)

Image Processing Errors

Error: Insufficient Images

Error Message:

[ERROR] Insufficient images for reconstruction. Minimum 5 images required, found 3.

Cause: Too few images to perform 3D reconstruction.

Solution:

• Provide at least 5 images
• Ensure sufficient overlap between images (recommended >60%)
• Check if any images were automatically filtered (see logs)

Error: No GPS Information

Error Message:

[WARNING] No GPS information found in image EXIF

Cause: No GPS information in image EXIF.

Solution:

1. Use custom POS data:

{
  "id": 1,
  "path": "image.jpg",
  "meta_data": {
    "pos": [114.123, 22.456, 100.5],
    "pos_sigma": [0.5, 0.5, 1.0]
  }
}

2. Reduce position constraints:

{
  "use_image_position_constraint": false
}

Multi-Camera Reconstruction Issues

Error: Camera Group Image Count Mismatch

Error Message:

[ERROR] Camera group image count mismatch: nadir(50), oblique_f(48)

Cause: Inconsistent image count across different camera groups.

Solution:

1. Check if any images are missing
2. Ensure multi-camera synchronous triggering works properly
3. Use task_json_check to verify grouping configuration

Correct Grouping Example:

{
  "image_meta_data": [
    // Each position should have images from all cameras
    {"id": 1, "path": "pos1/nadir.jpg", "group": "nadir"},
    {"id": 2, "path": "pos1/forward.jpg", "group": "forward"},
    {"id": 3, "path": "pos1/backward.jpg", "group": "backward"},
    // ... next position
    {"id": 4, "path": "pos2/nadir.jpg", "group": "nadir"},
    {"id": 5, "path": "pos2/forward.jpg", "group": "forward"},
    {"id": 6, "path": "pos2/backward.jpg", "group": "backward"}
  ]
}

Memory and Performance Issues

Error: Out of Memory

Error Message:

[ERROR] Out of memory. Required: 24GB, Available: 16GB

Cause: System memory insufficient to process current task.

Solution:

1. Lower precision level:

{
  "resolution_level": 3  // Use low precision
}

2. Limit memory usage:

{
  "min_avali_memory_size": 12.0  // Limit to 12GB
}

3. Reduce output formats:

{
  "generate_obj": true,
  "generate_osgb": false,  // Disable unnecessary outputs
  "generate_3d_tiles": false
}

Error: GPU Out of Memory

Error Message:

[ERROR] CUDA out of memory. Tried to allocate 2.00 GiB

Cause: Insufficient GPU memory.

Solution:

1. Close other programs using GPU
2. Lower resolution_level
3. Use block processing (for large projects)

License Issues

Error: Invalid License

Error Message:

[ERROR] Invalid license: License has expired

Solution:

1. Check license status: license_manager.exe -info
2. Confirm system time is correct
3. Reactivate license
4. Contact technical support to update license

Error: Virbox Service Not Running

Error Message:

[ERROR] Virbox service not running

Solution:

Windows：

# Start service
net start "Virbox Service"

# Check service status
sc query "Virbox Service"

Linux：

# Load driver
sudo modprobe virbox

# Check driver
lsmod | grep virbox

Output Result Issues

Issue: Model Has Holes

Possible Causes:

• Insufficient image overlap
• Texture-poor areas (water surface, glass, etc.)
• Poor image quality

Solution:

1. Increase image overlap to 80%
2. Use oblique photography to supplement side views
3. Avoid shooting in strong light or shadow conditions
4. Check and remove blurry images

Issue: Blurry Texture

Possible Causes:

• Original images are blurry
• Flight altitude too high
• Improper camera settings

Solution:

1. Use faster shutter speed (≥1/1000s)
2. Lower flight altitude
3. Use higher resolution camera
4. Ensure camera focus is correct

Issue: Coordinate Offset

Possible Causes:

• Incorrect coordinate system settings
• Poor GPS accuracy
• No control points used

Solution:

1. Check coordinate system configuration:

{
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  }
}

2. Add control points:

{
  "gcp_path": "gcps.txt",
  "gcp_coor_sys": {
    "type": 3,
    "epsg_code": 32650  // Ensure consistency with actual
  }
}

🛠️ Advanced Diagnostics

View Detailed Logs

Log file location: working_dir/log/log.txt

Find key information:

# View errors
grep -i "error" log.txt

# View warnings
grep -i "warning" log.txt

# View progress
grep "PROGRESS" log.txt

Performance Analysis

Find performance metrics in logs:

• [TIMING] - Time consumption for each stage
• [MEMORY] - Memory usage
• [GPU] - GPU utilization

Intermediate Results Check

Check intermediate results to locate issues:

1. AT results: working_dir/AT/mvs.xml
2. ROI range: working_dir/milestones/roi.json
3. Quality report: working_dir/report/report.json

📞 Getting Help

If the above solutions cannot solve your problem:

1. Collect diagnostic information:

   • Output from running task_json_check
   • Complete log.txt file
   • Configuration file (with sensitive data removed)
   • System information (hardware configuration)

2. Submit issue:

   • GitHub Issues: [Project Repository]
   • Technical support email: support@mipmap.com
   • Include the above diagnostic information

3. Check for updates:

   • Check if there's a new version
   • Review version changelog
   • Follow known issues list

---

Continuously updated. If you encounter unlisted issues, please contact technical support.