EasyVolcap

https://github.com/zju3dv/easyvolcap
Admin
EasyVolcap is a PyTorch library for neural volumetric video research, supporting capture,...
Tokens:80,613
Snippets:530
Trust Score:7.9
Update:10 hours ago
Show doc for...
Tokens:
Raw
### TLDR: Full setup for new Linux servers

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Complete shell workflow to set up EasyVolcap on a new Linux server: install Miniconda, create a conda environment with Python 3.11, install PyTorch, clone the longvolcap repo, install pip dependencies, and register EasyVolcap for imports. Includes commands to install development dependencies and to ignore the license during Miniconda installation.

```shell
cd ~
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
chmod +x Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh -b # this option will ignore license
conda init zsh # assuming you're using zshell
zsh # manually restart the shell

# Prepare conda environment
conda install -n base mamba -y -c conda-forge
mamba create -n easyvolcap "python>=3.11,<3.12" -y
mamba init zsh # assuming you're using zshell
zsh # manually restart the shell
conda activate easyvolcap

# Install PyTorch
pip install torch torchvision torchaudio -f https://download.pytorch.org/whl/torch_stable.html

# Clone the repo
mkdir -p local
cd local
git clone https://github.com/dendenxu/longvolcap
cd longvolcap

# Install pip dependencies
cat requirements.txt | sed -e '/^\s*-.*$/d' -e '/^\s*#.*$/d' -e '/^\s*$/d' | awk '{split($0, a, "#"); if (length(a) > 1) print a[1]; else print $0;}' | awk '{split($0, a, "@"); if (length(a) > 1) print a[2]; else print $0;}' | xargs -n 1 pip install

# Install development pip dependencies
cat requirements-devel.txt | sed -e '/^\s*-.*$/d' -e '/^\s*#.*$/d' -e '/^\s*$/d' | awk '{split($0, a, "#"); if (length(a) > 1) print a[1]; else print $0;}' | awk '{split($0, a, "@"); if (length(a) > 1) print a[2]; else print $0;}' | xargs -n 1 pip install # use this for full dependencies

# Register EasyVolcp for imports
pip install -v -e . --no-build-isolation --no-deps
```

--------------------------------

### Set up conda environment and install dependencies

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Complete setup for EasyVolcap: clone the repo, install mamba, create a conda environment, install pip dependencies one by one, and register CLI commands. The `cat` command is used because `pip install -r requirements.txt` fails if any single dependency fails. Note the caveat about WSL2 with Python 3.10 and OpenGL initialization.

```shell
# Clone this codebase with:
git clone https://github.com/zju3dv/EasyVolcap
cd EasyVolcap

# If you haven't installed conda, 
# We recommend installing it from https://docs.conda.io/projects/miniconda/en/latest/
# On Ubuntu, these scripts can be used
# cd ~
# wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
# chmod +x Miniconda3-latest-Linux-x86_64.sh
# ./Miniconda3-latest-Linux-x86_64.sh # and finish the installation as the guide

# Maybe install mamba through conda 
# The recommended way is to use mambaforge directly instead of installing miniconda3
conda install -n base mamba -c conda-forge -y

# Picks up on environment.yml and create a pytorch env
# mamba env create

# If this doesn't work, separate create and update as follows
# Note that as of 2023.04.21, wsl2 with python 3.10 could not correctly initialize or load opengl
# You need manually change the following command to accomodate for that (3.10 to 3.9)
# And update the environment.yml file to use python 3.9 instead of 3.10
# mamba create -n easyvolcap "python==3.10" -y
# mamba create -n easyvolcap "python>=3.10,<3.10" -y
mamba init zsh
mamba create -n easyvolcap "python~=3.11" -y
mamba activate easyvolcap
mamba env update # picks up environment.yml

# With the environment created, install other dependencies 
# And possibly modify .zshrc to automatically activate this env
# echo conda activate easyvolcap >> ~/.zshrc
# source ~/.zshrc # actually not needed (already activated)

# Install all pip dependencies one by one in case some fails
# pip dependencies might fail to install, check the root cause and try this script again
# Possible caveats: cuda version? pytorch version? python version?
cat requirements-devel.txt | sed -e '/^\s*#.*$/d' -e '/^\s*$/d' | awk '{split($0, a, "@"); if (length(a) > 1) print a[2]; else print $0;}' | xargs -n 1 pip install # use this for full dependencies

# Registers command-line interfaces like `evc` `evc-train` `evc-test` etc.
pip install -e . --no-build-isolation --no-deps
```

--------------------------------

### Launch GUI with GaussianT static config and superm spec

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/gaussiant.md

Use these commands to start the EasyVolcap GUI for the GaussianT project. Each command loads a specific static experiment configuration along with the superm specification. The first command uses gaussiant_0008_03_static.yaml, and the second uses gaussiant_0013_01_static.yaml.

```shell
evc-gui -c configs/exps/gaussiant/gaussiant_0008_03_static.yaml,configs/specs/superm.yaml
```

```shell
evc-gui -c configs/exps/gaussiant/gaussiant_0013_01_static.yaml,configs/specs/superm.yaml
```

