[Code Build][Ubuntu] SuGaR: Surface-Aligned Gaussian Splatting for Efficient 3D Mesh Reconstruction and High-Quality Mesh Rendering

https://github.com/Anttwo/SuGaR?tab=readme-ov-file

GitHub - Anttwo/SuGaR: [CVPR 2024] Official PyTorch implementation of SuGaR: Surface-Aligned Gaussian Splatting for Efficient 3D

 

 

[ required ubuntu environment]
ubuntu 20.04
cuda 11.8

 

# HTTPS
git clone https://github.com/Anttwo/SuGaR.git --recursive

 

SuGaR/ 경로로 들어가서

python install.py
conda activate sugar

 

 

python train_full_pipeline.py -s <path to COLMAP dataset> -r <"dn_consistency", "density" or "sdf"> --high_poly True --export_obj True

colmap 형태의 데이터가 준비되어있다는 전제하에 train 이 가능합니다.

-r argument 를 사용하여 regularization method 의 선택이 가능합니다.

 

 

• Regularization Method (-r 인자):
  • 선택 가능 옵션: "dn_consistency", "density", "sdf"
  • 추천: "dn_consistency" (최신 방식, 최고 품질 메쉬 제공)
  • 논문 결과:
    • 객체 중심 장면: "density"
    • 배경이 복잡한 장면 (Mip-NeRF 360 데이터셋): "sdf"
• Polygon 설정 (--high_poly, --low_poly 인자):
  • --high_poly True: 100만 개의 정점, 삼각형당 1개 Gaussian
  • --low_poly True: 20만 개의 정점, 삼각형당 6개 Gaussian
• Refinement Time (--refinement_time 인자):
  • 설정 가능 옵션: "short" (2k 반복), "medium", "long" (15k 반복)
  • 기본값: "long" (15k 반복)
  • "short"도 충분히 좋은 품질 제공 가능
• OBJ 파일 내보내기 (--export_obj 인자):
  • 기본 설정: OBJ 파일 추출 활성화
  • 용도: Blender에서 장면 편집, 결합, 애니메이션 작업 시 필요

 

<파라미터 요약>

--scene_path / -s	str	COLMAP 데이터셋이 포함된 소스 디렉토리 경로.	N/A
--gs_output_dir	str	기본 3D Gaussian Splatting 모델 체크포인트 디렉토리 경로. 제공하지 않으면 처음부터 모델을 최적화하여 학습을 시작함.	N/A
--regularization_type / -r	str	Gaussians 정렬 시 사용하는 Regularization 유형: "dn_consistency", "density", "sdf". "dn_consistency" 사용 권장.	N/A
--eval	bool	True일 경우 학습 이미지의 평가 분할을 수행함.	True
--low_poly	bool	True일 경우 Low Poly 메쉬 사용 (20만 정점, 삼각형당 6개의 Gaussian).	False
--high_poly	bool	True일 경우 High Poly 메쉬 사용 (100만 정점, 삼각형당 1개의 Gaussian).	False
--refinement_time	str	Refinement 단계에 사용할 반복 시간: "short" (2k 반복), "medium" (7k 반복), "long" (15k 반복).	"long"
--export_ply	bool	True일 경우 3D Gaussian을 .ply 파일로 내보냄. 파일 크기가 크지만 (약 500MB), 3DGS 뷰어 사용에 필요함.	True
--export_obj / -t	bool	True일 경우 정제된 SuGaR 모델에서 전통적인 텍스처 메쉬를 .obj 파일로 최적화 후 내보냄. UV 텍스처 계산은 Nvdiffrast로 몇 초 만에 처리됨.	True
--square_size	int	UV 텍스처에서 각 삼각형 쌍에 할당된 사각형 크기. 메모리 문제가 발생하면 값 감소 필요.	8
--white_background	bool	True일 경우 이미지 배경을 흰색으로 설정함.	False

 

 

 

SuGaR documentation 에서는 처음부터 학습하는 scratch 방법과 기존 모델 기반 학습인 방법 두개 다 지원합니다.

 

1. Training from Scratch (처음부터 학습)

• 초기화 방식:
  • 아무런 사전 학습 없이 Gaussian splats를 무작위로 초기화하여 학습을 시작합니다.
• 학습 시간:
  • 처음부터 최적의 Gaussians 위치와 색상, 밀도 등을 학습하기 때문에 시간이 오래 걸립니다.
• 필요한 리소스:
  • 대규모 연산 리소스가 필요하며, 초기 수렴 속도가 느릴 수 있습니다.
• 결과 품질:
  • 최적의 파라미터를 찾아가며 학습하므로 결과가 좋을 수 있지만, 학습 과정이 더 길어질 가능성이 있습니다.

---

2. Training from a Vanilla Gaussian Splatting Model (기존 모델 기반 학습)

• 초기화 방식:
  • 기존 Vanilla Gaussian Splatting 모델의 체크포인트를 불러와 학습을 시작합니다.
• 학습 시간:
  • 기존 모델의 사전 학습된 Gaussians가 초기값으로 사용되기 때문에 학습 시간을 크게 단축할 수 있습니다.
• 필요한 리소스:
  • 학습이 빠르게 진행되기 때문에 메모리 및 연산 효율이 높아집니다.
• 결과 품질:
  • 사전 학습된 정보가 기반이 되기 때문에 더 안정적이고 빠르게 좋은 품질의 결과를 얻을 수 있습니다.
  • 하지만 사전 학습된 모델이 특정 데이터에 맞춰져 있으면, 일반화된 모델보다 약간 제한적인 결과가 나올 수 있습니다.

 

