跳到主要内容

错误码参考

概述​

MipMapEngine SDK 使用标准化的错误码系统，帮助开发者快速定位和解决问题。错误码分为多个类别，包括重建接口错误、许可证错误、文件I/O错误和GPU错误等。

重建接口错误码 (ReconstructFull/ReconstructAT/Reconstruct3D)​

核心逻辑类​

错误码说明
0重建成功
1000重建失败，解析日志查看原因
1001用户取消
1002坐标系错误
1003空三结果为空
1004点云结果为空
1005网格结果为空
1006天底点图像不足，无法生成2D成果

许可证类​

错误码说明
2000许可证错误
2001枚举许可证失败
2002未找到匹配的许可证
2003许可证已过期
2004许可证不适用于此版本
2005许可证功能模块不匹配
2006超过许可证支持的最大图像数量

文件I/O类​

错误码说明
3000文件读写错误
3001JSON字段解析错误

计算设备驱动类​

错误码说明
4000GPU设备错误，检查GPU是否为NVIDIA且驱动版本是否满足要求

License Engine 错误码​

错误码说明
0成功
0x00000040网络错误
0x0000004A网络请求超时
0x05000004服务器未找到
0x13000051许可证需要在线激活
0x02000003连接失败，Virbox软件未安装或未联网
0x51005001查询授权码状态时发生异常
0x51005002授权码兑换请求时发生异常
0x51005003授权码不存在
0x51005004授权码许可证扣除失败
0x51005013无法绑定（许可证已过期）
0x51005014无法绑定（授权码同时绑定的设备数已达上限）
0x51005015无法绑定（授权码累计绑定的设备数已达上限）
0x51005018授权码终端解绑失败，请联系软件供应商
0x51005019服务器无法找到绑定记录，请联系软件供应商
0x51005021授权码许可证无法绑定，因为许可证被锁定，请联系软件供应商解决
0x51005025授权码不允许绑定
0x51005033暂时无法激活许可证，用户工具需升级到最新版本
0x51005034软件供应商已收回此设备的使用权，当前授权码无法再绑定，请联系软件供应商解决
0x5100612F授权码不存在，请确认授权码是否正确
0x51006130无效的硬件信息数据
0x51006134授权码许可证扣除失败，请联系软件供应商
0x5100502C无法解绑（未绑定）

错误诊断流程​

错误处理最佳实践​

1. 错误代码检查​

def check_reconstruction_error(error_code):
    if error_code == 0:
        return "Success"
    elif 1000 <= error_code <= 1006:
        return "Reconstruction logic error"
    elif 2000 <= error_code <= 2006:
        return "License error"
    elif 3000 <= error_code <= 3001:
        return "File I/O error"
    elif error_code == 4000:
        return "GPU device error"
    else:
        return f"Unknown error: {error_code}"

2. 错误日志分析​

def parse_error_from_log(log_file):
    import re
    
    error_patterns = {
        r'\[ERROR\] (\d+)': 'Error code',
        r'Memory allocation failed': 'Memory issue',
        r'CUDA error': 'GPU issue',
        r'File not found: (.+)': 'Missing file',
        r'License error: (\d+)': 'License issue'
    }
    
    with open(log_file, 'r', encoding='utf-8') as f:
        for line in f:
            for pattern, error_type in error_patterns.items():
                match = re.search(pattern, line)
                if match:
                    print(f"{error_type}: {match.group()}")

3. 错误恢复策略​

class ErrorHandler:
    def __init__(self):
        self.retry_counts = {}
        self.max_retries = 3
    
    def handle_error(self, error_code, task_name):
        if error_code == 0:
            return True
        
        # 可恢复的错误
        recoverable_errors = [
            1001,  # 用户取消
            3000,  # 文件读写错误
            4000   # GPU设备错误
        ]
        
        if error_code in recoverable_errors:
            retry_count = self.retry_counts.get(task_name, 0)
            
            if retry_count < self.max_retries:
                self.retry_counts[task_name] = retry_count + 1
                print(f"Retrying {task_name}, attempt {retry_count + 1}")
                
                # 执行恢复操作
                if error_code == 3000:  # 文件I/O错误
                    self.check_file_permissions()
                elif error_code == 4000:  # GPU错误
                    self.check_gpu_status()
                
                return False  # 重试
            
        # 许可证错误需要特殊处理
        if 2000 <= error_code <= 2006:
            self.handle_license_error(error_code)
        
        # 不可恢复的错误
        raise Exception(f"Unrecoverable error: {error_code}")
    
    def check_file_permissions(self):
        import os
        # 检查工作目录权限
        if not os.access("./", os.W_OK):
            raise Exception("No write permission in working directory")
    
    def check_gpu_status(self):
        import subprocess
        # 检查NVIDIA驱动
        result = subprocess.run(["nvidia-smi"], capture_output=True)
        if result.returncode != 0:
            raise Exception("NVIDIA driver not found")
    
    def handle_license_error(self, error_code):
        license_errors = {
            2000: "License error - check license status",
            2001: "Failed to enumerate license",
            2002: "No matching license found",
            2003: "License expired - renew license",
            2004: "License not valid for this version",
            2005: "License module mismatch",
            2006: "Exceeded maximum image count"
        }
        raise Exception(license_errors.get(error_code, f"License error {error_code}"))

