YOLO标注转MATLAB结构体：跨框架数据格式迁移实战

简介本资源是一套面向Python数据处理与计算机视觉预处理场景的轻量级工具脚本包适用于具备基础Python编程能力的学习者及图像标注数据处理需求的开发者。压缩包共含2个核心Python脚本总计1KB其中convert_txt_mat.py实现文本标注数据到MATLAB兼容.mat格式的批量转换便于跨平台如MATLAB、Python科学计算环境协同使用change_xml_wh.py则专用于批量修改XML标注文件中的 与 字段值常见于图像尺寸归一化、目标检测数据集适配等任务。两个脚本均基于Python标准库xml.etree.ElementTree与scipy.io模块开发涵盖文件I/O、XML解析、MAT文件读写等实用知识点代码简洁、参数明确可直接命令行调用并集成至自动化预处理流水线。目前已有259人学习下载是快速上手结构化标注数据格式转换的即用型实践素材。1. 这不是通用工具包而是图像标注流水线里卡点的「缝合型脚本」你手头有一批 YOLO 格式的.txt标注文件每行class_id x_center y_center width height归一化值还有一套旧版标注系统导出的 XML含width640/widthheight480/height但下游模型训练 pipeline 强制要求输入.mat文件——不是 MATLAB GUI 打开就行的那种而是结构体字段名固定、嵌套层级明确、能被scipy.io.loadmat()直接[annotations][0,0][boxes]索引出来的格式。这时候tools.zip里的两个脚本就不是“可有可无的辅助工具”而是绕过 MATLAB 许可证、避免重写整个标注平台的最小可行解。它们不封装成库、不提供 CLI 参数校验、不处理异常路径但每行代码都对应一个真实场景convert_txt_mat.py把文本坐标转成 MATLAB 兼容的 double 数组并存为结构体change_xml_wh.py不是简单替换字符串而是精准定位size下的width和height子节点防止误改objectnamewidth/name这类干扰项。适合正在做跨框架数据迁移的 CV 工程师、需要快速对齐 legacy 数据格式的算法实习生以及被甲方临时要求“把标注从 XML 转成 MAT”的外包开发者。2.convert_txt_mat.py从纯文本到 MATLAB 结构体的三步映射2.1 为什么不用numpy.savetxt()或直接写.npyMATLAB 的.matv7.3 格式HDF5和 v7 格式二进制在 Python 中必须通过scipy.io.savemat()写入否则 MATLAB 读取时会报Invalid file identifier或Unrecognized variable type。关键在于.mat文件本质是 MATLAB 变量的序列化容器它要求数据必须组织成dict且 key 必须是合法的 MATLAB 变量名不能含-、空格、数字开头value 必须是numpy.ndarray、numpy.float64、numpy.int32或嵌套的dict/list后者会被转为 cell。例如YOLO 的labels.txt每行0 0.123 0.456 0.234 0.567若直接用np.loadtxt()读成(N,5)数组存入.mat后 MATLAB 里会变成data [N×5 double]但下游脚本可能硬编码要求data.annotations(1).boxes这种结构。因此convert_txt_mat.py的核心逻辑不是“保存数值”而是“构造 MATLAB 期望的嵌套结构”。2.2 实际代码解析与可复现步骤# convert_txt_mat.py import numpy as np import scipy.io as sio import os import sys def txt_to_mat(txt_path, mat_path, image_nameNone): # 1. 读取 txt 并按行分割过滤空行 with open(txt_path, r) as f: lines [line.strip() for line in f.readlines() if line.strip()] # 2. 解析每行class_id, x_c, y_c, w, h → 转为 float64 boxes [] for line in lines: parts line.split() if len(parts) ! 5: continue # 跳过格式错误行 cls_id, xc, yc, w, h map(float, parts) # 还原为像素坐标假设原始图宽高已知此处需外部传入 # 实际项目中应从同名 .jpg 获取尺寸或从 config.json 读取 # 此处简化假设原始图 640x480归一化值反推 orig_w, orig_h 640, 480 x1 int((xc - w/2) * orig_w) y1 int((yc - h/2) * orig_h) x2 int((xc w/2) * orig_w) y2 int((yc h/2) * orig_h) boxes.append([x1, y1, x2, y2, int(cls_id)]) # 3. 构造 MATLAB 结构体必须是 dictkey 为合法变量名 # 注意MATLAB 中 struct 字段名区分大小写且不能是保留字 data { image_name: image_name or os.path.basename(txt_path).replace(.txt, ), boxes: np.array(boxes, dtypenp.float64), # 必须是 float64MATLAB 默认 double num_boxes: len(boxes), format: yolo_normalized_to_pixel } # 4. 写入 .mat —— 关键参数do_compressionTrue 减小体积appendmatFalse 强制 v7 格式 sio.savemat(mat_path, data, do_compressionTrue, appendmatFalse) if __name__ __main__: if len(sys.argv) 3: print(Usage: python convert_txt_mat.py input_txt output_mat [image_name]) sys.exit(1) txt_file sys.argv[1] mat_file sys.argv[2] img_name sys.argv[3] if len(sys.argv) 3 else None txt_to_mat(txt_file, mat_file, img_name)提示appendmatFalse是关键。若设为True默认savemat()会自动在output_mat后缀加.mat导致生成output_mat.mat.mat。而do_compressionTrue对含大量零值的boxes数组压缩率可达 60%避免.mat文件比原始.txt大 3 倍。2.2.1 参数说明与修改指南参数作用修改建议orig_w,orig_h将归一化坐标转为像素坐标的基础尺寸必须根据实际图像修改。若标注文件来自不同分辨率图像需提前用PIL.Image.open()读取对应.jpg获取尺寸而非硬编码dtypenp.float64MATLABdouble类型对应 Pythonfloat64若下游要求整数坐标如 OpenCV ROI改为np.int32但需确保savemat()支持v7 格式支持int32image_name写入.mat的image_name字段若需批量处理可在循环中用os.path.splitext(os.path.basename(txt_path))[0]自动提取2.2.2 验证生成的.mat是否可用在 MATLAB 中执行data load(output.mat); whos data % 查看变量类型应显示 data: 1x1 struct disp(data.image_name) % 输出文件名 size(data.boxes) % 应为 N×5且 class_id 在第5列在 Python 中验证import scipy.io as sio mat sio.loadmat(output.mat) print(mat.keys()) # 应含 image_name, boxes, num_boxes, __header__, __version__ print(mat[boxes].dtype) # 必须是 float64 print(mat[boxes].shape) # (N, 5)2.3 常见失败场景与修复错误ValueError: Unsupported type class str原因datadict 中混入了str类型如image_nameabc.jpg是 str但savemat()要求所有非数值字段也必须是np.ndarray。修复将image_name包装为np.array([image_name], dtypeobject)或改用np.string_(image_name)。错误MATLAB 加载后boxes为空矩阵原因boxes列表为空np.array([])生成 shape(0,)MATLAB 解析为 1×0 向量而非 0×5 矩阵。修复添加判断if not boxes: boxes np.zeros((0,5))。错误UnicodeEncodeError: latin-1 codec cant encode character原因txt文件含中文路径或 UTF-8 BOM。修复open(txt_path, r, encodingutf-8-sig)。3.change_xml_wh.py精准定位 XML 元素的 ElementTree 实战3.1 为什么不用正则替换width.*?/widthXML 是树状结构正则表达式无法处理嵌套、命名空间、属性值中的符号如sizewidth unitpx640/width/size。change_xml_wh.py使用xml.etree.ElementTree的核心优势在于它构建内存 DOM 树允许通过 XPath 定位精确节点并保证修改后 XML 格式严格合规缩进、闭合标签、转义字符。例如某 XML 中存在objectnamewidth/namebndboxxmin10/xmin/bndbox/object正则width.*?会错误匹配namewidth/name而ElementTree.find(.//width)仅匹配顶层width标签。3.2 代码实现与关键 XPath 语法# change_xml_wh.py import xml.etree.ElementTree as ET import sys import os def update_xml_size(xml_path, new_width, new_height, output_pathNone): # 1. 解析 XML获取根节点 tree ET.parse(xml_path) root tree.getroot() # 2. 定位 size 下的 width 和 height —— 使用 XPath .//size/width 确保层级 width_elem root.find(.//size/width) height_elem root.find(.//size/height) # 3. 检查元素是否存在防御性编程 if width_elem is None or height_elem is None: raise ValueError(fXML {xml_path} missing width or height under size) # 4. 更新文本内容注意text 是字符串需显式转换 width_elem.text str(int(new_width)) height_elem.text str(int(new_height)) # 5. 写入新文件 —— 关键preserve_whitespaceFalse 重排缩进但需手动添加换行 if output_path is None: output_path xml_path # 修复缩进ElementTree 默认无缩进影响可读性 def indent(elem, level0): i \n level * if len(elem): if not elem.text or not elem.text.strip(): elem.text i if not elem.tail or not elem.tail.strip(): elem.tail i for elem in elem: indent(elem, level 1) if not elem.tail or not elem.tail.strip(): elem.tail i else: if level and (not elem.tail or not elem.tail.strip()): elem.tail i indent(root) tree.write(output_path, encodingutf-8, xml_declarationTrue) if __name__ __main__: if len(sys.argv) 4: print(Usage: python change_xml_wh.py input_xml new_width new_height [output_xml]) sys.exit(1) xml_file sys.argv[1] try: w int(sys.argv[2]) h int(sys.argv[3]) except ValueError: print(Width and height must be integers) sys.exit(1) output_file sys.argv[4] if len(sys.argv) 4 else None update_xml_size(xml_file, w, h, output_file)3.2.1 XPath 表达式详解XPath匹配目标为什么安全.//size/width任意深度的size下直接子节点width//表示任意后代/表示直接子节点避免匹配objectwidth.../width/object.//size/*[self::width or self::height]size下所有width或height元素更健壮但本脚本只需两个元素简洁优先.//size/width[unitpx]带unitpx属性的width若 XML 有多种单位可精准筛选注意root.find()返回None时不会报错必须显式检查。这是 ElementTree 的设计哲学——“找不到就返回 None由用户决定如何处理”而非抛异常。3.2.2 批量处理 XML 的 Shell 脚本模板#!/bin/bash # batch_update_xml.sh XML_DIR./annotations NEW_W1920 NEW_H1080 for xml_file in $XML_DIR/*.xml; do if [ -f $xml_file ]; then echo Updating $xml_file to ${NEW_W}x${NEW_H} python change_xml_wh.py $xml_file $NEW_W $NEW_H fi done3.3 修复常见 XML 解析陷阱陷阱XML 声明?xml version1.0 encodingUTF-8?导致ParseError原因ET.parse()默认使用系统编码若文件声明为 UTF-8 但实际含 BOM或声明为 GBK 但文件是 UTF-8。修复先用chardet检测编码再指定open(xml_path, rb)读取import chardet with open(xml_path, rb) as f: raw f.read() encoding chardet.detect(raw)[encoding] root ET.fromstring(raw.decode(encoding))陷阱修改后 XML 在浏览器中显示空白原因tree.write()默认不写 XML 声明且缩进丢失导致某些解析器拒绝加载。修复tree.write(output_path, encodingutf-8, xml_declarationTrue)并确保indent()函数已定义如上。陷阱width值被写成科学计数法如6.4e02原因str(float(640))在某些 Python 版本下输出640.0但若new_width是640.0而非intstr()可能触发浮点表示。修复强制int(new_width)如代码所示。4. 两个脚本的协同工作流从 YOLO TXT 到 MATLAB 训练数据的闭环4.1 典型场景将 COCO 导出的 YOLO 标注迁移到 MATLAB Deep Learning Toolbox假设你从 CVAT 导出 YOLO 格式images/0001.jpglabels/0001.txt内容0 0.5 0.5 0.2 0.3annotations/0001.xmlPascal VOC 格式width640/widthheight480/height但 MATLAB 要求图像尺寸统一为1920x1080需更新 XML标注存为data_0001.mat结构体含image_name,boxes,classes执行流程先更新 XML 尺寸确保后续坐标计算基准一致python change_xml_wh.py annotations/0001.xml 1920 1080此时0001.xml中width变为1920height变为1080。再转换 TXT 到 MAT利用新尺寸还原像素坐标修改convert_txt_mat.py中orig_w, orig_h 1920, 1080然后运行python convert_txt_mat.py labels/0001.txt data_0001.mat 0001.jpg验证 MATLAB 加载结果data load(data_0001.mat); fprintf(Image: %s, Boxes: %d\n, data.image_name, data.num_boxes); % 输出Image: 0001.jpg, Boxes: 14.2 参数联动表避免尺寸错位的黄金法则步骤脚本关键参数必须同步的值错位后果1. 更新图像元数据change_xml_wh.pynew_width,new_height与实际图像物理尺寸一致MATLABimread()读取图像尺寸 ≠ XML 声明尺寸坐标错位2. 转换标注坐标convert_txt_mat.pyorig_w,orig_h必须等于步骤1的new_width,new_height归一化坐标反推像素位置偏移bbox 偏离目标物体3. 生成 MAT 文件名手动指定或脚本生成mat_path应与图像文件名一一对应如0001.mat←→0001.jpgMATLABimageDatastore无法关联图像与标注4.3 进阶技巧用lxml替代ElementTree处理超大 XML当单个 XML 文件 100MB如医学影像标注xml.etree.ElementTree可能内存溢出。此时改用lxml的iterparse流式解析from lxml import etree def fast_update_xml(xml_path, new_w, new_h): context etree.iterparse(xml_path, events(start, end)) context iter(context) event, root next(context) for event, elem in context: if event start and elem.tag width: elem.text str(new_w) elif event start and elem.tag height: elem.text str(new_h) # 清理已处理元素释放内存 if event end: elem.clear() # 重新写入lxml 保持原始缩进 with open(xml_path, wb) as f: root.getroottree().write(f, encodingutf-8, xml_declarationTrue, pretty_printTrue)提示lxml需pip install lxml其iterparse内存占用仅为ElementTree的 1/5且支持 XPath 2.0如//size/width/text()直接获取文本值。5. 排查.mat文件加载失败的三个终端命令当scipy.io.loadmat()报错Unknown mat file type或 MATLAB 提示Cannot read file不要急着重装 SciPy——先用这三条命令定位问题根源5.1 检查.mat文件头与格式版本# 查看文件前 16 字节MATLAB v7 格式签名 hexdump -C -n 16 your_file.mat | head -1 # 正常输出00000000 4d 49 20 31 2e 30 20 4d 41 54 2d 4c 41 42 20 37 |MI 1.0 MAT-LAB 7| # 若显示 HDF5 字样则是 v7.3 格式scipy 1.7 才支持5.2 验证 XML 是否符合 W3C 规范# 使用 xmllintmacOS/Linux 自带Windows 需下载 xmllint --noout --schema http://www.w3.org/TR/xmlschema-1/xmlschema.xsd your_file.xml # 若报错 Element width: This element is not expected说明 XML 结构非法5.3 检查 Python 生成的.mat在 MATLAB 中的变量结构% 在 MATLAB 命令行运行 s whos(-file, your_file.mat); fprintf(%s: %s (%s)\n, s.name, s.class, s.size); % 关键看 boxes 是否为 double 类型且维度正确 % 若显示 boxes: 1x1 struct说明 savemat() 写入的是 dict of dict而非预期数组本文还有配套的精品资源点击获取