{"id":34935983,"url":"https://github.com/jkulhanek/tetra-nerf","last_synced_at":"2025-12-26T18:06:50.931Z","repository":{"id":153802705,"uuid":"612205080","full_name":"jkulhanek/tetra-nerf","owner":"jkulhanek","description":"Official implementation for Tetra-NeRF paper - NeRF represented as triangulation of input point cloud.","archived":false,"fork":false,"pushed_at":"2023-11-24T09:49:55.000Z","size":1316,"stargazers_count":228,"open_issues_count":1,"forks_count":11,"subscribers_count":8,"default_branch":"master","last_synced_at":"2023-11-24T15:44:27.715Z","etag":null,"topics":["3d","3d-reconstruction","computer-vision","nerf","nerfstudio","neural-networks","optix","pytorch","raytracing"],"latest_commit_sha":null,"homepage":"https://jkulhanek.com/tetra-nerf","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jkulhanek.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}},"created_at":"2023-03-10T12:30:18.000Z","updated_at":"2023-11-24T15:44:27.715Z","dependencies_parsed_at":"2023-11-15T10:39:51.601Z","dependency_job_id":null,"html_url":"https://github.com/jkulhanek/tetra-nerf","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/jkulhanek/tetra-nerf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkulhanek%2Ftetra-nerf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkulhanek%2Ftetra-nerf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkulhanek%2Ftetra-nerf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkulhanek%2Ftetra-nerf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jkulhanek","download_url":"https://codeload.github.com/jkulhanek/tetra-nerf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkulhanek%2Ftetra-nerf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28057680,"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","status":"online","status_checked_at":"2025-12-26T02:00:06.189Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-reconstruction","computer-vision","nerf","nerfstudio","neural-networks","optix","pytorch","raytracing"],"created_at":"2025-12-26T18:06:00.784Z","updated_at":"2025-12-26T18:06:50.925Z","avatar_url":"https://github.com/jkulhanek.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tetra-NeRF\nOfficial implementation of **Tetra-NeRF paper**\n\n### [Project Page](https://jkulhanek.com/tetra-nerf) | [Paper](https://arxiv.org/pdf/2304.09987.pdf) | [Demo](https://jkulhanek.com/tetra-nerf/demo.html)\u003cbr\u003e\n[Tetra-NeRF: Representing Neural Radiance Fields Using Tetrahedra](https://jkulhanek.com/tetra-nerf)\u003cbr\u003e\n*[Jonas Kulhanek](https://jkulhanek.com)\u003csup\u003e1\u003c/sup\u003e, [Torsten Sattler](https://tsattler.github.io/)\u003csup\u003e1\u003c/sup\u003e*\u003cbr\u003e\n***ICCV 2023***\u003cbr\u003e\n\u003csup\u003e1\u003c/sup\u003e Czech Technical University in Prague\u003cbr\u003e\n\n![method overview](https://jkulhanek.com/tetra-nerf/resources/overview-white.svg)\u003cbr\u003e\nThe input to Tetra-NeRF is a point cloud which is triangulated to get a set of tetrahedra used to represent the radiance field. Rays are sampled, and the field is queried. The barycentric interpolation is used to interpolate tetrahedra vertices, and the resulting features are passed to a shallow MLP to get the density and colours for volumetric rendering.\u003cbr\u003e\n\n[![demo blender lego (sparse)](https://jkulhanek.com/tetra-nerf/resources/images/blender-lego-sparse-100k-animated-cover.gif)](https://jkulhanek.com/tetra-nerf/demo.html?scene=blender-lego-sparse)\n[![demo mipnerf360 garden (sparse)](https://jkulhanek.com/tetra-nerf/resources/images/360-garden-sparse-100k-animated-cover.gif)](https://jkulhanek.com/tetra-nerf/demo.html?scene=360-garden-sparse)\n[![demo mipnerf360 garden (sparse)](https://jkulhanek.com/tetra-nerf/resources/images/360-bonsai-sparse-100k-animated-cover.gif)](https://jkulhanek.com/tetra-nerf/demo.html?scene=360-bonsai-sparse)\n[![demo mipnerf360 kitchen (dense)](https://jkulhanek.com/tetra-nerf/resources/images/360-kitchen-dense-300k-animated-cover.gif)](https://jkulhanek.com/tetra-nerf/demo.html?scene=360-kitchen-dense)\n\n\u003cbr\u003e\n\n**UPDATE!**\nTetra-NeRF is now faster and achieves better performance thanks to using biased sampling instead of sampling uniformly along the ray.\nThe configuration from the paper was renamed to `tetra-nerf-original`. And `tetra-nerf` now points to the new configuration.\n\n## Introduction\nFirst, install **Tetra-NeRF**. The instructions are given in the [installation](#installation) section.\nIf you want to reproduce the results from the paper, please follow the [reproducing results section](#reproducing-results) which\nwill instruct you on how to download the data and run the training. We also publish the generated images.\n\nIf you want to use **Tetra-NeRF** with your own collected data, please follow the [using custom data section](#using-custom-data).\n\n## Using custom data\nWhen training on your own images, first you need the COLMAP model for camera poses and sparse point cloud.\nYou can run COLMAP yourself or use our script with default COLMAP parameters to build the model.\nFirst prepare a folder with your data. In the folder, a subfolder called `images` and copy all your images\ninto that folder.\n\n### Without existing COLMAP model\nSimply run the following:\n```bash\npython -m tetranerf.scripts.process_images --path \u003cdata folder\u003e\n```\nThis command will create a single sparse COLMAP model from all images to be later used\nfor both the camera poses and the input point cloud.\nHowever, if you care about correct evaluation, you want the input point cloud to be constructed only from\nthe training images. In that case, you can use the `--separate-training-pointcloud` flag.\nWith this flag turned on, the script will create two sparse models: \nfirst with all images to get the camera poses of all images and the second from only the training images. \n\nFinally, start the training:\n```bash\nns-train tetra-nerf colmap --data \u003cdata folder\u003e\n```\n\n### With existing COLMAP\nIn case you already have a sparse COLMAP model, move it to the data folder. The folder structure should look like this:\n```\nimages\n  ...\nsparse\n  0\n    cameras.bin\n    ...\n```\n\nFinally, start the training:\n```bash\nns-train tetra-nerf colmap --data \u003cdata folder\u003e\n```\n\n## Reproducing results\nWe first give instructions on how to download and preprocess the data, and run the training.\nWe also publish the generated images.\n\n### Getting the data\nFirst, please download and extract the datasets.\n- Download **Blender dataset** from here: [https://drive.google.com/file/d/18JxhpWD-4ZmuFKLzKlAw-w5PpzZxXOcG/view?usp=share_link](https://drive.google.com/file/d/18JxhpWD-4ZmuFKLzKlAw-w5PpzZxXOcG/view?usp=share_link). In this tutorial, we assume the data was extracted and moved to folder `data/blender`, which should now contain folders like: `lego`, `drums`, ... For the Blender dataset, we further provide the point clouds used by Point-NeRF. Please download and extract the following file: [https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/pointnerf-blender.zip](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/pointnerf-blender.zip) to folder `data/pointnerf-blender` which should now contain: `pointnerf-colmap-drums.ply`, ...\n- Download the **Tanks and Temples dataset** from here: [https://dl.fbaipublicfiles.com/nsvf/dataset/TanksAndTemple.zip](https://dl.fbaipublicfiles.com/nsvf/dataset/TanksAndTemple.zip). Extract it into `data/nsvf-tanks-and-temples`. The `Ignatius` scene has corrupted intrinsics file, therefore, we provide our own reconstructed data here: [https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/tt-ignatius.zip](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/tt-ignatius.zip). Please replace the path `data/nsvf-tanks-and-temples/Ignatius` with the downloaded and extracted fiel. You no longer need to run the processing steps on that scene.\n- Download the **Mip-NeRF 360 dataset** from here: [http://storage.googleapis.com/gresearch/refraw360/360_v2.zip](http://storage.googleapis.com/gresearch/refraw360/360_v2.zip). Extract it into `data/mipnerf360`.\n\nNext the poses must be transformed in order to be able to load them in NerfStudio. Make sure to have COLMAP and FFmpeg installed.\nYou can follow the instructions here if COLMAP is not installed: [https://colmap.github.io/install.html](https://colmap.github.io/install.html), or you can install it using `conda`.\nUse the following commands to transform the data and to generate the input tetrahedra.\n- For each scene from the Blender dataset, run the following:\n```bash\npython -m tetranerf.scripts.process_blender --transforms data/blender/\u003cscene\u003e/transforms_train.json --output data/blender/\u003cscene\u003e\npython -m tetranerf.scripts.triangulate --pointcloud data/blender/\u003cscene\u003e/sparse.ply --output data/blender/\u003cscene\u003e/sparse-1.th --random-points-ratio 1\npython -m tetranerf.scripts.triangulate --pointcloud data/pointnerf-blender/pointnerf-colmap-\u003cscene\u003e.ply --output data/blender/\u003cscene\u003e/pointnerf-0.5.th --random-points-ratio 0.5\n```\n- For each scene from the Tanks and Temples dataset, run the following:\n```bash\npython -m tetranerf.scripts.process_tanksandtemples --path data/nsvf-tanks-and-temples/\u003cscene\u003e --output data/nsvf-tanks-and-temples/\u003cscene\u003e\npython -m tetranerf.scripts.triangulate --pointcloud data/nsvf-tanks-and-temples/\u003cscene\u003e/dense.ply --output data/nsvf-tanks-and-temples/\u003cscene\u003e/dense-1M.th\n```\n\n- For each scene from the Mip-NeRF 360 dataset, run the following:\n```bash\npython -m tetranerf.scripts.process_mipnerf360 --downscale-factor \u003c2 for indoor, 4 for outdoor scenes\u003e --run-dense --path data/mipnerf360/\u003cscene\u003e\npython -m tetranerf.scripts.triangulate --pointcloud data/mipnerf360/\u003cscene\u003e/sparse.ply --output data/mipnerf360/\u003cscene\u003e/sparse-1.th --random-points-ratio 1\npython -m tetranerf.scripts.triangulate --pointcloud data/mipnerf360/\u003cscene\u003e/dense.ply --output data/mipnerf360/\u003cscene\u003e/dense-1M.th\n```\n\n### Running the training\nTo run the training, use the following commands:\n- For **Blender dataset**, run the following:\n```bash\nns-train tetra-nerf-original --pipeline.model.tetrahedra-path data/blender/\u003cscene\u003e/pointnerf-0.5.th blender-data --data data/blender/\u003cscene\u003e\n```\n- For **Tanks and Temples dataset**, run the following:\n```bash\nns-train tetra-nerf-original --pipeline.model.tetrahedra-path data/nsvf-tanks-and-temples/\u003cscene\u003e/dense-1M.th minimal-parser --data data/nsvf-tanks-and-temples/\u003cscene\u003e\n```\n- For **Mip-NeRF 360 dataset**, run the following:\n```bash\nns-train tetra-nerf-original --pipeline.model.tetrahedra-path data/mipnerf360/\u003cscene\u003e/dense-1M.th minimal-parser --data data/mipnerf360/\u003cscene\u003e\n```\n\n## Installation\nFirst, make sure to install the following:\n```\nCUDA (\u003e=11.3)\nPyTorch (\u003e=1.12.1)\nNerfstudio (\u003e=0.2.0)\nOptiX (\u003e=7.2,\u003c=7.6, preferably 7.6)\nCGAL\nCMake (\u003e=3.22.1)\n```\nWe recommend using a conda environment, `CMake`, `CGAL`, `torch` can be easily installed using `conda install`.\nOur code was tested with `python 3.10`, but any `python\u003e=3.7` should be also supported.\nYou can follow the getting started section in the `nerfstudio` repository [https://github.com/nerfstudio-project/nerfstudio#readme](https://github.com/nerfstudio-project/nerfstudio#readme).\nPlease make sure that Nerfstudio is installed and working well. If you run `ns-train` you shouldn't get any error messages. You can also test your `torch` installation by running:\n```\npython -c 'import torch; import torch.utils.cpp_extension;arch=(\";\".join(sorted(set(x.split(\"_\")[-1] for x in torch.utils.cpp_extension._get_cuda_arch_flags()))));print(f\"CUDA: {torch.version.cuda}, compute: {arch}\")'\n```\nwhich will output your CUDA version and CUDA compute, which should be greater than 61 and ideally 86.\n\nThe OptiX library can be installed from here [https://developer.nvidia.com/designworks/optix/downloads/legacy](https://developer.nvidia.com/designworks/optix/downloads/legacy). If you install it to a non-standard path, set the environment variable `OPTIX_PATH=/path/to/optix` when building `Tetra-NeRF`.\n\nFinally, you can install **Tetra-NeRF** by running:\n```\ngit clone https://github.com/jkulhanek/tetra-nerf\ncd tetra-nerf\ncmake .\nmake \npip install -e .\n```\n\n### Docker\nAlternatively, you can also run **Tetra-NeRF** in a docker image:\n```\ndocker pull kulhanek/tetra-nerf:latest\ndocker run --rm -it --gpus all -p 7007:7007 kulhanek/tetra-nerf:latest\n```\nNote, it is required that `nvidia-container-toolkit` is installed and configured properly.\n\nYou can also build your custom image. Follow the instructions in the attached `Dockerfile`.\n\n## Predictions\nTo enable easier comparisons with our method we further provide the predicted images for the test sets.\n\n| Dataset                        | Predictions | Input tetrahedra |\n| ------------------------------ | ----------- | ---------------- |\n| Mip-NeRF 360 (public scenes)   | [download](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/mipnerf360-public-predictions.tar.gz) | [download](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/mipnerf360-public-tetrahedra.tar.gz) |\n| Blender                        | [download](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/blender-predictions.tar.gz) | [download](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/blender-tetrahedra.tar.gz) |\n| Tanks and Temples              | [download](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/nsvf-tanks-and-temples-predictions.tar.gz) | [download](https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/assets/nsvf-tanks-and-temples-tetrahedra.tar.gz) |\n\n\n## Thanks\nThis project is built on [NerfStudio](https://docs.nerf.studio/en/latest/)\u003cbr\u003e\n[\u003cimg alt=\"NerfStudio logo\" src=\"https://data.ciirc.cvut.cz/public/projects/2023TetraNeRF/resources/nerfstudio-logo.png\" width=\"300\" /\u003e](https://docs.nerf.studio/en/latest/)\u003cbr\u003e\nFast ray-tracing is enabled by [NVIDIA OptiX](https://developer.nvidia.com/rtx/ray-tracing/optix)\n\n## Citing\nIf you use our work or build on top of it, please use the following citation:\n```bibtex\n@inproceedings{kulhanek2023tetranerf,\n  title={{T}etra-{NeRF}: Representing Neural Radiance Fields Using Tetrahedra},\n  author={Kulhanek, Jonas and Sattler, Torsten},\n  booktitle={Proceedings of the IEEE/CVF International Conference on Computer Vision},\n  pages={18458--18469},\n  year={2023}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkulhanek%2Ftetra-nerf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkulhanek%2Ftetra-nerf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkulhanek%2Ftetra-nerf/lists"}