我要提问
ARTICLE DETAIL

资讯详情

前沿编程新知与开发实战干货的深度解读。

使用 Label Studio 标注关键点数据并转换为 COCO 格式(MMPose 实战指南)

使用 Label Studio 标注关键点数据并转换为 COCO 格式(MMPose 实战指南) 使用 Label Studio 标注关键点数据并转换为 COCO 格式MMPose 实战指南【免费下载链接】mmposeOpenMMLab Pose Estimation Toolbox and Benchmark.项目地址: https://gitcode.com/GitHub_Trending/mm/mmposeLabel Studio 是一款广泛使用的开源深度学习标注工具但在关键点keypoint标注场景下它无法直接导出 MMPose 所需的 COCO 格式标注文件。本文将以 docs/en/user_guides/label_studio.md 为核心系统讲解如何在 Label Studio 中完成关键点、分割与包围框的规范标注如何通过 labelstudio2coco.py 将导出的 JSON 一键转换为 COCO 格式并最终接入 MMPose 的训练/评估配置同时结合仓库源码剖析转换器内部的实现原理与注意事项。背景为什么需要转换脚本MMPose 的数据集统一采用 COCO 风格标注其要求每条实例标注annotation同时携带keypoints、segmentation与bbox三类信息。而 Label Studio 在标注时会将这些信息分散到不同的独立标注KeyPointLabels、PolygonLabels、RectangleLabels中因此标注阶段必须遵守特定规则才能在后续转换脚本中正确合并为单个实例。此外MMPose 官方还提供了 Label Studio 相关工具的使用入口该文档中声明MMPose 对标注工具不做任何限制只要最终标注结果满足数据格式要求即可见 dataset_tools.md 的注释说明。一、Label Studio 标注规范1.1 标注界面配置新建 Label Studio 项目后需要在项目Settings设置中找到Labeling Interface标注界面点击Code粘贴以下示例代码。该配置定义了三种标注类型分别对应 COCO 格式中的三类字段KeyPointLabels对应keypointsPolygonLabels对应segmentationRectangleLabels对应bboxView KeyPointLabels namekp-1 toNameimg-1 Label valueperson background#D4380D/ /KeyPointLabels PolygonLabels namepolygonlabel toNameimg-1 Label valueperson background#0DA39E/ /PolygonLabels RectangleLabels namelabel toNameimg-1 Label valueperson background#DDA0EE/ /RectangleLabels Image nameimg-1 value$img/ /View从源码角度可以更清楚地理解该 XML 的作用。labelstudio2coco.py 中的LSConverter.__init__通过xml.etree.ElementTree解析该 XMLtree ET.parse(config) root tree.getroot() labels root.findall(.//KeyPointLabels/Label) label_values [label.get(value) for label in labels] self.categories list() self.category_name_to_id dict() for i, value in enumerate(label_values): # category id start with 1 self.categories.append({id: i 1, name: value}) self.category_name_to_id[value] i 1即转换器只读取KeyPointLabels下的Label value.../作为类别名称category id 从 1 开始按顺序递增并构建categories列表写入最终 COCO JSON 的categories字段。1.2 标注顺序关键规则由于需要将不同类型的标注合并到同一个实例标注顺序决定了各标注的归属关系。规则如下按KeyPointLabels→PolygonLabels/RectangleLabels的顺序标注一个实例内以关键点开始、以非关键点结束KeyPointLabels的顺序和数量必须与 MMPose 配置文件dataset_info中定义的关键点顺序和数量一致PolygonLabels与RectangleLabels的标注顺序可以互换且只需标注其中一种。注意bbox和area会基于后标注的 PolygonLabels/RectangleLabels 计算。若先标注 PolygonLabels则 bbox 基于后标注的 RectangleLabels 范围、area 等于矩形面积反之则基于多边形的最小外接矩形与多边形面积。这一点在 labelstudio2coco.py 的 docstring 中亦有明确描述The annotations in label studio must follow the order: keypoint 1, keypoint 2... keypoint n, rect of the instance, polygon of the instance, then annotations of the next instance. Where the order of rect and polygon can be switched, the bbox and area of the instance will be calculated with the data behind. Only annotating one of rect and polygon is also acceptable.1.3 关键点顺序与 dataset_info 对齐关键点顺序与dataset_info一致意味着你需要先确定目标关键点骨架定义。以 COCO 人体 17 关键点为例其顺序定义在 configs/base/datasets/coco.py 的dataset_info.keypoint_info中0 为 nose鼻子、1 为 left_eye左眼、2 为 right_eye右眼……直到 16 为 right_ankle右踝每个关键点还包含color可视化颜色、typeupper/lower、swap左右翻转互换关系等信息。在 Label Studio 中标注时每个实例的关键点必须严格按照这个顺序依次点选转换后的keypoints数组才能与 MMPose 的数据加载与评估逻辑匹配。1.4 导出标注结果标注完成后点击项目界面的Export按钮选择JSON格式点击Export下载包含标注的 JSON 文件。注意导出的文件只包含标注不含原始图片因此需要单独提供对应的标注图片。不建议直接使用上传方式导入图片因为 Label Studio 会截断过长的文件名推荐使用Export功能中的导出 COCO 格式工具其下载的压缩包内会包含图片文件夹。二、使用转换脚本生成 COCO 数据集2.1 脚本用法与参数转换脚本位于 tools/dataset_converters/labelstudio2coco.py其参数解析定义如下parser argparse.ArgumentParser( descriptionConvert Label Studio JSON file to COCO format JSON File) parser.add_argument(config, helpLabeling Interface xml code file path) parser.add_argument(input, helpLabel Studio format JSON file path) parser.add_argument(output, helpThe output COCO format JSON file path)三个位置参数分别为参数含义说明config标注界面 XML 代码文件即上一节Labeling Interface - Code中的 XML 内容保存为.xml文件inputLabel Studio 导出的 JSON 文件例如project-1-at-2023-05-13-09-22-91b53efa.jsonoutput输出 COCO 格式 JSON 路径若路径不存在脚本会自动创建实际命令示例python tools/dataset_converters/labelstudio2coco.py config.xml project-1-at-2023-05-13-09-22-91b53efa.json output/result.json该命令同时出现在 docs/en/user_guides/dataset_tools.md 的 Label Studio 章节中是官方推荐的调用方式。2.2 转换后的目录结构转换完成后将图片文件夹放入输出目录即可得到完整的 COCO 数据集目录结构示例如下. ├── images │ ├── 38b480f2.jpg │ └── aeb26f04.jpg └── result.json2.3 接入 MMPose 配置若要在 MMPose 中使用该数据集可在配置文件中按如下方式修改datasetdatasetdict( typedataset_type, data_rootdata_root, data_modedata_mode, ann_fileresult.json, data_prefixdict(imgimages/), pipelinetrain_pipeline, )其中ann_file指向转换得到的result.jsondata_prefix的img指向图片目录。MMPose 的 BaseCocoStyleDataset 会以data_root作为ann_file与data_prefix的根目录来拼接完整路径源码中ann_file、data_root、data_prefix均为其构造参数并通过assert exists(self.ann_file)校验标注文件是否存在后开始加载。三、转换脚本实现原理详解3.1 整体流程main()函数依次执行解析参数 → 实例化LSConverter(config)→ 调用convert_to_coco(input_json, output_json)。核心转换逻辑位于LSConverter.convert_to_coco中其流程可概括为读取 Label Studio 导出的 JSON每个 item 对应一张图片跳过没有标注的 item记录 warning 日志逐条遍历该 item 的result标注列表根据label[type]分发到三种处理分支聚合images、annotations、categories与info后写出 COCO JSON。3.2 图片信息提取每个 item 的file_upload字段作为图片文件名image_id按顺序自增image_id len(images)。图片宽高从标注的original_width/original_height字段中获取if not height or not width: if original_width not in label or \ original_height not in label: logger.debug( foriginal_width or original_height not found fin {image_name}) continue # get height and width info from annotations width, height label[original_width], label[ original_height] images add_image(images, width, height, image_id, image_name)add_image内部构造{width, height, id, file_name}四字段的 image 记录。3.3 矩形框RectangleLabels处理Label Studio 的矩形坐标以百分比0~100存储需要乘以original_width/original_height还原为像素坐标x label[value][x] y label[value][y] w label[value][width] h label[value][height] x x * label[original_width] / 100 y y * label[original_height] / 100 w w * label[original_width] / 100 h h * label[original_height] / 100 # rect annotation should be later than keypoints annotations[-1][bbox] [x, y, w, h] annotations[-1][area] w * h annotations[-1][num_keypoints] kp_num注意annotations[-1]矩形框的 bbox/area 会直接写入上一条已创建的 keypoint annotation这正是矩形必须标注在关键点之后这一规则的代码体现。3.4 多边形PolygonLabels处理多边形同样以百分比坐标存储转换时计算最小外接矩形作为 bbox并用向量叉积公式鞋带公式计算多边形面积points_abs [(x / 100 * width, y / 100 * height) for x, y in label[value][points]] x, y zip(*points_abs) x1, y1, x2, y2 min(x), min(y), max(x), max(y) # calculate bbox and area from polygons points # which may be different with rect annotation bbox [x1, y1, x2 - x1, y2 - y1] area float(0.5 * np.abs( np.dot(x, np.roll(y, 1)) - np.dot(y, np.roll(x, 1)))) # polygon label should be later than keypoints annotations[-1][segmentation] [[ coord for point in points_abs for coord in point ]] annotations[-1][bbox] bbox annotations[-1][area] area annotations[-1][num_keypoints] kp_numsegmentation被写成单层 list 的扁平化坐标数组[[x1, y1, x2, y2, ...]]符合 COCO RLE 之外的多边形表示习惯。3.5 关键点KeyPointLabels处理与实例聚合关键点是实例的起点当遇到第一条关键点标注i 0或上一条标注不是关键点类型时创建一个新的 COCO annotation否则将当前关键点追加到上一条 annotation 的keypoints数组中elif keypointlabels label[type]: x label[value][x] * label[original_width] / 100 y label[value][y] * label[original_height] / 100 # there is no method to annotate visible in Label Studio # so the keypoints visible code will be 2 except (0,0) if x y 0: current_kp [x, y, 0] kp_num_change 0 else: current_kp [x, y, 2] kp_num_change 1 # create new annotation in coco # when the keypoint is the first point of an instance if i 0 or item[annotations][0][result][ i - 1][type] ! keypointlabels: annotations.append({ id: annotation_id, image_id: image_id, category_id: category_id, keypoints: current_kp, ignore: 0, iscrowd: 0, }) kp_num kp_num_change else: annotations[-1][keypoints].extend(current_kp) kp_num kp_num_change这里有一个值得注意的细节Label Studio 没有提供标注关键点可见性visible的方法因此脚本将所有关键点的可见性码visible flag设为2即已标注且可见唯一例外是坐标恰为(0, 0)的关键点会被视为不存在可见性码设为0且不计数。这也是原始文档未展开、但阅读源码可以获得的实现事实。3.6 输出 JSON 结构最终通过json.dump(..., indent2)写出包含images、categories、annotations、info四个顶层字段的 COCO JSON其中info记录年份、版本与日期等元信息。四、常见问题与注意事项关键点顺序错误这是最常见的问题。转换脚本不会对关键点做任何重排仅按标注顺序原样写入。若标注顺序与dataset_info不一致训练时关键点将与语义标签错位。建议标注前先打印dataset_info.keypoint_info核对顺序。必须同时标注关键点与框/多边形每个实例以关键点开始、以非关键点结束。若某实例缺少 PolygonLabels 或 RectangleLabels其bbox、area、segmentation字段将缺失影响训练与评估。文件名截断问题Label Studio 会截断过长的上传文件名导致图片路径与标注无法对应建议使用 Export 中的 COCO 导出功能压缩包内含图片文件夹。可见性标记的局限由于 Label Studio 无法标注关键点可见性转换结果中所有关键点可见性码均为 2除 (0,0) 外。若你的任务对遮挡/可见性敏感需在转换后自行后处理标注文件。类别 id 从 1 开始转换脚本为每个KeyPointLabels下的 Label 按顺序分配从 1 开始的 category id与部分 COCO 数据集从 0 或 1 起始的习惯不同接入自定义评估代码时需注意对齐。五、延伸阅读完整的标注工具使用流程可参考 dataset_tools.md其中还包含 Browse Dataset、MIM 下载开源数据集、以及其他数据集格式转换脚本的说明若要了解 MMPose 数据集类如何加载 COCO 标注可阅读 base_coco_style_dataset.py 的load_data_list与parse_data_info实现标准 COCO 人体关键点骨架定义见 configs/base/datasets/coco.py转换脚本 labelstudio2coco.py 基于 label-studio-converter 改写遵循 Apache 2.0 许可见脚本头部注释。【免费下载链接】mmposeOpenMMLab Pose Estimation Toolbox and Benchmark.项目地址: https://gitcode.com/GitHub_Trending/mm/mmpose创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表