--------------------------------

### Clone and install tiny-cuda-nn manually

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Recommended to retain compiled objects in case of failure. Clones the repository recursively and installs the PyTorch bindings.

```shell
cd ~
git clone https://github.com/NVlabs/tiny-cuda-nn --recursive
cd tiny-cuda-nn/bindings/torch
pip install .
```

--------------------------------

### Install tiny-cuda-nn via pip

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Alternative installation method for `tiny-cuda-nn` using pip directly from the GitHub repository.

```shell
pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
```

--------------------------------

### Run WebSocket rendering server (evc-gui with server.yaml)

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Starts a WebSocket-based rendering server by appending configs/specs/server.yaml to the config list. This enables server-side rendering for remote viewing clients.

```shell
# Run the rendering server, append `configs/specs/server.yaml` to the config file list
evc-gui -c configs/exps/enerfi/enerfi_${expname}.yaml,configs/specs/server.yaml exp_name=enerfi_dtu val_dataloader_cfg.dataset_cfg.ratio=0.5 model_cfg.sampler_cfg.n_planes=32,8 model_cfg.sampler_cfg.n_samples=4,1

```

--------------------------------

### Install ffmpeg with zscale filter support

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Required for the examples in the main readme that use HDR video, which need the `zscale` filter. Adds the savoury1/ffmpeg4 PPA and installs ffmpeg.

```shell
sudo add-apt-repository ppa:savoury1/ffmpeg4
sudo apt update
sudo apt install ffmpeg
```

--------------------------------

### Install all pip dependencies from requirements.txt

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Installs all pip dependencies one by one to avoid failures. This command is automatically used when installing dependencies for EasyVolcap.

```shell
# Install all pip dependencies one by one in case some fails
cat requirements.txt | sed -e '/^\s*#.*$/d' -e '/^\s*$/d' | xargs -n 1 pip install
```

--------------------------------

### Prepare server configuration with zip

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Command to zip server configuration files, excluding the SSH private key.

```shell
# Prepare my server configuration
zip -r zsh_vim_tmux.zip .zshrc .oh-my-zsh .tmux .tmux.conf .tmux.conf.local .p10k.zsh .gitconfig .ssh .config/nvim software/exa software/nvim-linux64 software/vmtouch software/viu software/v2ray-sagernet software/aliyunpan -x .ssh/id_rsa
```

--------------------------------

### Install Miniconda on Linux

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Downloads and installs Miniconda on Linux, then initializes conda for zsh. The -b flag ignores the license prompt.

```shell
cd ~
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
chmod +x Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh -b # this option will ignore license
conda init zsh # assuming you're using zshell
```

--------------------------------

### Install dependencies one by one for robustness

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Alternative installation method when pip install fails due to one or two packages. Installs PyTorch, pip dependencies, development dependencies, and registers EasyVolcap for imports. The --no-build-isolation flag speeds up installation but requires latest setuptools and pip.

```shell
# Install PyTorch
pip install torch torchvision torchaudio -f https://download.pytorch.org/whl/torch_stable.html

# Install pip dependencies
cat requirements.txt | sed -e '/^\s*-.*$/d' -e '/^\s*#.*$/d' -e '/^\s*$/d' | awk '{split($0, a, "#"); if (length(a) > 1) print a[1]; else print $0;}' | awk '{split($0, a, "@"); if (length(a) > 1) print a[2]; else print $0;}' | xargs -n 1 pip install

# Install development pip dependencies
cat requirements-devel.txt | sed -e '/^\s*-.*$/d' -e '/^\s*#.*$/d' -e '/^\s*$/d' | awk '{split($0, a, "#"); if (length(a) > 1) print a[1]; else print $0;}' | awk '{split($0, a, "@"); if (length(a) > 1) print a[2]; else print $0;}' | xargs -n 1 pip install # use this for full dependencies

# Register EasyVolcp for imports
pip install -v -e . --no-build-isolation --no-deps
```

--------------------------------

### Install EasyVolcap from GitHub with pip

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Install EasyVolcap directly from GitHub using pip. The first command installs core dependencies; the second installs development dependencies, which may require CUDA compilation.

```shell
# Install core dependencies
pip install -v "git+https://github.com/zju3dv/EasyVolcap"

# Maybe also install development required dependencies (might require CUDA compilation)
pip install -v "git+https://github.com/zju3dv/EasyVolcap#egg=easyvolcap[devel]"
```

--------------------------------

### Fork EasyVolcap and set up upstream for new project

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Example development process for creating a new project based on EasyVolcap: clone the repo, set your own remote, add EasyVolcap as upstream, and fetch/merge updates. Used by projects like 4K4D.

```shell
# Prepare the name and GitHub repo of your new project
project=4K4D
repo=https://github.com/zju3dv/${project}

# Clone EasyVolcap and add our repo as an upstream
git clone https://github.com/zju3dv/EasyVolcap ${project}

# Setup the remote of your new project
git set-url origin ${repo}

# Add EasyVolcap as an upstream
git remote add upstream https://github.com/zju3dv/EasyVolcap

# If EasyVolcap updates, fetch the updates and maybe merge with it
git fetch upstream
git merge upstream/main
```

