SpatialLM

---

✨ 最新消息

• [2025年9月] SpatialLM-Dataset 现已在 Hugging Face 上发布。
• [2025年9月] SpatialLM 被 NeurIPS 2025 接受。
• [2025年6月] 在 FINETUNE.md 中添加了微调说明。
• [2025年6月] 欢迎体验我们的新模型：SpatialLM1.1-Llama-1B 和 SpatialLM1.1-Qwen-0.5B，现已在 Hugging Face 上发布。SpatialLM1.1 将点云分辨率提升一倍，引入了更强大的点云编码器 Sonata，并支持用户自定义类别的检测任务。
• [2025年6月] SpatialLM 的 技术报告 已在 arXiv 上发布。
• [2025年3月] 我们很高兴在 Hugging Face 上发布了 SpatialLM-Llama-1B 和 SpatialLM-Qwen-0.5B。
• [2025年3月] SpatialLM 首次正式发布！

简介

SpatialLM 是一种用于处理 3D 点云数据并生成结构化 3D 场景理解输出的 3D 大型语言模型。其输出包括墙体、门、窗等建筑元素，以及带有语义类别信息的定向物体边界框。与以往需要专用设备采集数据的方法不同，SpatialLM 可以处理来自单目视频序列、RGBD 图像和 LiDAR 传感器等多种来源的点云数据。这种多模态架构有效地弥合了非结构化 3D 几何数据与结构化 3D 表示之间的鸿沟，提供高层次的语义理解能力。它能够增强具身机器人、自主导航以及其他复杂 3D 场景分析任务中的空间推理能力。

SpatialLM 模型

使用方法

安装

已在以下环境中测试通过：

• Python 3.11
• PyTorch 2.4.1
• CUDA 版本 12.4

# 克隆仓库
git clone https://github.com/manycore-research/SpatialLM.git
cd SpatialLM

# 创建包含 CUDA 12.4 的 conda 环境
conda create -n spatiallm python=3.11
conda activate spatiallm
conda install -y -c nvidia/label/cuda-12.4.0 cuda-toolkit conda-forge::sparsehash

# 使用 poetry 安装依赖
pip install poetry && poetry config virtualenvs.create false --local
poetry install
# SpatialLM1.0 的依赖
poe install-torchsparse # 构建 torchsparse 的 wheel 文件可能需要一些时间
# SpatialLM1.1 的依赖
poe install-sonata # 构建 flash-attn 的 wheel 文件也可能需要较长时间

推理

在当前版本的 SpatialLM 中，输入的点云被视为轴对齐的，其中 z 轴为垂直向上方向。这种方向对于在不同数据集和应用之间保持空间理解和场景解释的一致性至关重要。 经过预处理的点云示例，由 MASt3R-SLAM 从 RGB 视频中重建而来，可在 SpatialLM-Testset 中找到。

下载一个示例点云：

huggingface-cli download manycore-research/SpatialLM-Testset pcd/scene0000_00.ply --repo-type dataset --local-dir .

运行推理：

python inference.py --point_cloud pcd/scene0000_00.ply --output scene0000_00.txt --model_path manycore-research/SpatialLM1.1-Qwen-0.5B

基于用户指定类别的检测

SpatialLM1.1 利用大语言模型的灵活性，支持基于用户指定类别的物体检测。

SpatialLM1.1 提供三种结构化室内建模任务变体：

• 结构化重建：检测墙壁、门、窗户、盒子。
• 布局估计：检测墙壁、门、窗户。
• 3D 物体检测：检测盒子。

对于包含物体边界框估计的任务，您可以指定 59 种家具类别中的子集，模型将仅预测这些指定类别内的物体。例如：

python inference.py --point_cloud pcd/scene0000_00.ply --output scene0000_00.txt --model_path manycore-research/SpatialLM1.1-Qwen-0.5B --detect_type object --category bed nightstand

可视化

使用 rerun 可视化点云和预测的结构化 3D 布局输出：

