sam-3d-objects README

The project's README from github.com/facebookresearch/sam-3d-objects. As one markdown file: README.md.

SAM 3D

SAM 3D Objects is one part of SAM 3D, a pair of models for object and human mesh reconstruction. If you’re looking for SAM 3D Body, click here.

SAM 3D Objects

SAM 3D Team, Xingyu Chen*, Fu-Jen Chu*, Pierre Gleize*, Kevin J Liang*, Alexander Sax*, Hao Tang*, Weiyao Wang*, Michelle Guo, Thibaut Hardin, Xiang Li⚬, Aohan Lin, Jia-Wei Liu, Ziqi Ma⚬, Anushka Sagar, Bowen Song⚬, Xiaodong Wang, Jianing Yang⚬, Bowen Zhang⚬, Piotr Dollár†, Georgia Gkioxari†, Matt Feiszli†§, Jitendra Malik†§

Meta Superintelligence Labs

*Core contributor (Alphabetical, Equal Contribution), ⚬Intern, †Project leads, §Equal Contribution

[Paper] [Code] [Website] [Demo] [Blog] [BibTeX] [Roboflow]

SAM 3D Objects is a foundation model that reconstructs full 3D shape geometry, texture, and layout from a single image, excelling in real-world scenarios with occlusion and clutter by using progressive training and a data engine with human feedback. It outperforms prior 3D generation models in human preference tests on real-world objects and scenes. We released code, weights, online demo, and a new challenging benchmark.

Latest updates

Installation

Follow the setup steps before running the following.

Single or Multi-Object 3D Generation

SAM 3D Objects can convert masked objects in an image, into 3D models with pose, shape, texture, and layout. SAM 3D is designed to be robust in challenging natural images, handling small objects and occlusions, unusual poses, and difficult situations encountered in uncurated natural scenes like this kidsroom:

For a quick start, run python demo.py or use the the following lines of code:

import sys

# import inference code
sys.path.append("notebook")
from inference import Inference, load_image, load_single_mask

# load model
tag = "hf"
config_path = f"checkpoints/{tag}/pipeline.yaml"
inference = Inference(config_path, compile=False)

# load image and mask
image = load_image("notebook/images/shutterstock_stylish_kidsroom_1640806567/image.png")
mask = load_single_mask("notebook/images/shutterstock_stylish_kidsroom_1640806567", index=14)

# run model
output = inference(image, mask, seed=42)

# export gaussian splat
output["gs"].save_ply(f"splat.ply")

For more details and multi-object reconstruction, please take a look at out two jupyter notebooks:

SAM 3D Body

SAM 3D Body (3DB) is a robust promptable foundation model for single-image 3D human mesh recovery (HMR).

As a way to combine the strengths of both SAM 3D Objects and SAM 3D Body, we provide an example notebook that demonstrates how to combine the results of both models such that they are aligned in the same frame of reference. Check it out here.

License

The SAM 3D Objects model checkpoints and code are licensed under SAM License.

Contributing

See contributing and the code of conduct.

Contributors

The SAM 3D Objects project was made possible with the help of many contributors.

Robbie Adkins, Paris Baptiste, Karen Bergan, Kai Brown, Michelle Chan, Ida Cheng, Khadijat Durojaiye, Patrick Edwards, Daniella Factor, Facundo Figueroa, Rene de la Fuente, Eva Galper, Cem Gokmen, Alex He, Enmanuel Hernandez, Dex Honsa, Leonna Jones, Arpit Kalla, Kris Kitani, Helen Klein, Kei Koyama, Robert Kuo, Vivian Lee, Alex Lende, Jonny Li, Kehan Lyu, Faye Ma, Mallika Malhotra, Sasha Mitts, William Ngan, George Orlin, Peter Park, Don Pinkus, Roman Radle, Nikhila Ravi, Azita Shokrpour, Jasmine Shone, Zayida Suber, Phillip Thomas, Tatum Turner, Joseph Walker, Meng Wang, Claudette Ward, Andrew Westbury, Lea Wilken, Nan Yang, Yael Yungster