--------------------------------

### Check EasyVolcap and PyTorch installation

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/enerf.md

Run these shell commands to verify that EasyVolcap and PyTorch are installed correctly. The first command checks the EasyVolcap installation, and the second checks PyTorch with a CUDA tensor. Missing packages can be installed via pip if import errors occur.

```shell
python -c "from easyvolcap.utils.console_utils import *" # Check for easyvolcap installation. 4K4D is a fork of EasyVolcap
python -c "import torch; print(torch.rand(3, 3, device='cuda'))" # Check for pytorch installation
```

--------------------------------

### Direct usage example with evc-gui and pdbr

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/config.md

Shows direct usage of the configuration system via the command line. Running 'evc-gui not_exist.help=ok' sets a config key, and then in pdbr you can inspect the resulting 'cfg' object to see the parsed value.

```shell
# Run this
evc-gui not_exist.help=ok

# Invoke pdbr and check for the parameter
(Pdbr) cfg.not_exist
{'help': 'ok'}
(Pdbr) cfg.not_exist.help
'ok'
(Pdbr)
```

--------------------------------

### Verify 4K4D dependencies with Python import checks

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/realtime4dv.md

Run these shell commands to confirm that EasyVolcap, PyTorch, PyTorch3D, tiny-cuda-nn, and Open3D are installed. Open3D is only required for training (extracting visual hulls).

```shell
python -c "from easyvolcap.utils.console_utils import *" # Check for easyvolcap installation. 4K4D is a fork of EasyVolcap
python -c "import torch; print(torch.rand(3,3,device='cuda'))" # Check for pytorch installation
python -c "from pytorch3d.io import load_ply" # Check for pytorch3d installation
python -c "import tinycudann" # Check for tinycudann installation
python -c "import open3d" # Check for open3d installation. open3d is only required for training (extracting visual hulls)
```

--------------------------------

### Update pip and setuptools

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Update pip and setuptools if the pip install -e . --no-build-isolation --no-deps command results in a package name of UNKNOWN.

```shell
python -m pip install -U pip setuptools
```

--------------------------------

### Install EasyMocap

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/custom_dataset.md

Clone EasyMocap outside the main EasyVolcap directory and install it in the easyvolcap conda environment using setup.py develop.

```shell
# Clone EasyMocap somewhere outside the main directory of EasyVolcap
cd ~
git clone https://github.com/zju3dv/EasyMocap.git

# Install EasyMocap
cd EasyMocap
conda activate easyvolcap
python3 setup.py develop
```

--------------------------------

### Prepare dataset variables and train background NGP

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/realtime4dv.md

Sets up dataset variables, rearranges background images, trains a background NGP, extracts point clouds, and prepares initialization for the background 4K4D model. Requires following the dense calibration and space carving guides first.

```shell
# Prepare dataset variables
expname=actor1_4
data_root=data/enerf_outdoor/actor1_4

# Rearrange background images
python scripts/segmentation/link_backgrounds.py --data_root ${data_root}

# Train background NGP
evc-train -c configs/exps/l3mhet/l3mhet_${expname}_bkgd.yaml

# Extract point clouds from trained background NGP
python scripts/fusion/volume_fusion.py --skip_depth_consistency -- -c configs/exps/l3mhet/l3mhet_${expname}_bkgd.yaml val_dataloader_cfg.dataset_cfg.ratio=0.15 val_dataloader_cfg.dataset_cfg.view_sample=0,None,3 # 50W should be ok

# Prepare for initialization of bg 4k4d
mkdir -p ${data_root}/bkgd/boost
cp data/geometry/l3mhet_${expname}_bkgd/POINT/frame0000.ply ${data_root}/bkgd/boost/000000.ply
```

--------------------------------

### Install requirements line by line with sed

Source: https://github.com/zju3dv/easyvolcap/blob/main/requirements-devel.txt

Alternative command to install each package from requirements.txt individually, skipping comments and empty lines. Useful for debugging installation failures.

```bash
cat requirements.txt | sed -e '/^\s*#.*$/d' -e '/^\s*$/d' | xargs -n 1 pip install
```

--------------------------------

### Prepare 3DGS+T initialization point cloud with volume_fusion.py

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Extracts a dense point cloud from a trained Instant-NGP+T model for 3DGS initialization, then copies the resulting .ply files into the dataset's vhulls folder with zero-padded frame numbers. Requires diff_gauss or diff_gaussian_rasterization installed. Tune ratio for denser/sparser estimation.

