wj2015/3d-model-convert-to-gltf

3DModelConvertToGltf - 统一3D模型格式转换工具

概述

本项目主要解决STEP和IGES模型需要在Web上展示的场景，市场上的web3d库不支持此类格式，而用户上传的STL文件直接展示会消耗大量带宽或CDN流量，转换为压缩的gltf格式更为合适。

演示资产模型效果对比

支持输入格式：STL/IGES/STP/OBJ/FBX
支持输出格式：GLTF/GLB

项目状态：稳定

核心功能与特性

• ✅ 基础项目结构规划与接口设计
• ✅ 转换与压缩代码实现
• ✅ 支持OBJ格式转换为Draco GLTF
• ✅ Docker镜像打包
• ✅ 易用的convert.sh脚本
• ✅ 在线转换预览功能
• ✅ GRPC支持
• ❌ [bug] STP转换为GLTF文件过大问题
• ❌ RPC应返回错误详情
• ❌ RPC API应支持非Draco压缩

使用场景与适用范围

• Lexcent 3D打印：通过微信扫描下方***，可实现3D模型预览与打印支持
  !img

• Web3D模型展示：将大型3D模型转换为轻量级GLTF/GLB格式，降低带宽消耗

• 服务器端批量模型转换：通过GRPC或命令行模式实现自动化模型格式转换

详细使用方法与配置说明

在线转换预览

可通过https://github.com/wangerzi/modelbox-sdk%E5%9C%A8%E7%BA%BF%E8%BD%AC%E6%8D%A2%E6%A8%A1%E5%9E%8B%EF%BC%88<100MB），预览链接：[***]

GRPC模式

基于GRPC实现，便于构建动态扩展的服务集群，支持上传zip/模型源文件，为保证各模型兼容性，响应文件均为zip格式，需解压后使用。

服务端部署

确保8999端口可用且镜像为最新版本，执行以下命令：

shell
# 拉取镜像
docker pull wj2015/3d-model-convert-to-gltf:latest

# 启动GRPC服务
docker run -d -p 8999:8999 wj2015/3d-model-convert-to-gltf:latest

客户端使用

需复制server/rpc/protos/converter.proto文件，根据调用方语言生成代码模板。GRPC官方支持语言文档：Support Language

示例代码

命令模式

依赖Docker环境，适用于服务器端简单调用，转换过程为同步阻塞，不支持分布式扩展。

使用步骤

1. 下载convert.sh并赋予执行权限
2. 执行转换命令，第二个参数需根据文件类型选择：stl|stp|iges|obj|fbx

shell
# 转换为GLB单文件
convert.sh stl inputpath.stl outputpath.glb

# 生成GLTF文件
convert.sh stl inputpath.stl outputpath.gltf

测试文件

assets目录下提供测试文件：test.stl、test.stp、test.igs、E 45 Aircraft_obj.obj、Samba Dancing.fbx，可复制到项目路径测试转换效果。

权限问题处理

若通过php-fpm等语言执行器调用convert.sh时出现权限错误，需将执行用户添加到docker组：

shell
usermod -a -G docker nginx

其他语言调用示例（PHP）

php
<?php
$out = 'out.glb';
$input = 'test.stl';
$type = 'stl';
// 注意防范执行攻击
shell_exec('convert.sh '.$type.' '.$input.' '.$out);
if (file_exists($out)) {
    echo "转换结果: " . $out;
} else {
    echo "转换失败";
}
?>

Docker环境

拉取镜像

在安装Docker的主机上执行以下命令拉取镜像（约4G）：

shell
docker pull wj2015/3d-model-convert-to-gltf

容器内转换

进入容器后，执行以下命令进行同步转换：

shell
conda run -n pythonocc python convert.py [stl|step|iges|obj|fbx] input.stl out.glb

负载均衡方案

如需多机负载，可使用nginx代理或Docker容器配合RPC实现简单负载均衡，或通过消息队列实现生产者-消费者模式。HTTP API或队列需自行实现逻辑。

!1583754967257

开发环境搭建

Docker开发环境

1. 安装docker和docker-compose，参考官方文档：Docker Desktop
2. 进入environment/目录，执行docker-compose up，成功启动后输出如下：

shell
user@MacBook-Pro environment % docker-compose up
Recreating 3d-model-convert-to-gltf-app ... done
Starting 3d-model-convert-to-gltf-redis ... done
Attaching to 3d-model-convert-to-gltf-redis, 3d-model-convert-to-gltf-app
3d-model-convert-to-gltf-redis | 1:C 09 Oct 2020 03:03:29.150 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
...

3. 查看运行中的容器：

shell
user@MacBook-Pro 3d-model-convert-to-gltf % docker ps
CONTAINER ID        IMAGE                             COMMAND                  CREATED             STATUS              PORTS               NAMES
69b684ed7755        wj2015/3d-model-convert-to-gltf   "conda run -n python…"   3 seconds ago       Up 2 seconds                            3d-model-convert-to-gltf-app

4. 进入容器并激活conda环境：

shell
docker exec -it 3d-model-convert-to-gltf-app /bin/bash
conda activate pythonocc
python server/convert.py 

非Docker开发环境

适用于无法运行Docker的开发者，需手动配置依赖。

配置Python环境

shell
# 创建conda虚拟环境
conda create -n 3d-model-convert-to-gltf-pythonocc -c dlr-sc -c pythonocc pythonocc-core=7.4.0rc1
conda activate 3d-model-convert-to-gltf-pythonocc
pip install -r server/requirements.txt

配置Node环境

需Node.js 12.0.0版本，安装依赖包：

shell
# 安装nvm (MacOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

# 安装并使用Node 12.0.0
nvm install 12.0.0
nvm use 12.0.0

# 安装gltf-pipeline和obj2gltf
npm install -g gltf-pipeline obj2gltf

安装FBX2glTf

从https://github.com/***incubator/FBX2glTF%E4%B8%8B%E8%BD%BDFBX2glTf%EF%BC%8C%E5%B9%B6%E9%87%8D%E5%91%BD%E5%90%8D%E4%B8%BA%60fbx2gltf%60%E6%94%BE%E5%85%A5%E7%8E%AF%E5%A2%83%E7%9B%AE%E5%BD%95%E3%80%82

版本更新记录

• v1.4 2021-06-11 17:20：支持GRPC，重构转换代码，修复bug
• v1.3 2020-06-24 17:19：添加英文文档，修复bug
• v1.0 2020-05-21 19:08：基础提交，核心功能完成，支持shell转换

常见问题

为什么不使用assmip？

曾尝试使用https://github.com/assimp/assimp%EF%BC%8C%E4%BD%86%E5%9C%A8%60stl/iges/obj%60%E8%BD%AC%E6%8D%A2%E6%B5%8B%E8%AF%95%E4%B8%AD%E6%95%88%E6%9E%9C%E4%B8%8D%E4%BD%B3%E3%80%82%E5%8F%AF%E4%BD%BF%E7%94%A8https://hub.docker.com/r/dylankenneally/assimp%E9%95%9C%E5%83%8F%E8%BF%9B%E8%A1%8C%E6%B5%8B%E8%AF%95%E3%80%82

为什么不实现API？

模型转换是高资源消耗且速度较慢的服务，模型上传下载会消耗带宽。直接部署在自有服务器会面临高带宽和CPU消耗，需引入OSS、CDN及动态扩展队列和后端服务，部署和实现成本较高。

许可证

3DModelConvertToGltf基于Apache License 2.0许可。详见https://github.com/GitbookIO/gitbook/blob/master/LICENSE%E3%80%82