저는 처음부터 학습하는 scratch 방법을 사용하였습니다.

그렇게 학습을 하니, output 폴더에 fined_mesh 와 refined_ply 파일이 저장된 것을 확인할 수 있었습니다.

 

 

자 이제, Viewer 를 이용해서 output 을 렌더링하여 볼 수 있습니다.

 

• 자동 .ply 파일 내보내기: 최적화 후 ./output/refined_ply/ 디렉토리에 SuGaR 하이브리드 표현이 포함된 refined 3D Gaussian .ply 파일이 자동으로 저장됩니다.
  • 이 .ply 파일은 모든 3D Gaussian Splatting Viewer에서 호환됩니다.
• 추천 Viewer:
  1. 오리지널 3D Gaussian Splatting Viewer (원본 구현의 Viewer)
  2. SuperSplat Viewer (강력한 성능의 뷰어)
  3. SuperSplat 웹 버전: 브라우저에서 직접 시각화 가능.
• SuGaR 전용 뷰어:
  • 텍스처 메쉬, 와이어프레임 메쉬, refined 3D Gaussian을 시각화할 수 있는 전용 실시간 뷰어도 제공됩니다.

 

 

SIBR_gaussianViewer_app.exe 를 이용하여 가우시안 ply 파일을 확인해본 결과, 잘 학습되어 렌더링 된 모습을 확인할 수 있었습니다.

 

 

하지만 SuGaR 논문 내에서도 제공하는 viewer가 따로 있었습니다.

SuGaR 에서 제공하는 viewer 는 linux 환경과 Mac OS 환경에서는 build 가 된다고 합니다.

저는 이제 ubuntu 의 vessl 서버 환경에서 진행하기 때문에, 다른 설정없이 follow up 해보도록 하겠습니다.

(window 사용자의 경우 WSL 을 통해서 linux 환경을 구축할 수 있다고 합니다.)

 

curl -fsSL https://deb.nodesource.com/setup_21.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt-get install aptitude
sudo aptitude install -y npm

 

./sugar_viewer/ 폴더로 들어가서

npm install
cd ..

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

 

설치가 완료되면, 터미널을 닫았다가 다시 열거나 다음 명령어를 실행하여 환경 변수를 적용합니다

 

 

python train_full_pipeline.py -s <path to COLMAP dataset> -r <"dn_consistency", "density" or "sdf"> --high_poly True --export_obj True --gs_output_dir <path to the Gaussian Splatting output directory>

python train_full_pipeline.py -s /source/sola/SuGaR/data/tandt_db/db/drjohnson -r dn_consistency --high_poly True --export_obj True --gs_output_dir /source/sola/SuGaR/data/3dgs_model/drjohnson

이렇게 돌리니, 해당 colmap data set 폴더에 이미지가 없다는 에러가 발생했습니다.

FileNotFoundError: [Errno 2] No such file or directory: '/source/sola/SuGaR/data/tandt_db/db/drjohnson/images/IMG_6292.jpg.jpg'

에러코드를 보니, 파일명에 확장자가 중복되어 들어가 있는것을 확인할 수 있었습니다.

 

=> name에 확장자가 이미 포함되어 있는 경우, 다시 추가하지 않도록 조건문을 추가해야 합니다.

(root폴더)/sugar_scene 폴더로 들어가서 cameras.py 코드를 일부 수정해줘야합니다.

---

수정된 코드 예시:

 

# 확장자가 이미 포함되어 있는지 확인 후 추가
if not name.endswith(('.jpg', '.png', '.jpeg', '.JPG', '.PNG')): 
    image_path = os.path.join(image_dir, name + extension)
else: image_path = os.path.join(image_dir, name)

---

코드 적용 위치:

load_gs_cameras 함수 내, 다음 코드 부분을 위 코드로 교체합니다:

image_path = os.path.join(image_dir, name + extension)

 

 

* antialiasing issue

sugar_scene 폴더에 있는 sugar_model.py 수정 필요.

raster_settings = GaussianRasterizationSettings(
            image_height=int(self.image_height),
            image_width=int(self.image_width),
            tanfovx=self.tanfovx,
            tanfovy=self.tanfovy,
            bg=bg_color,
            scale_modifier=1.,
            viewmatrix=world_view_transform,
            projmatrix=full_proj_transform,
            sh_degree=sh_deg,
            campos=camera_center,
            prefiltered=False,
            debug=False,
            antialiasing=True  # antialiasing 매개변수 추가
        )

 

* rasterizer 의 output 개수 오류.

# error code

rendered_image, radii = rasterizer(
ValueError: too many values to unpack (expected 2)

rasterizer의 output 을 직접 출력해서 보니까, 3개의 값을 반환하는 것을 확인할 수 있었음.
그런데 rendered_image 와 radii 두개로만 output 을 받으려고 하니까 발생하는 오류... 
근데 왜 이게 안맞는지는 잘 모르겠습니다.... 코드 원작자들이 잘 맞춰놓았을텐데...?

rendered_image, radii, additional_output = rasterizer(
            means3D = positions,
            means2D = means2D,
            shs = shs,
            colors_precomp = splat_colors,
            opacities = splat_opacities,
            scales = scales,
            rotations = quaternions,
            cov3D_precomp = cov3D)

 그래서 위와 같이 sugar_scene/sugar_model.py 를 수정해주었다.
additional_output 이 어디에 사용되는지는 모르겠지만...

 

 

그리고 다시 train 시키는 명령문을 작성해보면, 잘 학습되는것을 확인할 수 있습니당.