```shell
# Extract geometry (point cloud) for initialization from the l3mhet model
# Tune image sample rate and resizing ratio for a denser or sparser estimation
python scripts/fusion/volume_fusion.py -- -c configs/exps/l3mhet/l3mhet_${expname}.yaml val_dataloader_cfg.dataset_cfg.ratio=0.15

# Move the rendering results to the dataset folder
source_folder="data/geometry/l3mhet_${expname}/POINT"
destination_folder="${data_root}/vhulls"

# Create the destination directory if it doesn't exist
mkdir -p ${destination_folder}

# Loop through all .ply files in the source directory
for file in ${source_folder}/*.ply; do
    number=$(echo $(basename ${file}) | sed -e 's/frame\([0-9]*\).ply/\1/')
    formatted_number=$(printf "%06d" ${number})
    destination_file="${destination_folder}/${formatted_number}.ply"
    cp ${file} ${destination_file}
done
```

--------------------------------

### Run charger.py for SuperChargedR4DV

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Commands to run charger.py for SuperChargedR4DV with different configurations. Each command specifies a different experiment name and configuration file.

```shell
python scripts/realtime4dv/charger.py SuperChargedR4DV scr4dv_my_377_optcam -- -c configs/exps/r4dv/r4dv_my_377_optcam.yaml configs=configs/specs/super.yaml
```

```shell
python scripts/realtime4dv/charger.py SuperChargedR4DV scr4dv_my_387_optcam -- -c configs/exps/r4dv/r4dv_my_387_optcam.yaml configs=configs/specs/super.yaml
```

```shell
python scripts/realtime4dv/charger.py SuperChargedR4DV scr4dv_my_390_optcam -- -c configs/exps/r4dv/r4dv_my_390_optcam.yaml configs=configs/specs/super.yaml
```

--------------------------------

### Profile r4dv training with evc-prof, evc-train, and evc-gui

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Commands to start a long-running profiling job to debug training time issues. The first command runs evc-prof with specific profiler settings. The second command runs evc-train with profiler enabled and additional training settings. The third command runs evc-gui with a different configuration.

```shell
# Start a long running profling job to debug training time issues
evc-prof -c configs/exps/r4dv/r4dv_${name}_optcam.yaml profiler_cfg.skip_first=0 profiler_cfg.wait=2490 profiler_cfg.warmup=5 profiler_cfg.active=5 profiler_cfg.repeat=0 # long running profiling job
```

```shell
evc-train -c configs/exps/r4dv/r4dv_${name}_optcam.yaml profiler_cfg.enabled=True profiler_cfg.skip_first=0 profiler_cfg.wait=2490 profiler_cfg.warmup=5 profiler_cfg.active=5 profiler_cfg.repeat=0 profiler_cfg.clear_previous=False runner_cfg.epochs=250 runner_cfg.decay_epochs=1600 # long running profiling job
```

```shell
evc-gui -c configs/exps/r4dv/r4dv_${name}_optcam.yaml exp_name=scr4dv_${name}_optcam configs=configs/specs/superf.yaml val_dataloader_cfg.dataset_cfg.frame_sample=0,1,1
```

--------------------------------

### Run volume_fusion for l3mhet and dance3

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Commands to run volume_fusion.py for l3mhet and dance3 static configurations. The first command uses a ratio of 0.5 and frame sample 0,None,25. The second command uses a ratio of 0.5 and view sample 0,None,3.

```shell
python scripts/fusion/volume_fusion.py -- -c configs/exps/l3mhet/l3mhet_zju3dv.yaml configs=configs/specs/fp16.yaml,configs/specs/vis.yaml val_dataloader_cfg.dataset_cfg.ratio=0.5 val_dataloader_cfg.dataset_cfg.frame_sample=0,None,25
```

```shell
python scripts/fusion/volume_fusion.py -- -c configs/exps/l3mhet/l3mhet_dance3_static.yaml configs=configs/specs/fp16.yaml,configs/specs/vis.yaml val_dataloader_cfg.dataset_cfg.ratio=0.5 val_dataloader_cfg.view_sample=0,None,3
```

--------------------------------

### Install EasyVolcap with conda and mamba

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

Copy-and-paste installation process: creates a conda environment, installs dependencies, and registers EasyVolcap for imports. Uses mamba for speed and disables build isolation for pip install.

```shell
# Prepare conda environment
conda install -n base mamba -y -c conda-forge
mamba create -n easyvolcap "python>=3.11,<3.12" -y
mamba init zsh # assuming you're using zshell
conda activate easyvolcap

# Install conda dependencies
mamba env update

# Install pip dependencies
cat requirements.txt | sed -e '/^\s*-.*$/d' -e '/^\s*#.*$/d' -e '/^\s*$/d' | awk '{split($0, a, "#"); if (length(a) > 1) print a[1]; else print $0;}' | awk '{split($0, a, "@"); if (length(a) > 1) print a[2]; else print $0;}' | xargs -n 1 pip install
cat requirements-devel.txt | sed -e '/^\s*-.*$/d' -e '/^\s*#.*$/d' -e '/^\s*$/d' | awk '{split($0, a, "#"); if (length(a) > 1) print a[1]; else print $0;}' | awk '{split($0, a, "@"); if (length(a) > 1) print a[2]; else print $0;}' | xargs -n 1 pip install # use this for full dependencies

# Register EasyVolcp for imports
pip install -e . --no-build-isolation --no-deps
```

--------------------------------