# 将预测的布局转换为 Rerun 格式
python visualize.py --point_cloud pcd/scene0000_00.ply --layout scene0000_00.txt --save scene0000_00.rrd

# 可视化点云和预测的布局
rerun scene0000_00.rrd

评估

为了评估 SpatialLM 的性能，我们提供了 eval.py 脚本，该脚本在下文 Benchmark Results 部分的表格中报告了 SpatialLM-Testset 上的基准测试结果。

下载测试集：

huggingface-cli download manycore-research/SpatialLM-Testset --repo-type dataset --local-dir SpatialLM-Testset

运行评估：

# 使用 SpatialLM1.1-Qwen-0.5B 模型对 SpatialLM-Testset/pcd 文件夹中的 PLY 点云进行推理
python inference.py --point_cloud SpatialLM-Testset/pcd --output SpatialLM-Testset/pred --model_path manycore-research/SpatialLM1.1-Qwen-0.5B

# 评估预测的布局
python eval.py --metadata SpatialLM-Testset/test.csv --gt_dir SpatialLM-Testset/layout --pred_dir SpatialLM-Testset/pred --label_mapping SpatialLM-Testset/benchmark_categories.tsv

使用自定义视频的示例

我们在 EXAMPLE.md 中提供了一个示例，说明如何使用我们的模型从 RGB 视频开始估计场景布局，该视频使用新发布的 SLAM3R 生成。这些步骤同样适用于 MASt3R-SLAM 以及其他重建方法。

在自定义数据上微调

有关在您自己的数据上微调 SpatialLM 的说明，请参阅 FINETUNE.md。我们提供了一个使用 ARKitScenes 数据集的示例。

SpatialLM 数据集

SpatialLM 数据集是由专业 3D 设计师设计的大规模高质量合成数据集，已用于实际生产。它包含来自 12,328 个多样化室内场景的点云，共计 54,778 间房间，每间房间都配有丰富的 3D 真实标注。SpatialLM 数据集为推进室内场景理解、3D 感知及相关应用的研究提供了宝贵的资源。

如需访问用于生成 SpatialLM 点云的逼真 RGB/深度/法线/语义/实例全景渲染图以及相机轨迹，请参阅 SpatialGen 项目，以获取更多详细信息。

SpatialLM 测试集

我们提供了一个包含 107 个预处理点云的测试集，这些点云是使用 MASt3R-SLAM 从 RGB 视频重建的。与以往的干净 RGBD 扫描数据集相比，由于单目 RGB 视频重建的点云中存在噪声和遮挡，SpatialLM-Testset 的难度要高得多。

基准测试结果

布局估计

布局估计专注于预测室内场景中的建筑元素，即墙壁、门和窗户。我们在此任务上使用了 Structured3D 数据集进行评估。对于 RoomFormer，我们直接下载了模型检查点。SceneScript 和 SpatialLM 先在我们的数据集上进行了训练，随后又在 Structured3D 上进行了进一步微调。

我们感谢 @chinmay0301ucsd 发现并修复了评估脚本中的一个错误 #88，该错误影响了门和窗户的指标。因此，本次得分比之前报告的更高。

3D 物体检测

我们使用带有 18 类物体标注的 ScanNet 数据集对 3D 物体检测任务进行了评估。对于 V-DETR，我们直接下载了模型检查点。SceneScript 和 SpatialLM 先在我们的数据集上进行了训练，随后又在 ScanNet 上进行了微调。

视频中的零样本检测

在具有挑战性的 SpatialLM 测试集上的零样本检测结果如下表所示：

结果可视化

许可证

SpatialLM-Llama-1B 是基于 Llama3.2-1B-Instruct 构建的，该模型受 Llama3.2 许可证的约束。SpatialLM-Qwen-0.5B 则基于 Qwen-2.5 系列构建，最初受 Apache 2.0 许可证的保护。

SpatialLM1.0 是基于 SceneScript 点云编码器构建的，该编码器受 CC-BY-NC-4.0 许可证的保护。本项目中使用的 TorchSparse 受 MIT 许可证的保护。

