Skip to content

GitLab

Commit f983c38b authored by fengzch-das's avatar fengzch-das
Browse files

update readme

parent ee89d5fa
Hide whitespace changes
Inline Side-by-side
Showing with 179 additions and 79 deletions
readme.md
View file @ f983c38b
# cuBVH
# <div align="center"><strong>cuBVH</strong></div>
A CUDA Mesh BVH acceleration toolkit.
## 1 简介
### Install
cuBVH 是一个 CUDA Mesh BVH 加速工具包。
```bash
pip install git+https://github.com/ashawkey/cubvh
## 2 安装
# 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`**
| PyTorch版本 | fastpt版本 | cuBVH版本 | DTK版本 | Python版本 | 推荐编译方式 |
| ----------- | ---------- | ------------- | -------- | --------------- | ------------ |
| 2.5.1 | 2.1.0 | main-eeb9d5fa | >= 25.04 | 3.8、3.10、3.11 | fastpt不转码 |
| 2.4.1 | 2.0.1 | main-eeb9d5fa | >= 25.04 | 3.8、3.10、3.11 | fastpt不转码 |
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/
```
+ pytorch 版本大于 2.4.1 && dtk 版本大于 25.04 推荐使用 fastpt 不转码编译。
### 2.1 使用pip方式安装
**`fatal error: Eigen/Dense: No such file or directory`**
cuBVH whl 包下载目录：[光和开发者社区](https://download.sourcefind.cn:65024/4/main)，选择对应的 pytorch 版本和 python 版本下载对应 cuBVH 的 whl 包:
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`.)
```shell
pip install torch* # 下载torch的whl包
pip install fastpt* --no-deps # 下载fastpt的whl包
source /usr/local/bin/fastpt -E
pip install cubvh* # 下载的cubvh-fastpt的whl包
```
### Usage
### 2.2 使用源码编译方式安装
**Basics:**
#### 2.2.1 编译环境准备
```python
import numpy as np
import trimesh
import torch
提供基于 fastpt 不转码编译：
import cubvh
1. 基于光源 pytorch 基础镜像环境：镜像下载地址：[光合开发者社区](https://sourcefind.cn/#/image/dcu/pytorch)，根据 pytorch、python、dtk 及系统下载对应的镜像版本。
2. 基于现有 python 环境：安装 pytorch，fastpt whl 包下载目录：[光合开发者社区](https://sourcefind.cn/#/image/dcu/pytorch)，根据 python、dtk 版本，下载对应 pytorch 的 whl 包。安装命令如下：
### 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
```shell
pip install torch* # 下载torch的whl包
pip install fastpt* --no-deps # 下载fastpt的whl包, 安装顺序，先安装torch，后安装fastpt
pip install setuptools==59.5.0 wheel
```
### 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 源码编译安装
### 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]
```shell
git clone http://developer.sourcefind.cn/codes/OpenDAS/cubvh.git # 根据编译需要切换分支
```
**Robust Mesh Occupancy:**
- **手动下载三方库 eigen 至 third_party 下（git submodule update --init --recursive 访问代码仓会失败）**
- 提供2种源码编译方式（进入 cubvh 目录）：
- 源码编译安装：
UDF + flood-fill for possibly non-watertight/single-layer meshes:
```bash
source /usr/local/bin/fastpt -C
```python
import torch
import cubvh
import numpy as np
from skimage import morphology
python setup.py build
python setup.py install
```
- whl 包构建安装：
resolution = 512
device = torch.device('cuda')
```bash
source /usr/local/bin/fastpt -C
BVH = cubvh.cuBVH(vertices, faces)
python setup.py bdist_wheel # 该指令用于编译 whl 包
pip install dist/cubvh-0.1.0-cp310-cp310-linux_x86_64.whl
```
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 注意事项
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
+ ROCM_PATH 为 dtk 的路径，默认为 /opt/dtk；
+ 在 pytorch2.5.1 环境下编译需要支持 c++17 语法，打开setup.py文件，把文件中的 -std=c++14 修改为 -std=c++17。
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.
## 3 验证
执行下面的命令测试组件：
**Renderer:**
```bash
source /usr/local/bin/fastpt -E
Example for a mesh normal renderer by `ray_trace`:
pip install PyMCubes
pip install scikit-image
pip install kiui
pip install rtree
```bash
python test/renderer.py # default, show a dodecahedron
python test/renderer.py --mesh example.ply # show any mesh file
python test/extract_mesh_watertight.py /path/to/objFile(.obj 或 .ply 网格文件路径或目录)
python test/signed_distance.py
python test/unsigned_distance.py --N 100
```
https://user-images.githubusercontent.com/25863658/183238748-7ac82808-6cd3-4bb6-867a-9c22f8e3f7dd.mp4
## 4 Known Issue
- 无
### Acknowledgement
## 5 参考资料
* 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)!
- [readme_origin](readme_origin.md)
- [https://github.com/ashawkey/cubvh](https://github.com/ashawkey/cubvh)
readme_origin.md 0 → 100644
View file @ f983c38b
# 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