### Set shell variables for example dataset

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Defines shell variables used by subsequent commands to reference the example dataset and experiment name.

```shell
expname=actor1_4_subseq
data_root=data/enerf_outdoor/actor1_4_subseq

```

--------------------------------

### Render with minimal dataset using video config

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/realtime4dv.md

Render a model with the minimal dataset by appending configs/specs/video.yaml to the command. See configs/projects/realtime4dv/rendering for more examples.

```shell
# See configs/projects/realtime4dv/rendering for more
evc-gui -c configs/projects/realtime4dv/rendering/4k4d_0013_01.yaml,configs/specs/video.yaml
evc-gui -c configs/projects/realtime4dv/rendering/4k4d_sport1.yaml,configs/specs/video.yaml
evc-gui -c configs/projects/realtime4dv/rendering/4k4d_my_313.yaml,configs/specs/video.yaml
evc-gui -c configs/projects/realtime4dv/rendering/4k4d_dance3.yaml,configs/specs/video.yaml
evc-gui -c configs/projects/realtime4dv/rendering/4k4d_actor1_4.yaml,configs/specs/video.yaml
```

--------------------------------

### Test import order for diff-gaussian-rasterization

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/install.md

On some systems, the import order of CUDA-compiled extension and PyTorch matters. Importing PyTorch before the extension might fail; try changing the order if that happens.

```shell
python -c "from diff_gaussian_rasterization import _C" # works
python -c "import torch; from diff_gaussian_rasterization import _C" # might fail
python -c "from diff_gaussian_rasterization import _C; import torch" # should work
```

--------------------------------

### YAML config selecting CustomVolumetricVideoModule

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/how_to_contribute.md

Configuration snippet that selects the custom module by setting model_cfg.sampler_cfg.type to CustomVolumetricVideoModule. Use in the respective config file to activate the custom sampler.

```yaml
model_cfg:
    sampler_cfg:
        type: CustomVolumetricVideoModule
```

--------------------------------

### Remove and Create Swapfile

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Commands to remove an existing swapfile and create a new one. First, disable the swap with 'swapoff', remove the file, and delete its entry from /etc/fstab. Then create a new 512G swapfile, set permissions, format it, and enable it.

```shell
# Removing existing swapfiles
sudo swapoff -v /swapfile
# Remove the swap file entry /swapfile swap swap defaults 0 0 from the /etc/fstab file.
sudo rm /swapfile

# Creating swapfile
sudo fallocate -l 512G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```

--------------------------------

### Connect WebSocket client viewer (evc-ws)

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Launches a separate WebSocket client viewer. Replace the host IP and config file as needed; the enerf_outdoor.yaml provides a basic camera setup for the viewer.

```shell
# Separate WebSocket Client parameter and evc parameter with --, for now, the viewer can be configured with evc
# Replace 10.76.5.252 with your server IP
# Replace -c configs/datasets/enerf_outdoor/enerf_outdoor.yaml with what ever other config to use
# The enerf_outdoor.yaml here provides a basic camera setup for the viewer
evc-ws --host 10.76.5.252 --port 1024 -- -c configs/datasets/enerf_outdoor/enerf_outdoor.yaml viewer_cfg.window_size="768,1366" 

```

--------------------------------

### Install CUDA driver, toolkit, and CuDNN

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/cuda_pytorch.md

Shell commands to download and install the NVIDIA driver, CUDA toolkit, and CuDNN. Includes a note questioning the --no-driver flag for the toolkit installer.

```shell
# Installing CUDA Driver
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/525.116.04/NVIDIA-Linux-x86_64-525.116.04.run
chmod +x NVIDIA-Linux-x86_64-525.116.04.run
sudo ~/NVIDIA-Linux-x86_64-$(cat /sys/module/nvidia/version).run --accept-license --ui=none --no-kernel-module --no-questions

# Installing CUDA Toolkit
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
chmod +x cuda_12.1.0_530.30.02_linux.run
sudo cuda_12.1.0_530.30.02_linux.run --accept-license --ui=none --no-kernel-module --no-questions --no-driver # ?: is it really --no-driver

# Installing CuDNN
wget https://developer.download.nvidia.com/compute/cudnn/redist/cudnn/linux-x86_64/cudnn-linux-x86_64-8.9.0.131_cuda12-archive.tar.xz

tar -xvf cudnn-linux-x86_64-8.9.0.131_cuda12-archive.tar.xz
sudo cp cudnn-*-archive/include/cudnn*.h /usr/local/cuda/include
sudo cp -P cudnn-*-archive/lib/libcudnn* /usr/local/cuda/lib64
sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*
```

--------------------------------

### Import EasyVolcap modules and build custom viewer

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Shows how to import utility functions and the OpenGL-based viewer after installing EasyVolcap. The import works when running code, but autocompletion may fail in editors due to editable install compatibility; adjust editor settings or use a compatible install if warnings appear.

