MiDaS Python API详解：run.py核心函数参数配置指南
【免费下载链接】MiDaS 
项目地址: https://gitcode.com/gh_mirrors/mid/MiDaS
1. 引言
深度估计（Depth Estimation）是计算机视觉领域的关键任务，它通过单张二维图像推断出三维空间中的深度信息。在自动驾驶、机器人导航、增强现实等领域，深度估计技术都发挥着至关重要的作用。然而，传统的深度估计方法往往需要复杂的硬件设备或大量的标注数据，这给开发者带来了不小的挑战。
MiDaS（Monocular Depth Estimation）作为一款领先的单目深度估计算法，彻底改变了这一局面。它仅需一张普通的RGB图像，就能生成精确的深度图，无需任何额外的传感器或标注数据。MiDaS不仅在学术研究中表现出色，在工业界也得到了广泛的应用。
本文将深入剖析MiDaS项目中核心文件run.py的Python API，详细解读其核心函数和参数配置。通过本文的学习，您将能够：
- 全面了解MiDaS的API结构和工作流程
- 掌握
run.py中关键函数的使用方法 - 熟练配置各种参数以适应不同的应用场景
- 解决实际使用中可能遇到的常见问题
2. run.py整体架构
run.py是MiDaS项目的入口文件，它提供了一个完整的命令行接口，用于运行深度估计算法。下面是run.py的整体架构流程图：
主要包含以下几个部分：
- 参数解析：解析命令行输入的各种参数
- 模型初始化：根据参数加载相应的模型和权重
- 数据处理：读取输入图像并进行预处理
- 推理计算：运行深度估计算法得到深度图
- 结果输出：将深度图保存到文件或显示在屏幕上
接下来，我们将详细介绍每个部分的核心函数和参数配置。
3. 核心函数详解
3.1 run()函数
run()函数是run.py的主函数，负责协调整个深度估计流程。其函数签名如下：
def run(input_path, output_path, model_path, model_type="dpt_beit_large_512", optimize=False, side=False, height=None, square=False, grayscale=False):
参数说明
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| input_path | str | None | 输入图像文件夹路径。如果未指定，则尝试从摄像头获取图像 |
| output_path | str | None | 输出图像文件夹路径。如果未指定，将只处理图像而不保存 |
| model_path | str | None | 预训练模型权重文件路径 |
| model_type | str | "dpt_beit_large_512" | 模型类型，可选值见下文详细说明 |
| optimize | bool | False | 是否在CUDA上使用半精度浮点优化 |
| side | bool | False | 是否在输出图像中并排显示RGB图像和深度图 |
| height | int | None | 推理时编码器输入图像的首选高度 |
| square | bool | False | 是否将图像调整为正方形分辨率 |
| grayscale | bool | False | 是否使用灰度颜色映射显示深度图 |
model_type参数可选值
MiDaS支持多种不同的模型类型，各有其特点和适用场景：
具体可选值包括：
- dpt_beit_large_512
- dpt_beit_large_384
- dpt_beit_base_384
- dpt_swin2_large_384
- dpt_swin2_base_384
- dpt_swin2_tiny_256
- dpt_swin_large_384
- dpt_next_vit_large_384
- dpt_levit_224
- dpt_large_384
- dpt_hybrid_384
- midas_v21_384
- midas_v21_small_256
- openvino_midas_v21_small_256
其中，以dpt_开头的是基于Vision Transformer的模型，通常具有更高的精度但计算量也更大；以midas_v21_开头的是原始的MiDaS模型；openvino_开头的是针对OpenVINO工具包优化的模型，适用于Intel硬件加速。
使用示例
# 基本用法
run(input_path="input_images", output_path="output_depth", model_type="dpt_beit_large_512")
# 使用半精度优化并保存RGB和深度图并排显示
run(input_path="input", output_path="output", model_type="dpt_swin2_tiny_256", optimize=True, side=True)
# 指定输入图像高度和灰度显示
run(input_path="images", output_path="results", model_type="midas_v21_small_256", height=384, grayscale=True)
3.2 process()函数
process()函数负责执行实际的深度估计推理。其函数签名如下：
def process(device, model, model_type, image, input_size, target_size, optimize, use_camera):
参数说明
| 参数名 | 类型 | 描述 |
|---|---|---|
| device | torch.device | 用于推理的设备（CPU或GPU） |
| model | torch.nn.Module | 加载好的MiDaS模型 |
| model_type | str | 模型类型 |
| image | numpy.ndarray | 输入图像数据 |
| input_size | tuple | 神经网络输入的大小（宽度，高度） |
| target_size | tuple | 神经网络输出的大小（宽度，高度） |
| optimize | bool | 是否使用半精度优化 |
| use_camera | bool | 是否使用摄像头输入 |
功能流程
该函数根据模型类型（普通PyTorch模型或OpenVINO优化模型）执行不同的推理流程，但最终都返回相同格式的深度图。
3.3 create_side_by_side()函数
create_side_by_side()函数用于将原始RGB图像和深度图并排显示。其函数签名如下：
def create_side_by_side(image, depth, grayscale):
参数说明
| 参数名 | 类型 | 描述 |
|---|---|---|
| image | numpy.ndarray | RGB原始图像 |
| depth | numpy.ndarray | 深度图数据 |
| grayscale | bool | 是否使用灰度颜色映射 |
该函数会对深度图进行归一化处理，并应用颜色映射（默认使用INFERNO颜色映射，如指定grayscale=True则使用灰度映射），然后将原始图像和处理后的深度图水平拼接在一起。
4. 命令行参数配置
run.py使用argparse模块解析命令行参数。以下是所有可用命令行参数的详细说明：
4.1 基本参数
| 参数 | 缩写 | 类型 | 默认值 | 描述 |
|---|---|---|---|---|
| --input_path | -i | str | None | 输入图像文件夹路径 |
| --output_path | -o | str | None | 输出图像文件夹路径 |
| --model_weights | -m | str | None | 模型权重文件路径 |
| --model_type | -t | str | dpt_beit_large_512 | 模型类型 |
4.2 高级参数
| 参数 | 缩写 | 类型 | 默认值 | 描述 |
|---|---|---|---|---|
| --side | -s | bool | False | 是否将RGB图像和深度图并排显示 |
| --optimize | 无 | bool | False | 是否使用半精度优化 |
| --height | 无 | int | None | 推理时编码器输入图像的首选高度 |
| --square | 无 | bool | False | 是否将图像调整为正方形分辨率 |
| --grayscale | 无 | bool | False | 是否使用灰度颜色映射 |
4.3 常用命令示例
4.3.1 基本用法
python run.py -i input_images -o output_depth -t dpt_beit_large_512
这个命令将处理input_images文件夹中的所有图像，使用默认的dpt_beit_large_512模型，并将结果保存到output_depth文件夹中。
4.3.2 使用摄像头实时检测
python run.py -o camera_output -t midas_v21_small_256
这个命令将从摄像头获取实时图像，使用轻量级的midas_v21_small_256模型进行深度估计，并将结果保存到camera_output文件夹中。
4.3.3 使用半精度优化加速推理
python run.py -i input -o output -t dpt_swin2_base_384 --optimize
这个命令使用dpt_swin2_base_384模型，并启用半精度优化，可以在保持精度的同时加速推理过程。
4.3.4 自定义输入图像高度
python run.py -i images -o results -t dpt_levit_224 --height 480
这个命令将输入图像调整为高度为480像素（宽度会按比例调整）后再进行推理。
5. 模型类型选择指南
MiDaS提供了多种不同的模型类型，选择合适的模型对于平衡精度和性能至关重要。以下是一些常见模型类型的比较：
5.1 模型性能比较
| 模型类型 | 输入分辨率 | 参数数量 | 推理速度 (FPS) | 精度 (REL) | 适用场景 |
|---|---|---|---|---|---|
| midas_v21_small_256 | 256x256 | 4.8M | 30+ | 0.11 | 移动设备，实时应用 |
| dpt_levit_224 | 224x224 | 21.5M | 15-20 | 0.08 | 中等精度要求，实时性要求高 |
| dpt_swin2_tiny_256 | 256x256 | 28M | 10-15 | 0.07 | 平衡精度和速度 |
| dpt_swin2_base_384 | 384x384 | 87M | 5-10 | 0.05 | 高精度要求，对速度要求不高 |
| dpt_beit_large_512 | 512x512 | 302M | 2-5 | 0.04 | 最高精度要求，离线处理 |
5.2 选择建议
-
实时应用：优先选择
midas_v21_small_256或dpt_levit_224，它们体积小、速度快，适合在移动设备或嵌入式系统上运行。 -
平衡精度和速度：
dpt_swin2_tiny_256或dpt_swin2_base_384是不错的选择，它们在保持较高精度的同时，仍能提供可接受的推理速度。 -
高精度要求：如果对深度估计精度有极高要求，且可以接受较慢的推理速度，
dpt_beit_large_512是最佳选择。 -
Intel硬件：如果在Intel CPU或GPU上运行，可以考虑使用
openvino_midas_v21_small_256模型，它针对OpenVINO工具包进行了优化。
6. 高级参数调优
6.1 输入分辨率调整
--height参数允许您调整输入图像的高度，这直接影响推理速度和内存占用：
# 使用较低分辨率加速推理
python run.py -i input -o output -t dpt_swin2_base_384 --height 256
# 使用较高分辨率提高精度
python run.py -i input -o output -t dpt_swin2_base_384 --height 512
注意：实际输入分辨率会自动调整为32的倍数，以满足模型要求。
6.2 半精度优化
--optimize参数启用半精度浮点推理，可以显著减少内存占用并提高推理速度，尤其是在支持FP16的GPU上：
python run.py -i input -o output -t dpt_beit_large_512 --optimize
注意：某些模型（如Swin系列）在半精度模式下可能会产生非有限的深度值，使用时需要谨慎。
6.3 输出格式控制
通过--side和--grayscale参数，您可以控制输出图像的格式：
# 并排显示RGB图像和彩色深度图
python run.py -i input -o output -t dpt_swin2_base_384 --side
# 保存灰度深度图
python run.py -i input -o output -t dpt_swin2_base_384 --grayscale
7. 常见问题解决
7.1 内存不足问题
如果遇到内存不足错误，可以尝试以下解决方案：
- 使用更小的模型（如
midas_v21_small_256） - 降低输入图像分辨率（使用
--height参数） - 启用半精度优化（
--optimize参数） - 在CPU上运行（虽然速度较慢，但内存限制通常更宽松）
7.2 推理速度慢
如果推理速度太慢，可以尝试以下优化：
7.3 深度图质量不佳
如果深度图质量不理想，可以尝试以下改进方法：
- 使用更大的模型（如
dpt_beit_large_512） - 提高输入图像分辨率
- 确保光照条件良好（MiDaS在低光环境下性能可能下降）
- 尝试不同的模型类型，某些模型可能对特定场景更敏感
8. 总结与展望
本文详细介绍了MiDaS项目中run.py文件的核心函数和参数配置。通过学习，您应该已经掌握了如何使用MiDaS API进行深度估计，以及如何根据具体需求调整各种参数。
MiDaS作为一款先进的单目深度估计算法，在保持高精度的同时，也提供了灵活的参数配置选项，能够适应从移动设备到高性能服务器的各种应用场景。随着计算机视觉技术的不断发展，我们可以期待MiDaS在未来会有更高的精度和更快的推理速度。
最后，鼓励您尝试不同的模型类型和参数配置，以找到最适合您应用场景的解决方案。如有任何问题或建议，欢迎参与MiDaS项目的开源社区讨论。
9. 附录：完整参数列表
9.1 run()函数完整参数
def run(
input_path, # 输入图像文件夹路径
output_path, # 输出图像文件夹路径
model_path, # 模型权重文件路径
model_type="dpt_beit_large_512", # 模型类型
optimize=False, # 是否使用半精度优化
side=False, # 是否并排显示RGB和深度图
height=None, # 输入图像高度
square=False, # 是否调整为正方形分辨率
grayscale=False # 是否使用灰度颜色映射
):
9.2 命令行参数完整列表
usage: run.py [-h] [-i INPUT_PATH] [-o OUTPUT_PATH] [-m MODEL_WEIGHTS]
[-t MODEL_TYPE] [-s] [--optimize] [--height HEIGHT] [--square]
[--grayscale]
optional arguments:
-h, --help show this help message and exit
-i INPUT_PATH, --input_path INPUT_PATH
Folder with input images (if no input path is
specified, images are tried to be grabbed from camera)
-o OUTPUT_PATH, --output_path OUTPUT_PATH
Folder for output images
-m MODEL_WEIGHTS, --model_weights MODEL_WEIGHTS
Path to the trained weights of model
-t MODEL_TYPE, --model_type MODEL_TYPE
Model type: dpt_beit_large_512, dpt_beit_large_384,
dpt_beit_base_384, dpt_swin2_large_384,
dpt_swin2_base_384, dpt_swin2_tiny_256,
dpt_swin_large_384, dpt_next_vit_large_384,
dpt_levit_224, dpt_large_384, dpt_hybrid_384,
midas_v21_384, midas_v21_small_256 or
openvino_midas_v21_small_256
-s, --side Output images contain RGB and depth images side by
side
--optimize Use half-float optimization
--height HEIGHT Preferred height of images feed into the encoder
during inference. Note that the preferred height may
differ from the actual height, because an alignment
to multiples of 32 takes place. Many models support
only the height chosen during training, which is used
automatically if this parameter is not set.
--square Option to resize images to a square resolution by
changing their widths when images are fed into the
encoder during inference. If this parameter is not
set, the aspect ratio of images is tried to be
preserved if supported by the model.
--grayscale Use a grayscale colormap instead of the inferno one.
Although the inferno colormap, which is used by
default, is better for visibility, it does not allow
storing 16-bit depth values in PNGs but only 8-bit
ones due to the precision limitation of this colormap.
【免费下载链接】MiDaS 项目地址: https://gitcode.com/gh_mirrors/mid/MiDaS
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