4. 许可证错误处理​

def handle_license_engine_error(hex_code):
    """处理License Engine的16进制错误码"""
    
    license_errors = {
        0x00000040: "Network error - check internet connection",
        0x0000004A: "Network timeout - retry later",
        0x05000004: "Server not found - check server address",
        0x13000051: "License requires online activation",
        0x02000003: "Virbox not installed or offline",
        0x51005003: "Authorization code does not exist",
        0x51005013: "Cannot bind - license expired",
        0x51005014: "Cannot bind - concurrent device limit reached",
        0x51005015: "Cannot bind - total device limit reached",
        0x5100612F: "Invalid authorization code",
        0x5100502C: "Cannot unbind - not bound"
    }
    
    if hex_code in license_errors:
        return license_errors[hex_code]
    else:
        return f"Unknown license error: 0x{hex_code:08X}"

# 使用示例
try:
    result = subprocess.run(["license_engine.exe", "-bind", "YOUR-KEY"], 
                          capture_output=True)
    if result.returncode != 0:
        error_msg = handle_license_engine_error(result.returncode)
        print(f"License activation failed: {error_msg}")
except Exception as e:
    print(f"License engine error: {e}")

调试技巧​

1. 启用详细日志​

{
  "log_level": "DEBUG",
  "save_intermediate": true,
  "debug_output": true
}

2. 错误码映射​

ERROR_MESSAGES = {
    # 重建接口错误
    0: "Success",
    1000: "Reconstruction failed - check logs",
    1001: "User cancelled",
    1002: "Coordinate system error",
    1003: "Aerotriangulation result is empty",
    1004: "Point cloud result is empty",
    1005: "Mesh result is empty",
    1006: "Insufficient nadir images for 2D products",
    
    # 许可证错误
    2000: "License error",
    2001: "Failed to enumerate license",
    2002: "No matching license found",
    2003: "License expired",
    2004: "License not valid for this version",
    2005: "License module mismatch",
    2006: "Exceeded maximum image count",
    
    # 文件I/O错误
    3000: "File read/write error",
    3001: "JSON parsing error",
    
    # GPU错误
    4000: "GPU device error - check NVIDIA driver"
}

def get_error_message(error_code):
    return ERROR_MESSAGES.get(error_code, f"Unknown error: {error_code}")

3. 诊断脚本​

def diagnose_reconstruction_failure(working_dir):
    diagnostics = {
        'images_found': 0,
        'images_with_gps': 0,
        'average_overlap': 0,
        'memory_available': 0,
        'gpu_status': 'Unknown'
    }
    
    # 检查图像
    images = glob.glob(os.path.join(working_dir, "*.jpg"))
    diagnostics['images_found'] = len(images)
    
    # 检查 GPS
    for img in images:
        if has_gps_info(img):
            diagnostics['images_with_gps'] += 1
    
    # 检查系统资源
    diagnostics['memory_available'] = get_available_memory()
    diagnostics['gpu_status'] = check_gpu_status()
    
    # 生成报告
    print("Diagnostic Report:")
    for key, value in diagnostics.items():
        print(f"  {key}: {value}")
    
    # 建议
    if diagnostics['images_found'] < 5:
        print("⚠️ Need more images (minimum 5)")
    if diagnostics['images_with_gps'] == 0:
        print("⚠️ No GPS information found")
    if diagnostics['memory_available'] < 8:
        print("⚠️ Low memory, consider using lower resolution")

常见错误场景​

场景 1：许可证过期​

错误：2003 (License expired)
日志：License validation failed: expiry date 2023-12-31

解决方案：

  1. 联系供应商更新许可证
  2. 使用 license_engine.exe -bind 重新激活
  3. 检查系统时间是否正确

场景 2：GPU设备错误​

错误：4000 (GPU device error)
日志：CUDA error: no CUDA-capable device is detected

解决方案：

  1. 安装最新NVIDIA驱动（>=528.33）
  2. 确认GPU为NVIDIA显卡
  3. 运行 hardware_check.exe 验证环境

场景 3：空三结果为空​

错误：1003 (Aerotriangulation result is empty)
日志：Failed to find sufficient feature matches

解决方案：

  1. 检查图像质量和重叠度
  2. 确保图像数量 >= 5张
  3. 验证图像EXIF信息完整

场景 4：授权码无法绑定​

错误：0x51005014
日志：Cannot bind - concurrent device limit reached

解决方案：

  1. 在其他设备上解绑许可证
  2. 联系供应商增加设备数限制
  3. 使用 license_engine.exe -enum 查看当前绑定状态

预防措施​

  1. 预检查：运行前验证输入数据
  2. 渐进处理：先小数据测试，后大数据生产
  3. 资源监控：监控内存和GPU使用
  4. 备份恢复：定期保存中间结果

提示：遇到错误时，首先查看详细日志 log/log.txt，其中包含更多调试信息。