```python
# Import the logging and debugging functions
from easyvolcap.utils.console_utils import * # log, tqdm, @catch_throw
from easyvolcap.utils.timer_utils import timer  # timer.record
from easyvolcap.utils.data_utils import export_pts, export_mesh, export_npz
...

# Import the OpenGL-based viewer and build upon it
from easyvolcap.runners.volumetric_video_viewer import VolumetricVideoViewer

class CustomViewer(VolumetricVideoViewer):
    ...
```

--------------------------------

### Development install of EasyVolcap with pip

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Run these two commands in tandem to install PyTorch and EasyVolcap before compiling CUDA extensions. Requires a valid CUDA building environment with PyTorch already installed.

```shell
# Editable install, with dependencies from requirements-devel.txt
pip install -v -e . # will install from requirements.txt
pip install -v -r requirements-devel.txt
```

--------------------------------

### Example config chain: renbody.yaml, 0013_01.yaml, 0013_01_obj.yaml

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/design/config.md

Shows a parent config (renbody.yaml) with anchors and a child config (0013_01.yaml) that inherits via the 'configs' key and overrides dataset paths. The final child (0013_01_obj.yaml) further overrides bounds and inherits from 0013_01.yaml. Demonstrates recursive overwriting and YAML anchors for shared values.

```yaml
# Content of renbody.yaml (parent config)
dataloader_cfg: # we see the term "dataloader" as one word?
    dataset_cfg: &dataset_cfg
        masks_dir: masks # good naming ^_^
        ratio: 0.5
        bounds: [[-5.0, -5.0, -5.0], [5.0, 5.0, 5.0]] # thinner?

        force_sparse_view: True
        view_sample: [0, 60, 1]
        frame_sample: [0, 150, 1] # only train for a thousand frames

model_cfg:
    sampler_cfg:
        bg_brightness: 0.0
    renderer_cfg:
        bg_brightness: 0.0

val_dataloader_cfg:
    dataset_cfg:
        <<: *dataset_cfg
        frame_sample: [0, 150, 30]
    sampler_cfg:
        view_sample: [0, 60, 20]

```

```yaml
# Content of 0013_01.yaml (inner config, child of renbody.yaml, parent of 0013_01_obj.yaml)
configs: configs/datasets/renbody/renbody.yaml

dataloader_cfg: # we see the term "dataloader" as one word?
    dataset_cfg: &dataset_cfg
        data_root: data/renbody/0013_01
        images_dir: images_calib

val_dataloader_cfg:
    dataset_cfg:
        <<: *dataset_cfg

```

```yaml
# Content of 0013_01_obj.yaml (child of 0013_01.yaml)
configs: configs/datasets/renbody/0013_01.yaml

dataloader_cfg: &dataloader_cfg
    dataset_cfg: &dataset_cfg # ratio: 0.5
        bounds: [[-0.5352, -0.7697, -0.9967], [0.4148, 0.7203, 0.9533]] # !: BATCH

val_dataloader_cfg:
    dataset_cfg:
        <<: *dataset_cfg

```

--------------------------------

### Profile l3mhet training with evc-train

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Command to profile the l3mhet job with evc-train, setting profiler parameters and disabling resume.

```shell
# Profiling the l3mhet job
evc-train -c configs/exps/l3mhet/l3mhet_seq3.yaml exp_name=l3mhet_seq3_prof runner_cfg.ep_iter=50 runner_cfg.epochs=1 profiler_cfg.enabled=True profiler_cfg.skip_first=0 profiler_cfg.wait=40 profiler_cfg.warmup=5 profiler_cfg.active=5 profiler_cfg.repeat=1 profiler_cfg.clear_previous=False runner_cfg.resume=False
```

--------------------------------

### Run volume_fusion and extract_mesh for l3mhet

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Commands to run volume_fusion.py and extract_mesh.py for l3mhet configurations. The first command uses a ratio of 0.5 and view sample 0,None,6. The second command extracts a mesh with an occupancy threshold of 0.3.

```shell
python scripts/fusion/volume_fusion.py -- -c configs/exps/l3mhet/l3mhet_xuzhen_static.yaml configs=configs/specs/fp16.yaml,configs/specs/vis.yaml val_dataloader_cfg.dataset_cfg.ratio=0.5 val_dataloader_cfg.dataset_cfg.view_sample=0,None,6
```

```shell
python scripts/tools/extract_mesh.py --occ_thresh 0.3 -- -c configs/exps/l3mhet/l3mhet_0008_05_static.yaml
```

--------------------------------

### Run evc-test for stableenerf and l3mhet seq3

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Commands to run evc-test for stableenerf and l3mhet seq3 configurations. The first command tests stableenerf with immask and imbound crop settings. The second command tests l3mhet seq3 with render size, smoothing term, and number of views.

```shell
evc-test -c configs/projects/stableenerf/enerf/enerf_my_313_se.yaml runner_cfg.visualizer_cfg.save_tag=dtu_pretrain val_dataloader_cfg.dataset_cfg.immask_crop=False val_dataloader_cfg.dataset_cfg.imbound_crop=False val_dataloader_cfg.dataset_cfg.immask_fill=True
```

