- Install the latest Rust compiler from the official website
- Verify if
cargoandrustchave been installed successfully usingcargo --versionandrustc --version - If you are using linux, make sure
gcc,g++,cmake,libssl-dev,pkg-config,libfontconfig1-devare installed - Compile and build the binaries with
cargo build --release --bins - Install the binaries if you want to use it anywhere you want.
cargo install --path . - Use
vv,vvplayandvvplay_asyncin other directory. Now you are good to go! - Download the 8i_dataset to use and test our tool!
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 helpExample
vv read ./ply_ascii +output=ply_a \
write --output-format pcd --storage-type binary \
./pcd_binary +input=ply_aAlternatively, 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_aReads 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 helpvv read ./Ply +output=plysRead only 10 files from a folder, specifying --num is useful to check the command is working as expected.
vv read ./Ply --num 10 +output=plysWrites 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 helprender to png example
vv read ./Ply +output=plys \
render ./Pngs +input=plysrender 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 20Calculates 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 helpThe following command will write all metrics.
vv read ./original +output=original \
read ./reconstructed +output=reconstructed \
metrics +input=original,reconstructed +output=metrics \
write ./metrics +input=metricsSpecify 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=metricsWrites 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 helpWriting metrics
vv read ./original +output=original \
read ./reconstructed +output=reconstructed \
metrics +input=original,reconstructed +output=metrics \
write ./metrics +input=metrics 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 helpPoisson reconstruction
- Usage
--method spsr- Poisson reconstruction requires the point normals, acquired from the
normalcommand, 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_depthset 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
10should 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
plyfile.
- 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 \
upsample --method default --factor 2 +input=pcdb +output=pcdb_up \
write ./pcd_up \
+input=pcdb_up \
--storage-type binary \
--output-format plyUpsampling a file using poisson reconstruction
vv read ./ply +output=ply \
normal +input=ply +output=ply_n \
upsample --method spsr --screening 0.5 +input=ply_n +output=ply_spsr \
write ./ply_spsr \
+input=ply_spsr \
--storage-type binary \
--output-format plydownsamples a point cloud.
Usage: downsample --points-per-voxel <POINTS_PER_VOXEL>
Options:
-p, --points-per-voxel <POINTS_PER_VOXEL>
-h, --help Downsampling a file
Downsamples pcd files and write as ply binary
vv read ./pcd +output=pcdb \
downsample -p 2 +input=pcdb +output=pcdb_down \
write ./pcdb_down \
+input=pcdb_down \
--storage-type binary \
--output-format plyPerforms normal estimation on a point cloud.
Usage: normal --k <NUMBER_OF_NEIGHBORING_POINTS>Normal Estimation Example
Performs normal estimation on ply files and write the computed normals back to the ply files.
.\vv read ".\Ply" +output=ply_a \
normal --k 30 +input=ply_a +output=normal_a \
write --output-format ply ./test +input=normal_aComplex Example
vv read ./pcd +output=pcdb \
read ./pcd_compressed +output=pcd_comp \
downsample -p 5 +input=pcdb +output=pcdb_down \
upsample -f 2 +input=pcdb_down +output=pcdb_down_up \
metrics +input=pcd_comp,pcdb_down_up +output=metric \
write ./metrics +input=metric \
write ./down_up +input=pcdb_down_up \
render ./tmp/down_up +input=pcdb_down_up We recognize that some users may just want to convert a file from one format to another. So convert is provided as a shortcut for read and write. Currently we support any conversion between ply and pcd. We also support converting files from velodyne's bin file to ply/pcd. For convert, named input-ouput is not needed.
Usage: convert [OPTIONS] --output <OUTPUT>
Options:
-o, --output <OUTPUT>
--output-format <OUTPUT_FORMAT> [default: pcd]
-s, --storage-type <STORAGE_TYPE> [default: binary]
-i, --input <INPUT>
-h, --help Print helpconvert from ply to pcd(binary)
vv convert --input ./ply_a --output ./pcd_bconvert from pcd to ply(ascii)
vv convert --input ./pcd_b --output ./ply_a --storage-type ascii --output-format plyconvert from pcd(binary) to pcd(ascii)
vv convert --input ./pcd_b --output ./pcd_a --storage-type ascii --output-format pcdA preprocessing step to optimize point cloud data for adaptive playback in vvplay
Hyperparameters:
- Threshold: Manages the structural property (e.g. distribution of the points)
- Partitions: Manages how the point cloud is segmented for detail distribution.
Usage: lodify [OPTIONS] <PATH>
Arguments:
<PATH>
Options:
-x, --x-partition <X_PARTITION> [default: 2]
-y, --y-partition <Y_PARTITION> [default: 2]
-z, --z-partition <Z_PARTITION> [default: 2]
-b, --base-proportion <BASE_PROPORTION> [default: 30]
-t, --threshold <POINTS_PER_VOXEL_THRESHOLD> [default: 10]
-h, --help Print helpLodifying Point Clouds
This command constructs a base layer using about 30% of the original points to capture the core structure, while the remaining 70% are reserved to incrementally add detail as needed.
vv read ./Pcd_b +output=pcdb \
lodify +input=pcdb +output=pcdb_lod \
write ./Pcd_lod \
+input=pcdb_lod \
--storage-type binary \
--output-format pcdGet the info of a pointcloud file or directory. Supported formats are .pcd and .ply. If no option is specified, all info will be printed.
Usage: info [OPTIONS] <PATH>
Arguments:
<PATH>
Options:
--num-of-points Get the number of points in a file
--format Get the format of a file
--num-of-frames Get the number of frames in a directory
-h, --help Print helpExamples
info for a pointcloud file
vv info foo.plyThe encoding format(ascii or binary) of the file, the number of points will be printed.
format: pcd ASCII
number of points: 693899info for a directory that contains pointcloud file
vv info ./longdress/PlyThe encoding format(ascii or binary) of the file in the directory, the number frames and the average of points will be printed.
format: pcd BINARY
number of frames: 240
average number of points: 728297.04If more than one file format exists in the given directory, the summary of respective type will be printed.
vv info ./longdress/all_typeswill output
format: pcd ASCII
number of frames: 2
average number of points: 688515.00
format: ply BINARY
number of frames: 2
average number of points: 649491.00
format: pcd BINARY
number of frames: 2
average number of points: 671719.00
format: ply ASCII
number of frames: 2
average number of points: 688515.00Dash will simulate a varying network conditions, it 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: dash [OPTIONS] <FILES>... +output=plys
Arguments:
<INPUT_PATH> input directory with different quality of point clouds
<NETWORK_PATH> path to network settings
Options:
-a, --algorithm <ALGORITHM> [default: naive] [possible values: naive, quetra]
-n, --num <NUM> read previous n files after sorting lexicalgraphically
-t, --filetype <FILETYPE> [default: all] [possible values: all, ply, pcd, bin]
-h, --help Print helpPreparation
An example of network setting file is provided in ./test_files/dash/sim_nw_avg_14050.txt
The structure of input directory with different quality of point clouds should be the following.
INPUT_PATH
├── R01
│ ├── r1_longdress_dec_0000.pcd
│ ├── ***
│ └── r1_longdress_dec_0299.pcd
├── R02
│ ├── r2_longdress_dec_0000.pcd
│ ├── ***
│ └── r2_longdress_dec_0299.pcd
├── R03
│ ├── r3_longdress_dec_0000.pcd
│ ├── ***
│ └── r3_longdress_dec_0299.pcd
├── R04
│ ├── r4_longdress_dec_0000.pcd
│ ├── ***
│ └── r4_longdress_dec_0299.pcd
└── R05
├── r5_longdress_dec_0000.pcd
├── ***
└── r5_longdress_dec_0299.pcdUsage
vv dash ./input ./sim_nw_avg_14050.txt -a quetra +out=dash \
write --output-format pcd --storage-type binary \
./pcd_quetra +in=dashextend can be used to run external subcommands that is in the form of executable. Read extension.md for more details on creating subcommands and test.md on testing extend.
Extend is used for running custom subcommands.
Usage: extend [OPTIONS] <CMD_NAME>
Arguments:
<CMD_NAME> Command name of the extension without the vv-prefix
Options:
-x, --xargs <XARGS>... Arguments that needs to pass in to the binary executable, value separate by comma
-h, --help Print helpExample:
Read a ply-ascii file, pass to ~/.cargo/bin/vv-test-executable then perform downsample.
vv read ./test_files/ply_ascii/ +output=plyc \extend test-executable +input=plyc +output=plyd \downsample -p 2 +input=plyd
Read a ply-ascii, then pass to ~/.cargo/bin/vv-test-args that takes in two command line argument.
vv read ./test_files/ply_ascii/ +output=plyc \extend test-args +input=plyc --xargs=hello,world
Plays a folder of pcd/ply/bin files in lexicographical order. A window will appear upon running the binary from which you can navigate using your mouse and keyboard. Controls are described further below.
Plays a folder of point cloud files in lexicographical order
Usage: vvplay [OPTIONS] <SRC>
Arguments:
<SRC> src can be: 1. Directory with all the pcd files in lexicographical order 2. location of the mpd file
Options:
-q, --quality <QUALITY> [default: 0]
-f, --fps <FPS> [default: 30]
-x, --camera-x <CAMERA_X> [default: 0]
-y, --camera-y <CAMERA_Y> [default: 0]
-z, --camera-z <CAMERA_Z> [default: 1.3]
--yaw <CAMERA_YAW> [default: -90]
--pitch <CAMERA_PITCH> [default: 0]
-W, --width <WIDTH> [default: 1600]
-H, --height <HEIGHT> [default: 900]
--controls
-b, --buffer-size <BUFFER_SIZE>
-m, --metrics <METRICS>
--decoder <DECODER_TYPE> [default: noop] [possible values: noop, draco]
--decoder-path <DECODER_PATH>
--bg-color <BG_COLOR> [default: rgb(255,255,255)]
--adaptive-upsampling [default: False]
-h, --help Print helpPlays a folder of ply files in lexicographical order, leveraging prefetching and playback caching for optimized performance. A window will appear upon running the binary from which you can navigate using your mouse and keyboard. Controls are described further below.
Usage: vvplay_async [OPTIONS] <SRC>
Arguments:
<SRC> src can be:
Options:
-f, --fps <FPS>
[default: 30]
-x, --camera-x <CAMERA_X>
[default: 0]
-y, --camera-y <CAMERA_Y>
[default: 0]
-z, --camera-z <CAMERA_Z>
[default: 1.5]
--pitch <CAMERA_PITCH>
[default: 0]
--yaw <CAMERA_YAW>
[default: -90]
-W, --width <WIDTH>
Set the screen width [default: 1600]
-H, --height <HEIGHT>
Set the screen height [default: 900]
--controls
-b, --buffer-capacity <BUFFER_CAPACITY>
buffer capacity in seconds
-m, --metrics <METRICS>
--abr <ABR_TYPE>
[default: quetra] [possible values: quetra, quetra-multiview, mckp]
--decoder <DECODER_TYPE>
[default: noop] [possible values: noop, draco, tmc2rs]
--multiview
Set this flag if each view is encoded separately, i.e. multiview
--decoder-path <DECODER_PATH>
Path to the decoder binary (only for Draco)
--tp <THROUGHPUT_PREDICTION_TYPE>
[default: last] [possible values: last, avg, ema, gaema, lpema]
--throughput-alpha <THROUGHPUT_ALPHA>
Alpha for throughput prediction. Only used for EMA, GAEMA, and LPEMA [default: 0.1]
--vp <VIEWPORT_PREDICTION_TYPE>
[default: last] [possible values: last]
--network-trace <NETWORK_TRACE>
Path to network trace for repeatable simulation.
Network trace is expected to be given in Kbps
--camera-trace <CAMERA_TRACE>
Path to camera trace for repeatable simulation.
Camera trace is expected to be given in
(pos_x, pos_y, pos_z, rot_pitch, rot_yaw, rot_roll).
Rotation is in degrees
--record-camera-trace <RECORD_CAMERA_TRACE>
Path to record camera trace from the player
--enable-fetcher-optimizations
Enable fetcher optimizations
--bg-color <BG_COLOR>
[default: rgb(255,255,255)]
-h, --help
Print help (see more with '--help')With the main screen focused,
WKey - Moves your position to the frontAKey - Moves your position to the leftSKey - Moves your position to the backDKey - Moves your position to the rightQKey - Moves your position upEKey - Moves your position down0Key - Resets your position to the initial positionSpaceKey - Toggles Play/PauseLeftArrowKey - Rewinds by 1 frameRightArrowKey - Advances by 1 frameMouseDrag - Adjusts camera yaw / pitch (Hold right click on Mac, left click on Windows)LKey - Rotates camera horizontally(around the Y axis) clockwiseJKey - Rotates camera horizontally(around the Y axis) counterclockwiseIKey - Rotates camera vertically(around the X axis) clockwiseKKey - Rotates camera vertically(around the X axis) counterclockwise- Adjusts camera yaw/picth with mouse (Hold right click on Mac, left click on Windows)
With the secondary window focused,
The Play/Pause button toggles between play and pause. The slider allows you to navigate to any frame you wish.
The information displayed in the window are:
- Current Frame / Total Frames
- Camera Information - Useful to recreate a certain view through command line arguments
The following command will play all .pcd files in the ./pcds/ directory.
vvplay ./pcdsYou can buffer the render with a set number of frames using -b
vvplay ./pcds -b 100You can specify the background color using --bg-color in the following two ways.
- use rgb value: rgb(r,g,b)
- use hex rgb number: #RRGGBB
vvplay ./pcds --bg-color "#9ef244"
vvplay ./pcds --bg-color "rgb(10,23,189)"Use Rust 1.69
We follow the official Rust coding style. You can use rustfmt (or run cargo fmt) to automatically format your code.