bardofcodes/migumi-dataset

MiGumi数据集是一个包含传统日本接头符号、几何和网格表示以及为CNC铣床设计的改型数据集。它提供了原始接头几何形状、仅限铣削的基线、开启和差分翻转方法以及我们的方法产生的变种。数据集的结构包括base.json、info.json、polyline_files、vis_files和meshes等文件夹，用于存储接头设计、元数据、MXG表示、导出格式转换文件和STL网格。The MiGumi Dataset is a collection of symbolic, geometric, and mesh representations of traditional Japanese joints and their redesigned variants for CNC milling. It includes the original joint geometry, a Milling Only baseline, an Opening & Diff-Flip method, and variants produced by our method. The dataset structure consists of folders containing base.json, info.json, polyline_files, vis_files, and meshes for storing joint designs, metadata, MXG representations, export-friendly format conversions, and STL meshes.

搜集汇总

数据集介绍

构建方式

在传统细木工与数控加工交叉领域，MiGumi数据集系统性地收录了日本传统接合节点及其面向CNC铣削的再设计变体。其构建过程以符号化接合设计语言MXG为起点，通过手动创建基础几何描述文件base.json，继而衍生出四种变体：原始几何的'base'型、基于形态学开运算确保可铣削性的'mill'基线、采用开运算与差异翻转启发式恢复接触的'odf'型，以及通过损失函数优化紧密耦合与铣削约束的'ours'型。每种变体均保存为MXG多段线表示、Blender兼容可视化文件及Trimesh与Shapely生成的STL网格，形成从符号逻辑到物理几何的完整数据链路。

特点

该数据集的核心特质在于其多维度的几何表征与工艺约束建模能力。传统接合节点被解构为符号化设计文件、多段线轨迹与三角网格三种层次，分别对应设计意图、加工路径与物理形态。尤其值得关注的是，四种变体构成了一条从原始设计到可制造性优化的渐进式光谱：'mill'变体通过形态学操作强制可铣削性却牺牲表面耦合，'odf'变体以启发式恢复接触却引入无效减法，而'ours'变体则通过损失函数在紧密耦合与铣削可行性间取得平衡。这种设计使得数据集不仅提供静态几何，更蕴含了制造约束下的设计推理过程。

使用方法

使用者可通过两种途径获取该数据集：直接采用Git LFS克隆仓库至本地文件系统，或借助Hugging Face Datasets API以编程方式加载。对于本地部署，执行'git lfs install'后克隆指定URL即可获得完整目录结构，各接合节点按名称独立存储，内含JSON元数据、多段线文件夹、可视化文件及STL网格。若采用API方式，load_dataset函数将自动解析文件夹结构并返回接合节点名称与文件路径的映射。值得注意的是，数据集附带的论文与代码仓库提供了变体生成算法的完整实现，便于研究者复现或扩展可铣削接合设计方法。

背景与挑战

背景概述

在计算机图形学与数字制造交叉领域，传统木工榫卯结构的数字化重构一直是研究热点，尤其以日本传统木工技艺中的“组木”（Kigumi）结构为代表，其精密的几何耦合与无需紧固件的特性为现代制造提供了独特灵感。MiGumi数据集由Aditya Ganeshan、Kurt Fleischer、Wenzel Jakob等多位学者于2025年联合创建，隶属于SIGGRAPH Asia 2025发表的同名论文。该数据集聚焦于如何将紧密耦合的整体式榫卯接头改造为适用于数控铣削（CNC）加工的几何形态，核心研究问题在于平衡传统结构的力学完整性与铣削工艺的可制造性。通过提供符号化几何表示（MXG语言）、多层级变体（原始、仅铣削、启发式优化及本方法优化）及网格模型，该数据集为几何计算、制造约束优化及数字木工领域提供了标准化基准，显著推动了可制造榫卯结构的自动化设计研究。

当前挑战

数据集所解决的领域挑战在于突破传统榫卯结构在CNC铣削中的几何约束：铣削刀具的圆柱形路径限制了内凹与悬垂特征的制造，而原始组木结构常包含这类不可铣削的几何细节。构建过程中遭遇的核心挑战包括：1）对原始接头进行形态学开运算（Opening）以生成可铣削几何时，会破坏零件间的接触面耦合，导致结构松散；2）简单的开运算与差异翻转（Diff-Flip）启发式方法虽能恢复部分接触，但常产生无效的布尔运算结果（如零件间出现非流形交集），或引入微小的薄片状残片（Slivers），破坏几何鲁棒性；3）在保持铣削约束的同时优化紧密耦合损失函数，需在离散的符号几何空间与连续制造约束间建立可微桥梁，这对算法设计与数值稳定性提出了严苛要求。

常用场景

经典使用场景

MiGumi数据集专为研究可铣削的日式木工接合（Kigumi）几何优化而设计，其核心应用场景在于对比不同制造约束下的接合件几何变体。数据集提供了传统接合设计的符号化表示（MXG语言）、多段线轮廓、网格模型及STL网格，支持研究者从原始几何（base）、仅铣削基线（mill）、开孔与差异翻转（odf）到所提优化方法（ours）等多层次变体进行系统化比较。这一结构化设计使得该数据集成为评估几何保真度、制造可行性与表面耦合紧密度之间权衡的基准测试平台，尤其适用于验证基于符号几何的计算机辅助制造算法。

实际应用

在实际制造领域，该数据集直接服务于自动化木工接合设计与数控编程的衔接。通过提供经过验证的优化接合几何（ours变体），制造商可直接将STL网格导入CAM软件生成铣削路径，无需依赖经验丰富的工匠进行手工调整。此外，数据集中的多段线表示可被用于工业机器人离线编程或五轴加工中心的刀具轨迹规划。对于定制化家具、建筑木结构或精密模具行业，MiGumi数据集提供了一种可复用的几何模板库，能够显著缩短从设计到制造的迭代周期，降低因传统试错法导致的材料浪费。

衍生相关工作

该数据集直接源于SIGGRAPH Asia 2025论文《MiGumi: Making Tightly Coupled Integral Joints Millable》，其衍生的经典工作包括：基于符号几何的制造约束优化框架（ours方法），该框架通过可微损失函数建模接合面紧密耦合与铣削可达性之间的博弈；以及ODF（开孔与差异翻转）启发式基线方法，后者虽简单但揭示了布尔几何操作在制造约束下的局限性。此外，数据集中的MXG语言描述可启发后续研究将传统木工接合知识编码为可计算的形式化语言，进而推动面向制造的生成式设计工具开发。这些工作共同构成了从符号几何到物理制造的可验证研究链条。