{"id":15029442,"url":"https://github.com/one-2-3-45/one-2-3-45","last_synced_at":"2025-05-15T20:07:06.472Z","repository":{"id":177101792,"uuid":"659938722","full_name":"One-2-3-45/One-2-3-45","owner":"One-2-3-45","description":"[NeurIPS 2023] Official code of \"One-2-3-45: Any Single Image to 3D Mesh in 45 Seconds without Per-Shape Optimization\"","archived":false,"fork":false,"pushed_at":"2024-04-20T23:15:25.000Z","size":6500,"stargazers_count":1649,"open_issues_count":19,"forks_count":99,"subscribers_count":72,"default_branch":"master","last_synced_at":"2025-05-15T20:06:10.015Z","etag":null,"topics":["3d","3d-generation","3d-shape-generation","aigc","generalizable-nerf","mesh-generation","multi-view-reconstruction","nerf"],"latest_commit_sha":null,"homepage":"http://one-2-3-45.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/One-2-3-45.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-28T22:38:29.000Z","updated_at":"2025-05-12T05:46:45.000Z","dependencies_parsed_at":"2023-11-19T01:29:50.199Z","dependency_job_id":"fc564aeb-aacf-4e80-bc66-ab289c6ef4a8","html_url":"https://github.com/One-2-3-45/One-2-3-45","commit_stats":null,"previous_names":["one-2-3-45/one-2-3-45"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-2-3-45%2FOne-2-3-45","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-2-3-45%2FOne-2-3-45/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-2-3-45%2FOne-2-3-45/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-2-3-45%2FOne-2-3-45/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/One-2-3-45","download_url":"https://codeload.github.com/One-2-3-45/One-2-3-45/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414501,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","3d-generation","3d-shape-generation","aigc","generalizable-nerf","mesh-generation","multi-view-reconstruction","nerf"],"created_at":"2024-09-24T20:10:40.795Z","updated_at":"2025-05-15T20:07:01.288Z","avatar_url":"https://github.com/One-2-3-45.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\" width=\"100%\"\u003e\n\u003cimg src=\"https://github.com/Dustinpro/Dustinpro/assets/23076389/0fbdb69a-0fb4-4b42-b9da-e0b28532bdfd\"  width=\"80%\" height=\"80%\"\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  [\u003ca href=\"https://arxiv.org/pdf/2306.16928.pdf\"\u003e\u003cstrong\u003ePaper\u003c/strong\u003e\u003c/a\u003e]\n  [\u003ca href=\"http://one-2-3-45.com\"\u003e\u003cstrong\u003eProject\u003c/strong\u003e\u003c/a\u003e]\n  [\u003ca href=\"https://huggingface.co/spaces/One-2-3-45/One-2-3-45\"\u003e\u003cstrong\u003eDemo\u003c/strong\u003e\u003c/a\u003e]\n  [\u003ca href=\"#citation\"\u003e\u003cstrong\u003eBibTeX\u003c/strong\u003e\u003c/a\u003e]\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://huggingface.co/spaces/One-2-3-45/One-2-3-45\"\u003e\n    \u003cimg alt=\"Hugging Face Spaces\" src=\"https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Space_of_the_Week_%F0%9F%94%A5-blue\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nOne-2-3-45 rethinks how to leverage 2D diffusion models for 3D AIGC and introduces a novel forward-only paradigm that avoids time-consuming optimization.\n\nhttps://github.com/One-2-3-45/One-2-3-45/assets/16759292/a81d6e32-8d29-43a5-b044-b5112b9f9664\n\n\n\nhttps://github.com/One-2-3-45/One-2-3-45/assets/16759292/5ecd45ef-8fd3-4643-af4c-fac3050a0428\n\n\n## News\n**[11/14/2023]**\nCheck out our new work [One-2-3-45++](https://sudo-ai-3d.github.io/One2345plus_page/)!\n\n**[10/25/2023]**\nWe released [rendering scripts](render/) for evaluation and [APIs](https://github.com/One-2-3-45/One-2-3-45#apis) for effortless inference.\n\n**[09/21/2023]**\nOne-2-3-45 is accepted by NeurIPS 2023. See you in New Orleans!\n\n**[09/11/2023]**\nTraining code released.\n\n**[08/18/2023]**\nInference code released.\n\n**[07/24/2023]**\nOur demo reached the HuggingFace top 4 trending and was featured in 🤗 Spaces of the Week 🔥! Special thanks to HuggingFace 🤗 for sponsoring this demo!!\n\n**[07/11/2023]**\n[Online interactive demo](https://huggingface.co/spaces/One-2-3-45/One-2-3-45) released! Explore it and create your own 3D models in just 45 seconds! \n\n**[06/29/2023]**\nCheck out our [paper](https://arxiv.org/pdf/2306.16928.pdf). [[X](https://twitter.com/_akhaliq/status/1674617785119305728)]\n\n## Installation\nHardware requirement: an NVIDIA GPU with memory \u003e=18GB (_e.g._, RTX 3090 or A10). Tested on Ubuntu.\n\nWe offer two ways to set up the environment:\n\n### Traditional Installation\n\u003cdetails\u003e\n\u003csummary\u003eStep 1: Install Debian packages. \u003c/summary\u003e \n\n```bash\nsudo apt update \u0026\u0026 sudo apt install git-lfs libsparsehash-dev build-essential\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eStep 2: Create and activate a conda environment. \u003c/summary\u003e\n\n```bash\nconda create -n One2345 python=3.10\nconda activate One2345\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eStep 3: Clone the repository to the local machine. \u003c/summary\u003e\n\n```bash\n# Make sure you have git-lfs installed.\ngit lfs install\ngit clone https://github.com/One-2-3-45/One-2-3-45\ncd One-2-3-45\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eStep 4: Install project dependencies using pip. \u003c/summary\u003e\n\n```bash\n# Ensure that the installed CUDA version matches the torch's CUDA version.\n# Example: CUDA 11.8 installation\nwget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run\nsudo sh cuda_11.8.0_520.61.05_linux.run\nexport PATH=\"/usr/local/cuda-11.8/bin:$PATH\"\nexport LD_LIBRARY_PATH=\"/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH\"\n# Install PyTorch 2.0.1\npip install --no-cache-dir torch==2.0.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118\n# Install dependencies\npip install -r requirements.txt\n# Install inplace_abn and torchsparse\nexport TORCH_CUDA_ARCH_LIST=\"7.0;7.2;8.0;8.6+PTX\" # CUDA architectures. Modify according to your hardware.\nexport IABN_FORCE_CUDA=1\npip install inplace_abn\nFORCE_CUDA=1 pip install --no-cache-dir git+https://github.com/mit-han-lab/torchsparse.git@v1.4.0\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eStep 5: Download model checkpoints. \u003c/summary\u003e\n\n```bash\npython download_ckpt.py\n```\n\u003c/details\u003e\n\n\n### Installation by Docker Images\n\u003cdetails\u003e\n\u003csummary\u003eOption 1: Pull and Play (environment and checkpoints). (~22.3G)\u003c/summary\u003e \n\n```bash\n# Pull the Docker image that contains the full repository.\ndocker pull chaoxu98/one2345:demo_1.0\n# An interactive demo will be launched automatically upon running the container.\n# This will provide a public URL like XXXXXXX.gradio.live\ndocker run --name One-2-3-45_demo --gpus all -it chaoxu98/one2345:demo_1.0\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eOption 2: Environment Only. (~7.3G)\u003c/summary\u003e \n\n```bash\n# Pull the Docker image that installed all project dependencies.\ndocker pull chaoxu98/one2345:1.0\n# Start a Docker container named One2345.\ndocker run --name One-2-3-45 --gpus all -it chaoxu98/one2345:1.0\n# Get a bash shell in the container.\ndocker exec -it One-2-3-45 /bin/bash\n# Clone the repository to the local machine.\ngit clone https://github.com/One-2-3-45/One-2-3-45\ncd One-2-3-45\n# Download model checkpoints. \npython download_ckpt.py\n# Refer to getting started for inference.\n```\n\u003c/details\u003e\n\n## Getting Started (Inference)\n\nFirst-time running will take a longer time to compile the models.\n\nExpected time cost per image: 40s on an NVIDIA A6000.\n```bash\n# 1. Script\npython run.py --img_path PATH_TO_INPUT_IMG --half_precision\n\n# 2. Interactive demo (Gradio) with a friendly web interface\n#    A URL will be provided in the output \n#    (Local: 127.0.0.1:7860; Public: XXXXXXX.gradio.live)\ncd demo/\npython app.py\n\n# 3. Jupyter Notebook\nexample.ipynb\n```\n\n\n## APIs\n\nWe provide handy Gradio APIs for our pipeline and its components, making it effortless to accurately preprocess in-the-wild or text-generated images and reconstruct 3D meshes from them.\n\n\u003cdetails\u003e\n\u003csummary\u003eTo begin, initialize the Gradio Client with the API URL.\u003c/summary\u003e\n\n```python\nfrom gradio_client import Client\nclient = Client(\"https://one-2-3-45-one-2-3-45.hf.space/\")\n# example input image\ninput_img_path = \"https://huggingface.co/spaces/One-2-3-45/One-2-3-45/resolve/main/demo_examples/01_wild_hydrant.png\"\n```\n\u003c/details\u003e\n\n### Single image to 3D mesh\n```python\ngenerated_mesh_filepath = client.predict(\n\tinput_img_path,\t\n\tTrue,\t\t# image preprocessing\n\tapi_name=\"/generate_mesh\"\n)\n```\n### Elevation estimation \n\nIf the input image's pose (elevation) is unknown, this off-the-shelf algorithm is all you need!\n\n```python\nelevation_angle_deg = client.predict(\n\tinput_img_path,\n\tTrue,\t\t# image preprocessing\n\tapi_name=\"/estimate_elevation\"\n)\n```\n\n### Image preprocessing: segment, rescale, and recenter\n\nWe adapt the Segment Anything model (SAM) for background removal.\n\n```python\nsegmented_img_filepath = client.predict(\n\tinput_img_path,\t\n\tapi_name=\"/preprocess\"\n)\n```\n\n\n\n## Training Your Own Model\n\n### Data Preparation\nWe use the Objaverse-LVIS dataset for training and render the selected shapes (with a CC-BY license) into 2D images with Blender. \n#### Download the training images.\nDownload all One2345.zip.part-* files (5 files in total) from \u003ca href=\"https://huggingface.co/datasets/One-2-3-45/training_data/tree/main\"\u003ehere\u003c/a\u003e and then cat them into a single .zip file using the following command:\n```bash\ncat One2345.zip.part-* \u003e One2345.zip\n```\n\n#### Unzip the training images zip file.\nUnzip the zip file into a folder specified by yourself (`YOUR_BASE_FOLDER`) with the following command:\n\n```bash\nunzip One2345.zip -d YOUR_BASE_FOLDER\n```\n\n#### Download meta files.\n\nDownload `One2345_training_pose.json` and `lvis_split_cc_by.json` from \u003ca href=\"https://huggingface.co/datasets/One-2-3-45/training_data/tree/main\"\u003ehere\u003c/a\u003e and put them into the same folder as the training images (`YOUR_BASE_FOLDER`).\n\nYour file structure should look like this:\n```\n# One2345 is your base folder used in the previous steps\n\nOne2345\n├── One2345_training_pose.json\n├── lvis_split_cc_by.json\n└── zero12345_narrow\n    ├── 000-000\n    ├── 000-001\n    ├── 000-002\n    ...\n    └── 000-159\n    \n```\n\n### Training\nSpecify the `trainpath`, `valpath`, and `testpath` in the config file `./reconstruction/confs/one2345_lod_train.conf` to be `YOUR_BASE_FOLDER` used in data preparation steps and run the following command:\n```bash\ncd reconstruction\npython exp_runner_generic_blender_train.py --mode train --conf confs/one2345_lod_train.conf\n```\nExperiment logs and checkpoints will be saved in `./reconstruction/exp/`.\n\n## Related Work\n[\\[One-2-3-45++\\]](https://sudo-ai-3d.github.io/One2345plus_page/)\n\n[\\[Zero123++\\]](https://github.com/SUDO-AI-3D/zero123plus)\n\n[\\[Zero123\\]](https://github.com/cvlab-columbia/zero123)\n\n## Citation\n\nIf you find our code helpful, please cite our paper:\n\n```\n@article{liu2023one2345,\n  title={One-2-3-45: Any single image to 3d mesh in 45 seconds without per-shape optimization},\n  author={Liu, Minghua and Xu, Chao and Jin, Haian and Chen, Linghao and Varma T, Mukund and Xu, Zexiang and Su, Hao},\n  journal={Advances in Neural Information Processing Systems},\n  volume={36},\n  year={2024}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fone-2-3-45%2Fone-2-3-45","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fone-2-3-45%2Fone-2-3-45","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fone-2-3-45%2Fone-2-3-45/lists"}