{"id":24105920,"url":"https://github.com/stability-ai/stable-point-aware-3d","last_synced_at":"2025-05-15T09:02:45.699Z","repository":{"id":271670469,"uuid":"897759542","full_name":"Stability-AI/stable-point-aware-3d","owner":"Stability-AI","description":"SPAR3D: Stable Point-Aware Reconstruction of 3D Objects from Single Images","archived":false,"fork":false,"pushed_at":"2025-02-11T16:22:46.000Z","size":29153,"stargazers_count":757,"open_issues_count":32,"forks_count":74,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-04-07T08:09:15.925Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://spar3d.github.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stability-AI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-12-03T07:32:10.000Z","updated_at":"2025-04-05T02:55:44.000Z","dependencies_parsed_at":"2025-02-22T15:32:09.442Z","dependency_job_id":null,"html_url":"https://github.com/Stability-AI/stable-point-aware-3d","commit_stats":null,"previous_names":["stability-ai/stable-point-aware-3d"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stability-AI%2Fstable-point-aware-3d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stability-AI%2Fstable-point-aware-3d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stability-AI%2Fstable-point-aware-3d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stability-AI%2Fstable-point-aware-3d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stability-AI","download_url":"https://codeload.github.com/Stability-AI/stable-point-aware-3d/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248901561,"owners_count":21180449,"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":[],"created_at":"2025-01-10T21:16:33.768Z","updated_at":"2025-04-14T14:54:37.384Z","avatar_url":"https://github.com/Stability-AI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SPAR3D: Stable Point-Aware Reconstruction of 3D Objects from Single Images\n\n\u003ca href=\"https://arxiv.org/abs/2501.04689\"\u003e\u003cimg src=\"https://img.shields.io/badge/Arxiv-2501.04689-B31B1B.svg\"\u003e\u003c/a\u003e \u003ca href=\"https://huggingface.co/stabilityai/stable-point-aware-3d\"\u003e\u003cimg src=\"https://img.shields.io/badge/%F0%9F%A4%97%20Model_Card-Huggingface-orange\"\u003e\u003c/a\u003e \u003ca href=\"https://huggingface.co/spaces/stabilityai/stable-point-aware-3d\"\u003e\u003cimg src=\"https://img.shields.io/badge/%F0%9F%A4%97%20Gradio%20Demo-Huggingface-orange\"\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"demo_files/turntable.gif\" alt=\"Teaser\"\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\nThis is the official codebase for **SPAR3D**, a state-of-the-art open-source model for **fast** feedforward 3D mesh reconstruction from a single image using a point cloud conditioning to improve the quality of the reconstruction.\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg width=\"450\" src=\"demo_files/comp.gif\"/\u003e\n\u003c/p\u003e\n\nSPAR3D is based on [Stable Fast 3D](https://github.com/Stability-AI/stable-fast-3d) but improves upon the backside of the mesh by conditioning on a point cloud. This point cloud can be generated from an image using our included point cloud denoising model. This point cloud can even be edited easily in external tools or our included gradio demo. With that missing backside details can be fixed. We further improve the prediction quality of materials using novel contributions. We achieve all of this while still maintaining the fast inference speeds.\n\n## Getting Started\n\n### Installation\n\nEnsure your environment is:\n- Python \u003e= 3.8 (Depending on PyTorch version \u003e3.9)\n- Optional: CUDA or MPS has to be available\n- For Windows **(experimental)**: Visual Studio 2022\n- For Mac (MPS) **(experimental)**: OSX 15.2 (Sequoia) and above\n- Has PyTorch installed according to your platform: https://pytorch.org/get-started/locally/ [Make sure the Pytorch CUDA version matches your system's.]\n- Update setuptools by `pip install -U setuptools==69.5.1`\n- Install wheel by `pip install wheel`\n\nThen, install the remaining requirements with `pip install -r requirements.txt`.\nIf remeshing is required, install the additional requirements with `pip install -r requirements-remesh.txt`.\nFor the gradio demo, an additional `pip install -r requirements-demo.txt` is required.\n\n### Requesting Access and Login\n\nOur model is gated at [Hugging Face](https://huggingface.co):\n\n1. Log in to Hugging Face and request access [here](https://huggingface.co/stabilityai/stable-point-aware-3d).\n2. Create an access token with read permissions [here](https://huggingface.co/settings/tokens).\n3. Run `huggingface-cli login` in the environment and enter the token.\n\n### Low VRAM Mode\n\nTo run SPAR3D with low VRAM mode, set the environment variable `SPAR3D_LOW_VRAM=1`. By default, SPAR3D consumes 10.5GB of VRAM. This mode will reduce the VRAM consumption to roughly 7GB but in exchange the model will be slower. The `run.py` script also supports the `--low-vram-mode` flag.\n\n### Windows Support **(experimental)**\n\nTo run Stable Fast 3D on Windows, you must install Visual Studio (currently tested on VS 2022) and the appropriate PyTorch and CUDA versions.\nThen, follow the installation steps as mentioned above.\n\nNote that Windows support is **experimental** and not guaranteed to give the same performance and/or quality as Linux.\n\n### Support for MPS (for Mac Silicon) **(experimental)**\n\nStable Fast 3D can also run on Macs via the MPS backend, with the texture baker using custom metal kernels similar to the corresponding CUDA kernels.\n\nSupport is only available for OSX 15.2 (Sequoia) and above.\n\nNote that support is **experimental** and not guaranteed to give the same performance and/or quality as the CUDA backend.\n\nMPS backend support was tested on M4 max 36GB with the latest PyTorch release and OSX 15.2 (Sequoia). We recommend you install the latest PyTorch (2.5.1 as of writing) and/or the nightly version to avoid any issues that my arise with older PyTorch versions.\n\nYou also need to run the code with `PYTORCH_ENABLE_MPS_FALLBACK=1`.\n\nMPS currently consumes more memory compared to the CUDA PyTorch backend. We recommend running the CPU version if your system has less than 32GB of unified memory.\n\n### CPU Support\n\nCPU backend will automatically be used if no GPU is detected in your system. Note that this will be really slow.\n\nIf you have a GPU but are facing issues and want to use the CPU backend instead, set the environment variable `SPAR3D_USE_CPU=1` to force the CPU backend. The `run.py` script also supports the `--device=cpu` flag.\n\n### Manual Inference\n\n```sh\npython run.py demo_files/examples/fish.png --output-dir output/\n```\nThis will save the reconstructed 3D model as a GLB file to `output/`. You can also specify more than one image path separated by spaces. The default options takes about **6GB VRAM** for a single image input.\n\nYou may also use `--texture-resolution` to specify the resolution in pixels of the output texture and `--remesh_option` to specify the remeshing operation (None, Triangle, Quad).\n\nFor detailed usage of this script, use `python run.py --help`.\n\n### Local Gradio App\n\n```sh\npython gradio_app.py\n```\n\n\n## ComfyUI extension\n\nCustom nodes and an [example workflow](./demo_files/workflows/spar3d_example.json) are provided for [ComfyUI](https://github.com/comfyanonymous/ComfyUI).\n\nTo install:\n\n* Clone this repo into ```custom_nodes```:\n ```shell\n  $ cd ComfyUI/custom_nodes\n  $ git clone https://github.com/Stability-AI/stable-point-aware-3d\n ```\n* Install dependencies:\n ```shell\n  $ cd stable-point-aware-3d\n  $ pip install -r requirements.txt\n ```\n* Optional for remeshing:\n ```shell\n  $ pip install -r requirements-remesh.txt\n ```\n* Restart ComfyUI\n\n## Remesher Options:\n\n  -`none`: mesh unchanged after generation. No CPU overhead.\n\n  -`triangle`: verticies and edges are rearranged to form a triangle topography. Implementation is from: *\"[A Remeshing Approach to Multiresolution Modeling](https://github.com/sgsellan/botsch-kobbelt-remesher-libigl)\" by M. Botsch and L. Kobbelt*. CPU overhead expected.\n\n  -`quad`: verticies and edges are rearanged in quadrilateral topography with a proper quad flow. The quad mesh is split into triangles for export with GLB. Implementation is from *\"[Instant Field-Aligned Meshes](https://github.com/wjakob/instant-meshes)\" from Jakob et al.*. CPU overhead expected.\n\nAdditionally the target vertex or face count can be specified. This is not a hard constraint but a rough count the method aims to create. This target is ignored if the remesher is set to `none`.\n\n## Citation\n```BibTeX\n@article{spar3d2025,\n  title={{SPAR3D}: Stable Point-Aware Reconstruction of {3D} Objects from Single Images},\n  author={Huang, Zixuan and Boss, Mark and Vasishta, Aaryaman and Rehg, James Matthew and Jampani, Varun},\n  journal={arXiv preprint},\n  year={2025}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstability-ai%2Fstable-point-aware-3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstability-ai%2Fstable-point-aware-3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstability-ai%2Fstable-point-aware-3d/lists"}