📚 课程目录第2章 Tuning工具入门

2. Tuning工具入门：Qualcomm Camera Tuning Tool

做高通平台影像调试，第一关就是跟Tuning Tool打交道。很多新人拿到工具第一反应是「这界面也太复杂了吧？」——别急，我刚开始也是这样。今天我们就从零开始，把QCTT（Qualcomm Camera Tuning Tool）的安装、界面、操作流程捋一遍。

2.1 工具安装与环境准备

QCTT不是随便装个exe就能用的。它依赖Python环境、ADB驱动、还有高通自己的底层库。我见过不少同事卡在安装这一步，折腾半天连不上设备。

组件	版本要求	备注
Python	3.6 ~ 3.8	3.9以上可能报依赖错误
ADB	1.0.41+	建议用高通SDK自带版本
QCTT安装包	根据芯片平台选择	SM8250/SM8350等版本不同
USB驱动	高通USB驱动	否则设备无法识别

注意：安装路径不要带中文或空格。我之前有个项目，同事把工具装在了「Program Files (x86)」下面，结果Python脚本路径解析报错，折腾了两天才发现是空格的问题。

安装步骤其实很简单：

先装Python，记得勾选「Add Python to PATH」
解压QCTT包，运行 setup.bat
安装高通USB驱动，重启电脑
手机打开开发者模式，开启USB调试

装好之后，在命令行敲 qctt --version，能看到版本号就说明成了。

2.2 界面布局：别被吓到

第一次打开QCTT，你会看到左边一大片树形结构，右边是参数面板，底部还有日志输出。说实话，我第一次打开也懵了——这玩意儿比VS Code还复杂。

但说白了，核心就四个区域：

Module Tree（模块树）：左边，按ISP Pipeline排列，从Sensor到ISP到Stats，一层层展开
Parameter Panel（参数面板）：右边，选中某个模块后，这里显示可调参数
Preview Window（预览窗口）：中间，实时显示图像效果
Log Console（日志控制台）：底部，打印调试信息和错误

小技巧：我个人习惯把Module Tree和Log Console固定，参数面板用快捷键Ctrl+E快速切换。这样屏幕利用率高很多。

你想想看，整个ISP Pipeline就像一条流水线：Sensor采集原始数据 → ISP做各种处理 → 最后输出YUV或JPEG。QCTT的模块树就是这条流水线的「控制面板」，每个节点对应一个处理环节。

2.3 连接设备：最容易出坑的环节

连接设备听起来简单——插上USB，点个连接按钮就行了？没那么简单。我遇到过的情况：

ADB能识别，但QCTT连不上
连上了，但抓图报错
抓到了图，但Raw图是黑的

标准连接流程：

手机连电脑，确认ADB devices能看到设备
打开QCTT，点击 Connect 按钮
选择对应的Camera ID（一般是后摄0，前摄1）
等待状态栏变成绿色「Connected」

  核心要点：连接成功后，QCTT会从手机端拉取当前的tuning参数。如果拉取失败，检查手机端的CHI（Camera Hardware Interface）服务是否正常运行。我曾经遇到过手机系统OTA升级后，CHI服务被禁用，折腾了半天才发现。

2.4 抓取Raw图：调试的第一步

Raw图是调试的「原材料」。没有Raw图，后面所有效果优化都是空中楼阁。

抓Raw图的步骤：

连接设备后，在Module Tree选中 Sensor 节点
在参数面板找到 Raw Capture 选项
设置输出格式（一般是10-bit或12-bit Raw）
点击 Capture 按钮
选择保存路径，等待抓取完成

抓到的Raw图通常以 .raw 或 .dng 格式保存。我个人建议用DNG格式，因为它包含了元数据（ISO、曝光时间、增益等），后续分析方便很多。

避坑指南：我曾经在抓Raw图时发现图像全是黑的，检查了半天发现是曝光时间设置成了0。还有一次，Raw图有条纹，结果是Sensor的PLL配置不对。所以抓图之前，先确认Sensor的初始化参数是否正确。

2.5 知识结构总览

下面这张图把QCTT的核心流程串起来了，你可以对照着看：

2.6 实操：第一次抓图

理论说完了，咱们来点实际的。假设你已经装好了QCTT，连上了设备，现在要抓一张Raw图。

操作步骤：

在Module Tree找到 Sensor → sensor0
双击打开参数面板，找到 Raw Format，选 MIPI_RAW10
设置 Exposure Time 为 30ms（室内场景够用）
设置 Analog Gain 为 1.0x（避免增益噪声）
点击工具栏的 Capture 按钮（相机图标）
在弹出的对话框里选 DNG 格式，保存到桌面

经验之谈：第一次抓图建议用DNG格式，因为可以用Adobe Camera Raw或RawDigger打开查看。如果抓出来是纯黑或纯白，先检查曝光时间和增益。我有个习惯——抓图之前先看一眼预览窗口，确认画面正常再点Capture。

抓到的Raw图可以用 rawdump 工具验证：

# 查看Raw图基本信息
rawdump --info capture_001.dng

# 输出示例：
# Width: 4032
# Height: 3024
# Bit Depth: 10
# Bayer Pattern: RGGB
# Black Level: 64
# White Level: 1023

看到这些信息，说明Raw图抓成功了。如果报错，八成是格式不匹配或者Sensor没初始化好。

2.7 常见问题与避坑

我把这些年遇到的高频问题整理了一下：

问题	原因	解决方法
ADB识别不到设备	驱动没装好或USB线不行	换原装线，重装高通USB驱动
QCTT连上又断开	CHI服务异常或权限不足	重启手机，检查adb root权限
抓图报错	Sensor配置与QCTT不匹配	确认sensor ID和分辨率设置
Raw图全黑	曝光时间或增益为0	检查Exposure Time和Gain参数
Raw图有条纹	Sensor PLL或时钟配置错误	检查Sensor初始化序列

避坑指南：我曾经在一个项目里，连续三天抓不到正常的Raw图，最后发现是手机端的CHI服务版本和QCTT不匹配。高通每个平台（比如SM8250和SM8350）的CHI接口有差异，一定要用对应版本的QCTT。所以，装工具之前先确认芯片平台，别装错了。

嗯，到这里QCTT的入门内容就差不多了。工具这东西，光看没用，得动手。建议你今晚就装好环境，抓一张Raw图试试。哪怕抓出来是黑的，也是进步——至少你知道了问题在哪。