Skip to content

GitLab

Commit 753b5e30 authored by fengzch-das's avatar fengzch-das
Browse files

Merge branch 'fzc-dev' into 'main' 

update readme

See merge request !1
parents ee89d5fa f667eada
Hide whitespace changes
Inline Side-by-side
Showing with 156 additions and 87 deletions
readme.md
View file @ 753b5e30
# cuBVH
<h1 style="text-align: center;">cubvh</h1>
A CUDA Mesh BVH acceleration toolkit.
# 1 简介
### Install
cubvh 是一个CUDA Mesh BVH加速工具包。
```bash
pip install git+https://github.com/ashawkey/cubvh
# or locally
git clone --recursive https://github.com/ashawkey/cubvh
cd cubvh
pip install .
```
It will take several minutes to build the CUDA dependency.
#### Trouble Shooting
**`fatal error: eigen/matrix.h: No such file or directory`**
This is a known issue for `torch==2.1.0` and `torch==2.1.1` (https://github.com/pytorch/pytorch/issues/112841).
To patch up these two versions, clone this repository, and copy `patch/eigen` to your pytorch include directory:
```bash
# for example, if you are using anaconda (assume base env)
cp -r patch/eigen ~/anaconda3/lib/python3.9/site-packages/torch/include/pybind11/
```
**`fatal error: Eigen/Dense: No such file or directory`**
# 2 编译安装方式
Please make sure [`eigen >= 3.3`](https://eigen.tuxfamily.org/index.php?title=Main_Page) is installed.
We have included it as a submodule in this repository, but you can also install it in your system include path.
(For example, ubuntu systems can use `sudo apt install libeigen3-dev`.)
## 2.1 环境准备
### Usage
当前组件在下面的环境下已验证编译成功：
**Basics:**
| 序号 | FastPT版本 | Pytorch版本 | DTK版本 |
| :--: | :----------------: | :---------: | :------: |
| 1 | 2.0.1+das.dtk25041 | 2.4.1 | dtk25041 |
| 2 | 2.0.1+das.dtk2504 | 2.4.1 | dtk2504 |
```python
import numpy as np
import trimesh
import torch
## 2.2 编译流程
import cubvh
### 2.2.1 基础环境检查
### build BVH from mesh
mesh = trimesh.load('example.ply')
# NOTE: you need to normalize the mesh first, since the max distance is hard-coded to 10.
BVH = cubvh.cuBVH(mesh.vertices, mesh.faces) # build with numpy.ndarray/torch.Tensor
* 检查当前环境是否安装 DTK，若没有则需要安装 DTK，并确定当前环境下 DTK 的版本；
* 检查当前环境是否安装 Pytorch，若没有则需要安装 Pytorch，并确定当前环境下 Pytorch 的版本是否与 DTK 版本对应；
* 检查当前环境是否安装 FastPT，若没有则需要安装 FastPT，并确定当前环境下 FastPT 的版本是否与 Pytorch 的版本相对应；
### query ray-mesh intersection
rays_o, rays_d = get_ray(pose, intrinsics, H, W) # [N, 3], [N, 3], query with torch.Tensor (cuda)
intersections, face_id, depth = BVH.ray_trace(rays_o, rays_d) # [N, 3], [N,], [N,]
### 2.2.2 cubvh 编译流程
### query unsigned distance
points # [N, 3]
# uvw is the barycentric corrdinates of the closest point on the closest face (None if `return_uvw` is False).
distances, face_id, uvw = BVH.unsigned_distance(points, return_uvw=True) # [N], [N], [N, 3]
* 安装依赖
### query signed distance (INNER is NEGATIVE!)
# for watertight meshes (default)
distances, face_id, uvw = BVH.signed_distance(points, return_uvw=True, mode='watertight') # [N], [N], [N, 3]
# for non-watertight meshes:
distances, face_id, uvw = BVH.signed_distance(points, return_uvw=True, mode='raystab') # [N], [N], [N, 3]
```bash
pip install wheel
```
**Robust Mesh Occupancy:**
UDF + flood-fill for possibly non-watertight/single-layer meshes:
* 手动下载三方库 eigen 至 third_party 下（`git submodule update --init --recursive` 访问代码仓会失败）
* 执行命令编译组件：
```python
import torch
import cubvh
import numpy as np
from skimage import morphology
resolution = 512
device = torch.device('cuda')
BVH = cubvh.cuBVH(vertices, faces)
```
python setup.py build
python setup.py install
```
grid_points = torch.stack(
torch.meshgrid(
torch.linspace(-1, 1, resolution, device=device),
torch.linspace(-1, 1, resolution, device=device),
torch.linspace(-1, 1, resolution, device=device),
indexing="ij",
), dim=-1,
) # [N, N, N, 3]
### 2.2.3 编译 whl 包
udf, _, _ = BVH.unsigned_distance(grid_points.view(-1, 3), return_uvw=False)
udf = udf.cpu().numpy().reshape(resolution, resolution, resolution)
occ = udf < 2 / resolution # tolerance 2 voxels
可以通过执行下面的命令生成 whl 包：
empty_mask = morphology.flood(occ, (0, 0, 0), connectivity=1) # flood from the corner, which is for sure empty
occ = ~empty_mask
```bash
python setup.py bdist_wheel # 该指令用于编译whl包，执行该指令时不必执行前两个指令
```
Check [`test/extract_mesh_watertight.py`](test/extract_mesh_watertight.py) for more details.
**Renderer:**
Example for a mesh normal renderer by `ray_trace`:
并通过下面的命令安装 cubvh:
```bash
python test/renderer.py # default, show a dodecahedron
python test/renderer.py --mesh example.ply # show any mesh file
pip install dist/cubvh-0.1.0-cp310-cp310-linux_x86_64.whl
```
https://user-images.githubusercontent.com/25863658/183238748-7ac82808-6cd3-4bb6-867a-9c22f8e3f7dd.mp4
# 3 组件测试
### Acknowledgement
执行下面的命令测试组件：
* Credits to [Thomas Müller](https://tom94.net/)'s amazing [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn) and [instant-ngp](https://github.com/NVlabs/instant-ngp)!
```bash
pip install PyMCubes
pip install scikit-image
pip install kiui
pip install rtree
python test/extract_mesh_watertight.py /path/to/objFile(.obj 或 .ply 网格文件路径或目录)
python test/signed_distance.py
python test/unsigned_distance.py --N 100
```
readme_origin.md 0 → 100644
View file @ 753b5e30
# cuBVH
A CUDA Mesh BVH acceleration toolkit.
### Install
```bash
pip install git+https://github.com/ashawkey/cubvh
# or locally
git clone --recursive https://github.com/ashawkey/cubvh
cd cubvh
pip install .
```
It will take several minutes to build the CUDA dependency.
#### Trouble Shooting
**`fatal error: eigen/matrix.h: No such file or directory`**
This is a known issue for `torch==2.1.0` and `torch==2.1.1` (https://github.com/pytorch/pytorch/issues/112841).
To patch up these two versions, clone this repository, and copy `patch/eigen` to your pytorch include directory:
```bash
# for example, if you are using anaconda (assume base env)
cp -r patch/eigen ~/anaconda3/lib/python3.9/site-packages/torch/include/pybind11/
```
**`fatal error: Eigen/Dense: No such file or directory`**
Please make sure [`eigen >= 3.3`](https://eigen.tuxfamily.org/index.php?title=Main_Page) is installed.
We have included it as a submodule in this repository, but you can also install it in your system include path.
(For example, ubuntu systems can use `sudo apt install libeigen3-dev`.)
### Usage
**Basics:**
```python
import numpy as np
import trimesh
import torch
import cubvh
### build BVH from mesh
mesh = trimesh.load('example.ply')
# NOTE: you need to normalize the mesh first, since the max distance is hard-coded to 10.
BVH = cubvh.cuBVH(mesh.vertices, mesh.faces) # build with numpy.ndarray/torch.Tensor
### query ray-mesh intersection
rays_o, rays_d = get_ray(pose, intrinsics, H, W) # [N, 3], [N, 3], query with torch.Tensor (cuda)
intersections, face_id, depth = BVH.ray_trace(rays_o, rays_d) # [N, 3], [N,], [N,]
### query unsigned distance
points # [N, 3]
# uvw is the barycentric corrdinates of the closest point on the closest face (None if `return_uvw` is False).
distances, face_id, uvw = BVH.unsigned_distance(points, return_uvw=True) # [N], [N], [N, 3]
### query signed distance (INNER is NEGATIVE!)
# for watertight meshes (default)
distances, face_id, uvw = BVH.signed_distance(points, return_uvw=True, mode='watertight') # [N], [N], [N, 3]
# for non-watertight meshes:
distances, face_id, uvw = BVH.signed_distance(points, return_uvw=True, mode='raystab') # [N], [N], [N, 3]
```
**Robust Mesh Occupancy:**
UDF + flood-fill for possibly non-watertight/single-layer meshes:
```python
import torch
import cubvh
import numpy as np
from skimage import morphology
resolution = 512
device = torch.device('cuda')
BVH = cubvh.cuBVH(vertices, faces)
grid_points = torch.stack(
torch.meshgrid(
torch.linspace(-1, 1, resolution, device=device),
torch.linspace(-1, 1, resolution, device=device),
torch.linspace(-1, 1, resolution, device=device),
indexing="ij",
), dim=-1,
) # [N, N, N, 3]
udf, _, _ = BVH.unsigned_distance(grid_points.view(-1, 3), return_uvw=False)
udf = udf.cpu().numpy().reshape(resolution, resolution, resolution)
occ = udf < 2 / resolution # tolerance 2 voxels
empty_mask = morphology.flood(occ, (0, 0, 0), connectivity=1) # flood from the corner, which is for sure empty
occ = ~empty_mask
```
Check [`test/extract_mesh_watertight.py`](test/extract_mesh_watertight.py) for more details.
**Renderer:**
Example for a mesh normal renderer by `ray_trace`:
```bash
python test/renderer.py # default, show a dodecahedron
python test/renderer.py --mesh example.ply # show any mesh file
```
https://user-images.githubusercontent.com/25863658/183238748-7ac82808-6cd3-4bb6-867a-9c22f8e3f7dd.mp4
### Acknowledgement
* Credits to [Thomas Müller](https://tom94.net/)'s amazing [tiny-cuda-nn](https://github.com/NVlabs/tiny-cuda-nn) and [instant-ngp](https://github.com/NVlabs/instant-ngp)!
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment