VVTk: A Toolkit for Volumetric Video Researchers

How to Install?

1. Install the latest Rust compiler from the official website
2. Verify if cargo and rustc have been installed successfully using cargo --version and rustc --version
3. If you are using linux, make sure gcc, g++, cmake, libssl-dev, pkg-config, libfontconfig1-dev are installed
4. Compile and build the binaries with cargo build --release --bins
5. Install the binaries if you want to use it anywhere you want. cargo install --path .
6. Use vv, vvplay and vvplay_async in other directory. Now you are good to go!
7. Download the 8i_dataset to use and test our tool!

Commands

vv

Provides subcommands that can be chained together. The inputs and outputs of a subcommand must be specified with the +input= or +in followed by a comma separated list of inputs or +output= or +out to denote the name of its output stream. Note that +input must be specified for commands other than read.

Usage: vv <COMMAND>

Commands:
  convert     Converts a pointcloud file from one format to another.
                  Supported formats are .pcd and .ply.
                  Supported storage types are binary and ascii.
  write       Writes from input stream into a file, input stream can be pointcloud data or metrics
  read        Reads in one of our supported file formats. 
                  Files can be of the type .pcd .ply. 
                  The path can be a file path or a directory path contains these files.
  render      Writes point clouds from the input stream into images
  metrics     Calculates the metrics given two input streams.
                  First input stream is the original.
                  Second is the reconstructed.
                  Then uses write command to write the metrics into a text file.
  downsample  Downsample a pointcloud from the stream
  upsample    Upsamples a pointcloud from the stream
  normal      Performs normal estimation on point clouds.
  info        Get the info of a pointcloud file or directory.
                  Supported formats are .pcd and .ply.
                  If no option is specified, all info will be printed.
  lodify       Preprocesses point cloud data for adaptive playback in vvplay
  dash        Dash will simulate a varying network conditions. 
                  Dash reads in one of our supported file formats. 
                  Files can be of the type .pcd .ply. 
                  The path can be a file path or a directory path contains these files.
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Example

vv read ./ply_ascii +output=ply_a \
        write --output-format pcd --storage-type binary \
        ./pcd_binary +input=ply_a

Alternatively, you can use +in and +out as a shortcut to +input and +output.

vv read ./ply_ascii +out=ply_a \
        write --output-format pcd --storage-type binary \
        ./pcd_binary +in=ply_a

read

Reads in one of our supported file formats. Files can be of the type .pcd .ply. The path can be a file path or a directory path contains these files.

Usage: read [OPTIONS] [FILES]...

Arguments:
  [FILES]...  Files, glob patterns, directories

Options:
  -t, --filetype <FILETYPE>  [default: all] [possible values: all, ply, pcd]
  -n, --num <NUM>            read previous n files after sorting lexicalgraphically
  -h, --help                 Print help

vv read ./Ply +output=plys

Read only 10 files from a folder, specifying --num is useful to check the command is working as expected.

vv read ./Ply --num 10 +output=plys

render

Writes point clouds from the input stream into images(png) or videos(mp4). To render point clouds into mp4, you need to make sure ffmepg is installed.

Usage: render [OPTIONS] <OUTPUT_DIR> 

Arguments:
  <OUTPUT_DIR>  Directory to store output png images

Options:
  -x, --camera-x <CAMERA_X>        [default: 0]
  -y, --camera-y <CAMERA_Y>        [default: 0]
  -z, --camera-z <CAMERA_Z>        [default: 1.8]
      --yaw <CAMERA_YAW>           [default: -90]
      --pitch <CAMERA_PITCH>       [default: 0]
      --width <WIDTH>              [default: 1600]
      --height <HEIGHT>            [default: 900]
      --name-length <NAME_LENGTH>  [default: 5]
      --bg-color <BG_COLOR>        [default: rgb(255,255,255)]
      --format <RENDER_FORMAT>     [default: png] [possible values: png, mp4]
      --fps <FPS>                  [default: 30]
      --verbose
  -h, --help                       Print help

render to png example

vv read ./Ply +output=plys \
        render ./Pngs +input=plys

render to mp4 example

Read 60 frames of pointcloud and render them into a mp4 video with fps=20. This is done by first render them into png files, and then use ffmpeg to convert the images into a mp4 video.

vv read -n 60 ./pcd +output=pcd \
    render ./mp4 \
    +input=f --format mp4 --fps 20

metrics

Calculates the metrics given two input streams where the first input stream is the original and the second is the reconstructed one. Then uses write command to write the metrics into a text file. Currently we support a number of commanly used metrics such as ACD(Asymmetric Chamfer Distance), CD(Chamfer Distance), CD-PSNR, HD(Hausdorff Distance), L-CPSNR(Luminance Color PSNR), VQoE(Viola et al.’s QoE). If no metric is specified, all metrics will be outputed.

Usage: metrics [OPTIONS]

Options:
  -m, --metrics <METRICS>...  [default: all] [possible values: acd, cd, cd-psnr, hd, lc-psnr, v-qoe, all]
  -h, --help             Print help

The following command will write all metrics.

vv read ./original +output=original \
        read ./reconstructed +output=reconstructed \
        metrics +input=original,reconstructed +output=metrics \
        write ./metrics +input=metrics

Specify the metrics by using --metrics, use space ',' as a delimiter for more than one metric.

vv read ./original +output=original \
        read ./reconstructed +output=reconstructed \
        metrics +input=original,reconstructed +output=metrics --metrics acd,cd,hd \
        write ./metrics +input=metrics

write

Writes from input stream into a file, input stream can be pointcloud data or metrics

Usage: write [OPTIONS] <OUTPUT_DIR>

Arguments:
  <OUTPUT_DIR>  output directory to store point cloud files or metrics

Options:
      --output-format <OUTPUT_FORMAT>  [default: pcd]
  -s, --storage-type <STORAGE_TYPE>    [default: binary]
      --name-length <NAME_LENGTH>      [default: 5]
  -h, --help                           Print help

Writing metrics

vv read ./original +output=original \
        read ./reconstructed +output=reconstructed \
        metrics +input=original,reconstructed +output=metrics \
        write ./metrics +input=metrics 

upsample

Upsamples a point cloud using the default interpolation method or poisson reconstruction.

Usage: upsample --method <METHOD> [OPTIONS]

Options:
  -m, --method <METHOD>                  [default: default]
  -f, --factor <FACTOR>                  [default: 0]
  -s, --screening <SCREENING>            [default: 0.0] 
  -d, --density-estimation-depth <DEPTH> [default: 6] 
      --max-depth <MAX_DEPTH>            [default: 6] 
      --max-relaxation-iters <MAX_ITERS> [default: 10] 
  -c, --colour                           [default: true] 
      --faces                            [default: false] 
  -h, --help             Print help

Poisson reconstruction

• Usage
  • --method spsr
  • Poisson reconstruction requires the point normals, acquired from the normal command, used to estimate point normals
• Options
  • Screening: relates to the influence of outlier points during the reconstruction. A higher screening value will reduce the influence of potential outliers in the point cloud, making the reconstructed surface less sensitive to noise. A value of 0 means no screening.
  • Density estimation depth: the depth on the multigrid solver where point density estimation is calculated. The estimation kernel radius will be equal to the maximum extent of the input point’s AABB, divided by 2.pow(max_depth). Smaller value of this parameter results in more robustness wrt. occasional holes and sampling irregularities, but reduces thedetail accuracies.
  • Max depth: the max depth of the multigrid solver. Larger values result in higher accuracy (which requires higher sampling densities, or a density_estimation_depth set to a smaller value). Higher values increases computation times.
  • Max relaxation iters: the maximum number of iterations for the internal conjugate-gradient solver. Values around 10 should be enough for most cases.
  • Colour: disables colour on the reconstructed point cloud.
  • Faces: Adds the reconstructed triangle surface mesh to the output point cloud, only compatible when output is a ply file.
• Changes from original algorithm
  • Hierarchical clustering of point constraints optimisation
  • Added colouring of reconstructed point cloud, stored with a kd-tree
  • Added ability to construct triangle face mesh

More details on the poisson reconstruction algorithm used

Upsampling a file using default interpolation

Upsamples pcd files and write as ply binary

vv read ./pcd +output=pcdb \