```shell
evc-test -c configs/exps/l3mhet/l3mhet_seq3.yaml exp_name=l3mhet_seq3 configs=configs/specs/fp16.yaml,configs/specs/interp.yaml val_dataloader_cfg.dataset_cfg.render_size=1080,1920 val_dataloader_cfg.dataset_cfg.smoothing_term=15.0 val_dataloader_cfg.dataset_cfg.n_render_views=300
```

--------------------------------

### Run evc-test for l3mhet and enerf configurations

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Commands to run evc-test with various configurations for l3mhet and enerf experiments. The first command tests l3mhet with a specific voxel size and frame sample. The second and third commands test enerf with different settings, including render size, smoothing term, and number of views.

```shell
evc-test -c configs/exps/l3mhet/l3mhet_ipstage.yaml configs=configs/specs/geometry.yaml val_dataloader_cfg.dataset_cfg.voxel_size=0.05 val_dataloader_cfg.dataset_cfg.frame_sample=0,1,1
```

```shell
evc-test -c configs/exps/enerf/enerf_seq3.yaml exp_name=enerf_dtu configs=configs/specs/fp16.yaml,configs/specs/cubic.yaml,configs/specs/ibr.yaml val_dataloader_cfg.dataset_cfg.render_size=1080,1920 val_dataloader_cfg.dataset_cfg.smoothing_term=15.0 val_dataloader_cfg.dataset_cfg.n_render_views=300 runner_cfg.visualizer_cfg.save_tag=seq3
```

```shell
evc-test -c configs/exps/enerf/enerf_seq3.yaml exp_name=enerf_dtu configs=configs/specs/fp16.yaml,configs/specs/cubic.yaml,configs/specs/ibr.yaml runner_cfg.visualizer_cfg.save_tag=seq3 val_dataloader_cfg.dataset_cfg.render_size=1080,1920 val_dataloader_cfg.dataset_cfg.smoothing_term=15.0 val_dataloader_cfg.dataset_cfg.n_render_views=300 val_dataloader_cfg.batch_sampler_cfg.n_srcs_list=2,
```

--------------------------------

### Dataset configuration YAML example (enerf_outdoor.yaml)

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/custom_dataset.md

YAML configuration for a dataset in EasyVolcap. The near, far, and bounds parameters define the global sampling range and bounding box for the scene, used to refine per-ray near/far values.

```yaml
dataloader_cfg:
    dataset_cfg:
        near: 3.5 # global near for the specific scene
        far: 9.0 # global far for the specific scene
        bounds: [[-3.0, -3.0, -2.0], [3.0, 3.0, 2.0]] # global bounds for the specific scene
```

--------------------------------

### Install EasyVolcap core dependencies with pip

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Editable install using dependencies from requirements.txt. On Windows or older Linux, this may result in a CPU-only PyTorch installation because only the CPU version for Windows is available on PyPI.

```shell
# Editable install, with dependencies from requirements.txt
pip install -v -e . 
```

--------------------------------

### Train single-frame ENeRF for installation check

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/enerf.md

Runs a quick single-frame training on the first frame of the actor1 sequence to verify installation and dataset preparation. Expect training PSNR to reach 23-24 dB within the first 100-200 iterations; otherwise, check for bugs. Missing packages may stop training and should be installed with pip.

```shell
evc-train -c configs/exps/enerf/enerf_actor1.yaml,configs/specs/static.yaml exp_name=check
```

--------------------------------

### Train single-frame 4K4D on DNA-Rendering (evc-train)

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/realtime4dv.md

Use this shell command to test installation and training on the first frame of the 0013_01 sequence. During the first 100-200 iterations, training PSNR should increase to 24-25 dB; otherwise check dataset preparation or installation.

```shell
evc-train -c configs/exps/4k4d/4k4d_0013_01_r4.yaml,configs/specs/static.yaml,configs/specs/tiny.yaml exp_name=4k4d_0013_01_r4_static
```

--------------------------------

### Run EasyVolcap GUI with UnitySocketViewer for ENeRF++

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/srdisplay.md

Starts the EasyVolcap GUI rendering server for the ENeRF++ model on the online telepresence system, using the UnitySocketViewer. Sets render size to 480x640, skips exceptions, and centers the scene at index 2.

```shell
evc-gui -c configs/exps/enerfpp/enerfpp_online_complex.yaml exp_name=enerfpp_static viewer_cfg.type=UnitySocketViewer viewer_cfg.render_size=480,640 viewer_cfg.skip_exception=True viewer_cfg.scene_center_index=2
```

--------------------------------

### Render ENeRFi with GUI (evc-gui)

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Launches an interactive GUI renderer for ENeRFi. The ratio=0.5 setting achieves about 2.5 FPS on an NVIDIA 3060.

```shell
# Render ENeRFi with GUI
evc-gui -c configs/exps/enerfi/enerfi_${expname}.yaml exp_name=enerfi_dtu val_dataloader_cfg.dataset_cfg.ratio=0.5 # 2.5 FPS on 3060

```

--------------------------------

### Export video for technical communications

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/misc/tricks.md

Command to export a video for easyvolcap technical communications using evc-test with specific rendering settings.

