# img2model

**Repository Path**: lettu_xust/img2model

## Basic Information

- **Project Name**: img2model
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# img2model

img2model 将 1-5 张物体或建筑影像生成带纹理的三维网格，并可在生成完成后自动执行网格质量评测。

## 处理流程

```text
输入影像
  -> RMBG 去背景
  -> TRELLIS 粗网格
  -> UltraShape 几何细化
  -> 降面与 UV 展开
  -> MV-Adapter 多视图纹理与烘焙
  -> output_mesh.glb
  -> 网格评测
  -> mesh_eval_report.json
```

## 部署组成

完整运行环境由三部分组成，缺少任意一部分都无法启动：

| 部分 | 内容 | 是否在本仓库 |
|---|---|---|
| Docker 镜像 | `img2model:v1.4`，包含 CUDA、Conda 和 Python 依赖 | 否 |
| 服务与 pipeline 代码 | Flask 服务、生成 pipeline、评测脚本 | 是，位于 `original_img2model/` |
| 外部资产 | TRELLIS、UltraShape、MV-Adapter、权重缓存、Blender | 否，需从现有服务器迁移 |

注意：裸镜像中没有 `run_img2model_with_eval.py`。该脚本由宿主机目录通过 bind mount 提供。

## 仓库结构

```text
.
├── README.md                         # 项目入口与文档导航
├── IMG2MODEL_DEPLOYMENT_GUIDE.md     # 新机器完整部署手册
├── README_img2model_test.md          # HTTP、本地 pipeline 和独立评测
├── run_img2model_eval.sh             # 本地 pipeline + 评测的一键脚本
├── flask_run_inference_8130.py       # Flask 服务代码的顶层留档
├── run_img2model_with_eval.py        # pipeline + 评测合并入口的顶层留档
├── eval_img2model_mesh.py            # 评测脚本的顶层留档
└── original_img2model/               # 按服务器运行路径整理的可部署目录
    ├── service/img2model/
    ├── workspace/Pipelines/img2model_deployment/
    ├── workspace/Pipelines/building_refine/
    └── utils/MaterialAnything2/
```

部署时以 `original_img2model/` 下的目录结构为准。顶层三个 Python 文件用于查阅和留档，不要与部署目录中的同名文件混用。

## 快速开始

以下示例假设：

- Git 仓库克隆到 `/data/img2model-repo`；
- 完整运行目录为 `/data/img2model-runtime`；
- 运行目录在容器内固定挂载为 `/moganshan/afs_a/lbx`；
- 镜像 `img2model:v1.4` 已导入，外部仓库、权重和 Blender 已迁移。

部署代码：

```bash
git clone git@gitee.com:lettu_xust/img2model.git /data/img2model-repo
mkdir -p /data/img2model-runtime
rsync -a /data/img2model-repo/original_img2model/ /data/img2model-runtime/
```

启动服务（物理 GPU 1、端口 5003）：

```bash
docker run -d \
  --name img2model_8130_1 \
  --runtime nvidia \
  -e NVIDIA_VISIBLE_DEVICES=1 \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
  --network host \
  -v /data/img2model-runtime:/moganshan/afs_a/lbx \
  -e IMG2MODEL_GPU=0 \
  -e PORT=5003 \
  -e IMG2MODEL_OCTREE_RES=768 \
  -e IMG2MODEL_TRELLIS_SIMPLIFY=1 \
  --shm-size=8gb \
  --restart unless-stopped \
  img2model:v1.4 \
  /moganshan/afs_a/lbx/service/img2model/entrypoint.sh
```

等待模型预热完成后检查：

```bash
docker logs -f img2model_8130_1
curl http://127.0.0.1:5003/health
```

预期 `warmed_up` 为 `true`。

## 使用入口

| 使用方式 | 入口 | 输入 | 适用场景 |
|---|---|---|---|
| HTTP 服务 | `POST /api/v1/modeling/submit` | HTTP(S) 图片 URL | 联调、生产服务 |
| 本地生成并评测 | `run_img2model_with_eval.py` | 本地影像目录，可选 `--compare_mesh` | 离线测试、批处理 |
| 单独评测 | `eval_img2model_mesh.py` | 已生成网格，可选比较网格 | 重跑或复核评测 |

本地 pipeline 是直接算法调用，不启动 Flask，也不发送 HTTP 请求。建议在空闲 GPU 上使用一次性容器运行，不要和已预热的 Flask 容器共用同一张 GPU。

## 输出

合并入口的主要输出：

```text
output_mesh.glb          最终模型
mesh_eval_report.json   评测报告
run_summary.json        本次运行摘要
pipeline_stdout.log     pipeline 日志
eval_stdout.log         评测日志
work/                   中间目录，仅使用 --keep-tmp 时保留
```

无比较网格时报告网格自身质量；指定 `--compare_mesh` 后增加 Chamfer distance、F-score 和法向一致性等对比指标。

## 文档索引

- [完整部署手册](IMG2MODEL_DEPLOYMENT_GUIDE.md)：镜像导入、代码与权重迁移、挂载、启动、验收和故障排查。
- [测试与调用手册](README_img2model_test.md)：HTTP curl、本地算法 pipeline、参数解释和单独评测。

## 安全说明

仓库不应包含 MinIO 密钥、模型权重、运行数据和生成结果。凭据应通过受保护的环境变量或部署配置注入，不要提交到 Git。