MCFiguers 项目简介

1. 简介

MCFiguers 是一个面向 Minecraft 搭建参考的 3D 模型体素化工具，目标是把带贴图的 OBJ 模型转换成可旋转查看的方块化结构，帮助玩家对照模型在游戏中还原手办或角色造型。

2. 项目背景

这个项目的起点来自一个很直接的想法：想在 MC 游戏里搭建手办，于是希望先把 3D 模型及其贴图体素化，再对照体素结果在游戏内逐块搭建。项目早期已经完成了 OBJ 模型读取、材质解析、原模型预览和初步体素化窗口，但由于当时的代码能力仍在成长阶段，对 3D 模型渲染、纹理采样、UV 坐标和面片到体素颜色映射的理解还不够完整，最终卡在了“贴图颜色如何正确附着到体素”这一环节。

目前代码已归档，作为一次对图形渲染、模型解析和体素化算法的实践记录保留。未来如果继续推进，重点会放在纹理颜色采样、体素填充策略和导出到 MC 搭建参考格式上。

3. 核心功能及亮点

• OBJ/MTL 模型解析：项目能够读取 OBJ 模型中的顶点、法线、纹理坐标和面片信息，并根据 MTL 材质文件关联贴图路径，为后续渲染和体素化提供结构化数据。
• 原始模型实时预览：通过 OpenGL 渲染模型，并支持贴图材质、基础光照、旋转、平移和缩放查看，便于在体素化前确认模型是否正确加载。
• 基于高度限制的体素网格生成：用户可以输入目标高度，程序根据模型包围盒计算体素大小与三维网格尺寸，将模型面片映射到对应体素位置，形成初步的方块化结果。
• 体素结果独立窗口展示：体素化后的方块以独立渲染窗口展示，并沿用旋转、平移、缩放交互，能够从不同角度检查模型轮廓和空间结构。
• 材质与贴图编辑尝试：界面中提供材质颜色选择和贴图加载入口，并通过更新队列同步到渲染窗口，体现了对“模型数据编辑”和“实时渲染反馈”协作流程的探索。

它不是只做静态文件解析，而是把“模型数据结构、材质贴图、OpenGL 渲染、鼠标交互、体素化结果预览”串成了一个完整的实验链路。虽然最终没有解决颜色准确附着，但已经覆盖了 3D 模型处理工具中最关键的几个环节。

4. 技术栈

• Java 21：项目主体语言，用于实现桌面应用、模型数据结构、OBJ/MTL 解析和体素化逻辑。
• Swing：构建模型加载、材质选择、贴图加载和体素高度输入等基础操作界面。
• LWJGL / GLFW / OpenGL：负责创建渲染窗口、处理鼠标输入，并完成原模型与体素方块的实时 3D 渲染。
• GLSL Shader：分别为原始模型和体素模型编写顶点/片段着色器，实现矩阵变换、纹理采样、颜色输出和基础光照。
• JOML：处理向量、矩阵、摄像机视图、投影变换、模型旋转缩放和平移等 3D 数学计算。
• STBImage / ImageIO：加载纹理图片，并尝试将贴图像素数据用于材质渲染和体素颜色采样。
• IntelliJ IDEA 工程配置：项目以 IDEA Java Module 形式组织，依赖本地配置的 JDK 与图形库。

5. 项目成果

项目已经实现了 OBJ 模型读取、MTL 贴图关联、原模型渲染预览、鼠标交互查看和初步体素化展示。体素窗口可以根据指定高度生成方块网格，并支持从各个角度旋转、平移、缩放观察结果。

当前主要限制是颜色无法正确附着到体素上：代码中已经尝试通过面片的纹理坐标读取贴图颜色，并对落入同一体素的颜色取平均值，但面片到体素的覆盖关系、纹理采样位置、内部填充判断等逻辑还不完善，因此结果还不能稳定还原模型贴图颜色。README 中也记录了项目目前卡在“体素化的颜色提取以及填充体素”阶段。

整体而言，项目产出了一个可运行的 3D 模型体素化原型，验证了从模型解析到可视化预览的基本流程，也留下了一个后续继续研究模型体素化与 MC 建筑辅助工具的基础。

7. 未来展望

• 完善贴图颜色采样：基于三角形重心、UV 插值或更细粒度的面片采样，将纹理颜色更准确地映射到体素表面。
• 补全体素填充逻辑：从当前偏表面的体素映射，进一步实现稳定的内部填充和空洞处理，让生成结果更适合 MC 方块搭建。
• 增加 MC 搭建辅助输出：未来可导出分层切片图、方块坐标表、材料清单或可被其他 MC 工具读取的结构文件。
• 优化性能与可用性：减少逐体素逐帧绘制带来的性能压力，增加加载状态、错误提示、参数校验和更清晰的操作流程。
• 沉淀图形学知识：在继续实现的过程中系统补齐 OBJ/MTL、UV 坐标、纹理采样、光栅化思想和体素化算法等基础知识。