SpatialLM1.1 是基于 Sonata 点云编码器构建的，其模型权重受 CC-BY-NC-4.0 许可证的保护。而基于 Pointcept 构建的代码则受 Apache 2.0 许可证的保护。

引用

如果您认为这项工作对您有所帮助，请考虑引用以下内容：

@inproceedings{SpatialLM,
  title     = {SpatialLM: Training Large Language Models for Structured Indoor Modeling},
  author    = {Mao, Yongsen and Zhong, Junhao and Fang, Chuan and Zheng, Jia and Tang, Rui and Zhu, Hao and Tan, Ping and Zhou, Zihan},
  booktitle = {Advances in Neural Information Processing Systems},
  year      = {2025}
}

致谢

我们衷心感谢以下项目为本研究提供了支持：

Llama3.2 | Qwen2.5 | Transformers | SceneScript | TorchSparse | Sonata | Pointcept

SpatialLM 快速上手指南

SpatialLM 是一款专为处理 3D 点云数据设计的大型语言模型，能够生成结构化的 3D 场景理解输出（如墙体、门窗、带语义类别的定向边界框）。它支持来自单目视频、RGBD 图像和 LiDAR 等多种来源的点云数据。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐)
• Python: 3.11
• PyTorch: 2.4.1
• CUDA: 12.4
• 硬件: 支持 CUDA 的 NVIDIA GPU

注意：本项目依赖特定的 CUDA 版本和稀疏计算库，建议严格按照以下步骤配置环境以避免兼容性问题。

安装步骤

1. 克隆仓库

git clone https://github.com/manycore-research/SpatialLM.git
cd SpatialLM

2. 创建 Conda 环境

创建名为 spatiallm 的环境并安装基础依赖（包含 CUDA 12.4 工具包）：

conda create -n spatiallm python=3.11
conda activate spatiallm
conda install -y -c nvidia/label/cuda-12.4.0 cuda-toolkit conda-forge::sparsehash

3. 安装项目依赖

使用 poetry 管理依赖，并根据您想使用的模型版本安装特定组件：

# 安装 poetry 并配置不使用虚拟环境（在当前 conda 环境中安装）
pip install poetry && poetry config virtualenvs.create false --local
poetry install

# 根据需求选择安装以下其中一个依赖包：

# 选项 A: 如果您使用 SpatialLM 1.0 系列模型
poe install-torchsparse 
# 注意：编译 torchsparse 可能需要较长时间

# 选项 B: 如果您使用最新的 SpatialLM 1.1 系列模型 (推荐)
poe install-sonata 
# 注意：编译 flash-attn 可能需要较长时间

基本使用

以下示例展示如何使用 SpatialLM1.1-Qwen-0.5B 模型对单个点云文件进行推理。

1. 下载测试数据

从 Hugging Face 下载示例点云文件：

huggingface-cli download manycore-research/SpatialLM-Testset pcd/scene0000_00.ply --repo-type dataset --local-dir .

2. 运行推理

执行推理命令，模型将分析点云并输出结构化布局信息：

python inference.py --point_cloud pcd/scene0000_00.ply --output scene0000_00.txt --model_path manycore-research/SpatialLM1.1-Qwen-0.5B

3. (可选) 指定类别检测

SpatialLM1.1 支持用户指定需要检测的对象类别。例如，仅检测 "bed" (床) 和 "nightstand" (床头柜)：

python inference.py --point_cloud pcd/scene0000_00.ply --output scene0000_00.txt --model_path manycore-research/SpatialLM1.1-Qwen-0.5B --detect_type object --category bed nightstand

4. 可视化结果

使用 rerun 工具查看原始点云与预测的结构化 3D 布局：

# 将预测结果转换为 Rerun 格式
python visualize.py --point_cloud pcd/scene0000_00.ply --layout scene0000_00.txt --save scene0000_00.rrd

# 启动可视化界面
rerun scene0000_00.rrd

提示：输入的点云默认应为轴对齐格式，其中 Z 轴 为向上方向。如果使用的是自定义视频重建的点云，请确保坐标系方向一致。