```shell
# Export video for easyvolcap technical communications
evc-test -c configs/exps/r4dv/r4dv_0013_01_optcam.yaml exp_name=scr4dv_0013_01_optcam configs=configs/specs/superf.yaml val_dataloader_cfg.dataset_cfg.frame_sample=0,150,1 val_dataloader_cfg.dataset_cfg.camera_path_intri=data/paths/0013_01/intri.yml val_dataloader_cfg.dataset_cfg.camera_path_extri=data/paths/0013_01/extri.yml configs=configs/specs/superf.yaml,configs/specs/cubic.yaml,configs/specs/ibr.yaml val_dataloader_cfg.dataset_cfg.smoothing_term=10.0 model_cfg.sampler_cfg.should_release_memory=False val_dataloader_cfg.dataset_cfg.ratio=1.0 val_dataloader_cfg.dataset_cfg.render_size=2160,3840 val_dataloader_cfg.dataset_cfg.n_render_views=600 runner_cfg.visualizer_cfg.vis_ext=.png runner_cfg.visualizer_cfg.video_fps=60 runner_cfg.visualizer_cfg.dpt_cm=virdis
```

--------------------------------

### Normal training with evc-train

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/enerfpp.md

Starts training for the enerfpp_actor1_4 experiment using the specified config file. Sets exp_name and disables resume to start fresh.

```shell
evc-train -c configs/exps/enerfpp/enerfpp_actor1_4.yaml exp_name=enerfpp_actor1_4 runner_cfg.resume=False
```

--------------------------------

### Train, render, and GUI commands for l3mhet model

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Run these shell commands after preparing config files to train the l3mhet model, render output with a spiral path, and launch a GUI at lower resolution. Requires tiny-cuda-nn installed. The spiral.yaml config generates a spiral path by interpolating given cameras.

```shell
evc-train -c configs/exps/l3mhet/l3mhet_${expname}.yaml
```

```shell
evc-test -c configs/exps/l3mhet/l3mhet_${expname}.yaml,configs/specs/spiral.yaml
```

```shell
evc-gui -c configs/exps/l3mhet/l3mhet_${expname}.yaml viewer_cfg.render_ratio=0.15
```

--------------------------------

### Train, render, and GUI for 3DGS+T with evc commands

Source: https://github.com/zju3dv/easyvolcap/blob/main/readme.md

Commands to train a 3DGS model, perform network-only rendering, and launch the GUI for a given experiment. Training may run out of VRAM; reduce densify until iter. The superm.yaml spec skips input image loading for network-only rendering.

```shell
# Train a 3DGS model on the ${expname} dataset
evc-train -c configs/exps/gaussiant/gaussiant_${expname}.yaml # might run out of VRAM, try reducing densify until iter

# Perform rendering on the trained ${expname} dataset
evc-test -c configs/exps/gaussiant/gaussiant_${expname}.yaml,configs/specs/superm.yaml,configs/specs/spiral.yaml

# Perform rendering with GUI, do this on a machine with monitor, tested on Windows and Ubuntu
evc-gui -c configs/exps/gaussiant/gaussiant_${expname}.yaml
```

--------------------------------

### Static scene GUI rendering with evc-gui

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/realtime4dv.md

Launches the GUI for real-time rendering of the static scene.

```shell
evc-gui -c configs/exps/4k4d/4k4d_${expname}_r4_static.yaml,configs/specs/superb.yaml exp_name=4k4d_${expname}_static
```

--------------------------------

### Run EasyVolcap GUI with UnitySocketViewer for 4K4D

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/srdisplay.md

Starts the EasyVolcap GUI rendering server for the 4K4D model on the DNA-Rendering dataset, using the UnitySocketViewer to stream frames to the Unity client. Sets render size to 2160x3840, skips exceptions, enables autoplay, and centers the scene at index 22.

```shell
evc-gui -c configs/projects/realtime4dv/rendering/4k4d_0013_01.yaml val_dataloader_cfg.dataset_cfg.frame_sample=0,1,1 viewer_cfg.type=UnitySocketViewer viewer_cfg.render_size=2160,3840 viewer_cfg.skip_exception=True viewer_cfg.autoplay=True viewer_cfg.scene_center_index=22
```

--------------------------------

### Install requirements excluding open3d

Source: https://github.com/zju3dv/easyvolcap/blob/main/requirements-devel.txt

Command to install all packages from requirements.txt except open3d, useful if open3d installation fails. Filters out lines starting with '#' and the open3d line.

```bash
pip install $(grep -v '^ *#\|^open3d' requirements.txt | grep .)
```

--------------------------------

### Real-time rendering in GUI with evc-gui

Source: https://github.com/zju3dv/easyvolcap/blob/main/docs/projects/realtime4dv.md

Launches the GUI for real-time rendering. Uses the superb spec and sets the experiment name.

```shell
evc-gui -c configs/exps/4k4d/4k4d_${expname}_r4.yaml,configs/specs/superb.yaml exp_name=4k4d_${expname}
```
Tokens:
Raw