Ml For 3d Course

欢迎来到《ML for 3D》课程！咱们今天不聊高大上的理论，直接上手干活。这门课的目标是让你用机器学习玩转3D模型，而且完全免费、零门槛。你只需要一台能上网的电脑，连显卡都不用买——因为咱们全程用 Hugging Face 的在线平台。

第一步：注册 Hugging Face 账号
1）打开浏览器，访问 huggingface.co（国内用户如果打不开，可以试试镜像站 hf-mirror.com）。
2）点击右上角“Sign Up”，用邮箱注册，或者直接用 GitHub/Google 账号登录。
3）登录后，点右上角头像 → “New Space”，创建一个新的 Space。这是咱们的“工作间”，以后所有代码和模型都跑在这里。

第二步：了解3D数据格式
3D模型常见格式有：OBJ（最通用）、STL（3D打印常用）、PLY（带颜色信息）、GLB/GLTF（网页3D标准）。咱们课程主要用 GLB，因为它在浏览器里直接就能看，不用装任何软件。

下载一个示例模型试试：
```python
# 在 Hugging Face Space 里新建一个 notebook，运行下面代码
import requests
url = "https://huggingface.co/datasets/ysharma/3d-examples/resolve/main/chair.glb"
r = requests.get(url)
with open("chair.glb", "wb") as f:
f.write(r.content)
print("下载成功！")
```

第三步：安装必备库
在 Space 的终端里运行：
```bash
pip install trimesh pyrender numpy matplotlib
```
trimesh 是处理3D模型的瑞士军刀，pyrender 用来可视化。装好后，跑个测试：
```python
import trimesh
mesh = trimesh.load("chair.glb")
print(f"模型有 {len(mesh.vertices)} 个顶点，{len(mesh.faces)} 个面")
mesh.show() # 如果没弹窗，别急，后面我们用网页方式看
```

实用技巧：
- 国内用户下载慢？把 huggingface.co 换成 hf-mirror.com 就行。
- 如果 Space 环境重启了，代码要重新跑，但下载的模型文件会保留（除非你手动删）。
- 遇到“ModuleNotFoundError”？别慌，就是没装库，再跑一次 pip install。

现在你已经有了一个能跑3D代码的环境，下一章咱们开始“看”懂3D模型！

上一章咱们搭好了环境，现在来点真格的——用机器学习处理3D点云。点云就是一堆三维坐标点，比如用手机LiDAR扫描房间，得到的就是点云。咱们要教会电脑“看懂”这些点。

第一步：把3D模型变成点云
大多数3D模型是三角形网格（一堆小三角形拼成的表面），咱们先把它采样成点云：
```python
import trimesh
import numpy as np

mesh = trimesh.load("chair.glb")
# 从模型表面随机采样10000个点
points, _ = trimesh.sample.sample_surface(mesh, 10000)
print(f"采样了 {points.shape[0]} 个点")
# 保存为numpy数组，方便后续处理
np.save("chair_points.npy", points)
```

第二步：用PointNet做分类
PointNet是处理点云的经典网络，咱们直接用Hugging Face上训练好的模型。先装个库：
```bash
pip install torch torchvision open3d
```
然后加载预训练模型：
```python
from transformers import AutoModelForImageClassification, AutoFeatureExtractor
import torch

# 这里用个简化版示例，实际PointNet需要自己写或找第三方实现
# 但咱们可以先用Hugging Face的3D视觉模型
model_name = "facebook/detr-resnet-50" # 只是个示例，实际可用PointNet变体
# 注意：Hugging Face上专门的3D模型还不多，咱们用巧办法
```

第三步：自己训练一个简单分类器
别怕，咱们不用从零写神经网络，用scikit-learn就行：
```python
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split

# 假装我们有一些点云数据（实际要准备数据集）
X = np.random.rand(100, 3) # 100个点，每个点xyz
y = np.random.randint(0, 2, 100) # 0或1标签

# 提取简单特征：每个点的坐标直接当特征
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
clf = RandomForestClassifier()
clf.fit(X_train, y_train)
print(f"准确率: {clf.score(X_test, y_test):.2f}")
```
重点：真实项目里，点云特征要提取更复杂的，比如法向量、曲率、局部密度。咱们先跑通流程。

实用技巧：
- 点云数据量大？用体素滤波降采样：`voxelized = mesh.voxelized(pitch=0.02)`。
- 国内下载模型慢？设置镜像：`export HF_ENDPOINT=https://hf-mirror.com`。
- 如果报显存不足，把采样点数从10000降到5000。

现在你学会了把3D模型转成点云，并跑了一个简单的分类器。下章咱们玩更酷的——用AI生成3D模型！

最激动人心的环节来了——用AI“凭空”生成3D模型！就像Midjourney画图一样，咱们输入一段文字，AI直接输出一个可以3D打印的模型。这里我们用Hugging Face上的Shap-E模型（OpenAI出品）。