Citing SAM 3D Objects

If you use SAM 3D Objects in your research, please use the following BibTeX entry.

@article{sam3dteam2025sam3d3dfyimages,
      title={SAM 3D: 3Dfy Anything in Images}, 
      author={SAM 3D Team and Xingyu Chen and Fu-Jen Chu and Pierre Gleize and Kevin J Liang and Alexander Sax and Hao Tang and Weiyao Wang and Michelle Guo and Thibaut Hardin and Xiang Li and Aohan Lin and Jiawei Liu and Ziqi Ma and Anushka Sagar and Bowen Song and Xiaodong Wang and Jianing Yang and Bowen Zhang and Piotr Dollár and Georgia Gkioxari and Matt Feiszli and Jitendra Malik},
      year={2025},
      eprint={2511.16624},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2511.16624}, 
}

sam-3d-objects (facebookresearch/sam-3d-objects)

Searching Database…

7.5K ·GitHub
Sam-3d-objects
Что это такое?SAM 3D Objects — это базовая модель от Meta, которая по одному 2D-изображению восстанавливает полную 3D-геометрию формы, текстуру и расположение объекта, даже в загромождённых реальных сценах с перекрытием объектов.
Это модель, которую я запускаю сам, или просто онлайн-демо?Это открытый исследовательский код и файлы весов модели, которые вы запускаете сами (через скрипт или блокноты), а также онлайн-демо и бенчмарк, выпущенные вместе с ней. Это одна из двух моделей пары SAM 3D, вторая — SAM 3D Body для восстановления 3D-сетки тела человека.
Как попробовать на своём изображении?После выполнения шагов настройки запустите `python demo.py` или откройте блокноты Jupyter для одного и нескольких объектов, которые входят в репозиторий и позволяют подробнее разобрать процесс реконструкции.
Что нужно установить перед запуском?В README указаны отдельные шаги настройки, которые нужно выполнить перед запуском скрипта демо или блокнотов, но точный список зависимостей в этом фрагменте не приведён.
Можно ли использовать код в коммерческих целях бесплатно?Файлы весов модели и код выпущены по собственной лицензии «SAM License», а не по стандартной открытой лицензии вроде MIT или Apache, поэтому условия использования отличаются от типичных разрешительных лицензий.
Для кого это создано?Инструмент рассчитан на исследователей и инженеров в области компьютерного зрения и робототехники, которым нужна 3D-реконструкция объектов по одному изображению. Об этом говорят бенчмарк, таблица лидеров и обширный список академических цитирований.
Как SAM 3D Objects связан с SAM 3D Body?Это пара моделей из одного проекта: SAM 3D Objects восстанавливает объекты, а SAM 3D Body отвечает за восстановление 3D-сетки человека. В репозитории есть блокнот, который показывает, как совместить результаты обеих моделей в одной системе координат.
Чем SAM 3D Objects лучше предыдущих моделей 3D-генерации?Модель использует поэтапное обучение и конвейер сбора данных с человеческой обратной связью. По результатам тестов человеческих предпочтений она превосходит предыдущие модели 3D-генерации именно на реальных объектах и сценах, а не на чистых студийных снимках.
Может ли она обработать несколько объектов на одном изображении?Да, есть отдельный блокнот Jupyter для нескольких объектов, которые выделены масками на одном изображении, в дополнение к рабочему процессу для одного объекта.
Можно ли проверить или сравнить результаты?Проект включает сложный бенчмарк и, по состоянию на последнее обновление, набор объектов 3D Artist Object Set с таблицей лидеров на Hugging Face для сравнения результатов моделей.
What are similar projects?ml-sharp, WorldSculpt, vggt, Mira-Scene, pointdit, wuji-ego-mint, InsertAny3D, shap-e
Which topics is it in?meta, image-to-3d, demo, 3d-reconstruction, foundation-models, jupyter-notebook, paper, robotics, 3d, academic-research, generative-ai, computer-vision
Creator
facebookresearch
Size
268 MB
Stars
7.5K
Updated
CommitJun 02
Age
1y
Commits · 90 Days