第一步：加载Shap-E模型
Shap-E是文本/图像转3D的扩散模型。先装依赖：
```bash
pip install diffusers transformers accelerate torch
```
然后加载模型（注意：模型约2GB，第一次下载会慢点）：
```python
from diffusers import ShapEPipeline
import torch

pipe = ShapEPipeline.from_pretrained("openai/shap-e", torch_dtype=torch.float16)
pipe = pipe.to("cuda" if torch.cuda.is_available() else "cpu")
print("模型加载成功！")
```

第二步：从文本生成3D模型
输入一段描述，AI就会生成对应的3D模型：
```python
# 生成一个椅子
prompt = "a comfortable armchair with wooden legs"
with torch.no_grad():
images = pipe(prompt, guidance_scale=15.0, num_inference_steps=64, frame_size=256).images

# 保存为GLB文件
import trimesh
# 这里Shap-E输出的是多视图图像，需要转成3D网格（简化版）
# 实际要用Shap-E的3D输出接口，这里用伪代码示意
mesh = trimesh.Trimesh(vertices=images[0], faces=images[1]) # 假设images包含顶点和面
mesh.export("generated_chair.glb")
print("3D模型已生成！")
```
注意：上面代码是简化版，实际Shap-E输出的是NeRF参数，需要调用`pipe.export_to_mesh()`方法。完整代码如下：
```python
# 正确的Shap-E生成方式
result = pipe(prompt, guidance_scale=15.0, num_inference_steps=64)
mesh = result.images[0] # 直接返回Trimesh对象
mesh.export("generated_chair.glb")
```

第三步：在浏览器里查看生成的模型
把生成的GLB文件放到Hugging Face Space里，用Three.js显示。咱们用最简单的方式——直接在notebook里看：
```python
# 用open3d可视化（需先安装：pip install open3d）
import open3d as o3d
mesh_o3d = o3d.io.read_triangle_mesh("generated_chair.glb")
o3d.visualization.draw_geometries([mesh_o3d])
```

实用技巧：
- 想生成更复杂的物体？试试提示词：`"a futuristic robot with glowing blue eyes"`。
- 如果模型生成效果差，调高`guidance_scale`（建议10-20），或增加`num_inference_steps`（64-128）。
- 国内用户注意：`openai/shap-e`模型可能被墙，用镜像：`pipe = ShapEPipeline.from_pretrained("openai/shap-e", cache_dir="./cache")`，然后手动下载模型文件放到cache目录。
- 显存不够？用CPU模式（`device="cpu"`），但生成速度会慢10倍。

现在你已经能用文字生成3D模型了！下章咱们学如何优化和分享这些模型。

前几章咱们生成了3D模型，但往往不够完美——可能有破洞、面数太多、或者文件太大。这一章教你怎么“打磨”模型，并发布到Hugging Face上让全世界看到。

第一步：修复模型几何问题
用trimesh自动修复常见问题：
```python
import trimesh

mesh = trimesh.load("generated_chair.glb")
# 1) 合并重复顶点
mesh.merge_vertices()
# 2) 移除孤立的小碎片
mesh = mesh.split(only_watertight=False)[0] # 取最大连通组件
# 3) 填充孔洞
mesh.fill_holes()
# 4) 修复法线方向
mesh.fix_normals()
print(f"修复后顶点数: {len(mesh.vertices)}, 面数: {len(mesh.faces)}")
mesh.export("fixed_chair.glb")
```
重点：如果模型有自相交面（面与面交叉），用`mesh.remove_degenerate_faces()`清理。

第二步：模型简化（减面）
生成的模型可能有几十万面，网页加载会卡。咱们减到1万面以内：
```python
# 用pyacvd库（需安装：pip install pyacvd）
import pyacvd
import numpy as np

# 均匀采样简化
clus = pyacvd.Clustering(mesh)
clus.cluster(10000) # 目标顶点数
simplified = clus.create_mesh()
simplified.export("simplified_chair.glb")
print(f"简化后面数: {len(simplified.faces)}")
```

第三步：发布到Hugging Face
1）在Hugging Face上创建一个新Dataset或Model仓库。
2）用huggingface_hub库上传：
```bash
pip install huggingface_hub
```
```python
from huggingface_hub import HfApi, login

# 先登录（会提示输入token，在Hugging Face Settings里生成）
login()

api = HfApi()
api.upload_file(
path_or_fileobj="simplified_chair.glb",
path_in_repo="chair.glb",
repo_id="你的用户名/3d-models",
repo_type="model",
)
print("上传成功！")
```

第四步：创建在线3D查看器
在Hugging Face Space里新建一个Gradio应用：
```python
# app.py
import gradio as gr
import trimesh
import plotly.graph_objects as go

def visualize_3d(model_path):
mesh = trimesh.load(model_path)
# 用Plotly显示
fig = go.Figure(data=[
go.Mesh3d(
x=mesh.vertices[:,0], y=mesh.vertices[:,1], z=mesh.vertices[:,2],
i=mesh.faces[:,0], j=mesh.faces[:,1], k=mesh.faces[:,2],
color='lightblue', opacity=0.8
)
])
return fig

gr.Interface(
fn=visualize_3d