Skip to content

Latest commit

 

History

History
294 lines (237 loc) · 7.3 KB

README.md

File metadata and controls

294 lines (237 loc) · 7.3 KB

Surround 360 Rendering Software

Surround 360 is a hardware and software system for capturing and rendering 3d (stereo) 360 videos and photos, suitable for viewing in VR. This subdirectory of the project is specific to rendering software.

Requirements

  • The Surround 360 rendering software requires either Linux or Mac OS X

  • The essential dependencies of the Surround 360 rendering software are:

    • CMake
    • gflags
    • glog
    • OpenCV 3.0+

  • Additional optional functionality depends on:

    • ffmpeg
    • Gooey
    • wx

Installing Dependencies of the Surround 360 Rendering Software

  • After building all of the dependencies and the rendering code itself, there are no further installation steps.

  • The build system for the Surround 360 code is CMake.

  • This software has been tested on Ubuntu 14.04/16.04 LTS (CMake 3.2.2) and OS X 10.11.5 (using CMake 3.5.1).

  • If you are building on OS X, it may be more convenient to use brew to install some dependencies.

  • Install CMake (method 1): see https://cmake.org

  • Install CMake (method 2 - Linux only)

  sudo apt-get install software-properties-common
  sudo add-apt-repository ppa:george-edison55/cmake-3.x
  sudo apt-get update
  sudo apt-get install cmake && sudo apt-get upgrade cmake

  ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  • Git is used to download and install packages from source (e.g. OpenCV below). Git may come preinstalled (check using git --version). It is not required if using brew in OS X.

  • Install Git (method 1 - Linux only):

  sudo apt-get install git
  • Install Subversion (method 1 - Linux only):
  sudo apt install subversion
  • Install Subversion (method 1 - OS X only):
  brew install subversion
  • Install Git (method 2 - OS X only):
  brew install git
  • Install Python (method 1 - Linux only):
  sudo apt-get install python python-dev
  • Install Python (method 2 - OS X only):
  brew install python
  • Install gflags (method 1 - Linux only):
  sudo apt-get install libgflags2v5 libgflags-dev
  • Install gflags (method 2 - OS X only):
  brew install gflags
  • Install glog (method 1 - Linux only):
  sudo apt-get install libgoogle-glog-dev
  • Install glog (method 2 - OS X only):
  brew install glog

  brew install folly

  sudo apt-get install libatlas-base-dev
  sudo apt-get install libeigen3-dev
  cd ~
  git clone https://ceres-solver.googlesource.com/ceres-solver
  cd ceres-solver
  git checkout 85c6b5c
  mkdir ceres-bin
  cd ceres-bin
  cmake ..
  make -j3
  sudo make install
  sudo ln -s /usr/include/eigen3/Eigen /usr/local/include/Eigen
  • Install Ceres (method 2 - OSX only):
  brew install --build-from-source homebrew/science/ceres-solver
  • Install pip (OSX only):
  pip install --upgrade pip
  • Install numpy (method 1 - Linux only):
  sudo apt-get install python-numpy
  • Install numpy (method 2 - OSX only):
  pip install numpy
  • Install OpenCV (method 1 - Linux only):
  cd ~
  git clone https://github.com/Itseez/opencv.git
  cd opencv
  git checkout f109c01
  cmake -DWITH_IPP=OFF
  make
  sudo make install
  • Install OpenCV (method 2 - OSX only):
  cd ~
  git clone https://github.com/Itseez/opencv.git
  cd opencv
  git checkout f109c01
  cmake -DWITH_IPP=OFF \
  -DPYTHON2_PACKAGES_PATH=/usr/local/lib/python2.7/site-packages \
  -DPYTHON2_LIBRARIES=/usr/local/Cellar/python/2.7.13/Frameworks/Python.framework/Versions/2.7/bin \
  -DPYTHON2_INCLUDE_DIR=$(python -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
  -DBUILD_opencv_python2=ON \
  -DHAVE_opencv_python2=ON
  make
  sudo make install

  brew install ffmpeg

  sudo apt-get install python-pip
  sudo pip install --upgrade pip
  sudo pip install Gooey
  sudo apt-get install python-wxgtk2.8

If python-wxgtk2.8 not available (e.g. Ubuntu 16.04):

  echo "deb http://archive.ubuntu.com/ubuntu wily main universe" | sudo tee /etc/apt/sources.list.d/wily-copies.list
  sudo apt update
  sudo apt install python-wxgtk2.8
  sudo rm /etc/apt/sources.list.d/wily-copies.list
  sudo apt update
  • Install Gooey (method 3 - OS X only):
  sudo pip install Gooey
  brew install wxpython
  brew install wxmac
  brew link wxmac
  • Install PIL (method 1 - Linux only)
  sudo apt-get install python-pil
  • Install PIL (method 2 - OSX only)
  pip install pillow
  • Install extra dependencies (Linux only):
  sudo apt-get install libtinfo-dev libjpeg-dev
  • (to use accelerated ISP) Install LLVM
  cd ~
  svn co https://llvm.org/svn/llvm-project/llvm/branches/release_37 llvm3.7
  svn co https://llvm.org/svn/llvm-project/cfe/branches/release_37 llvm3.7/tools/clang
  cd llvm3.7
  mkdir build
  cd build
  cmake -DLLVM_ENABLE_TERMINFO=OFF -DLLVM_TARGETS_TO_BUILD="X86;ARM;NVPTX;AArch64;Mips;PowerPC" -DLLVM_ENABLE_ASSERTIONS=ON -DCMAKE_BUILD_TYPE=Release ..
  make -j8
  export LLVM_CONFIG=$HOME/llvm3.7/build/bin/llvm-config
  export CLANG=$HOME/llvm3.7/build/bin/clang
  • (to use accelerated ISP) Install Halide (last known version to work from Mar 15 2017)
  cd ~
  git clone https://github.com/halide/Halide.git
  cd Halide
  git checkout 970f749
  mkdir cmake_build
  cd cmake_build
  cmake -DLLVM_DIR=$HOME/llvm3.7/build/share/llvm/cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_VERSION=37 -DWARNINGS_AS_ERRORS=OFF ..

Compiling the Surround 360 Rendering Software

  • After installing all of the dependencies as described above, run:
  cd <install_path>/surround360/surround360_render
  cmake -DCMAKE_BUILD_TYPE=Release
  make

(to use accelerated ISP):

  cd <install_path>/surround360/surround360_render
  cmake -DCMAKE_BUILD_TYPE=Release -DHALIDE_DIR=$HOME/Halide/cmake_build
  make
  • To test that compilation is successful, run:
  ./bin/TestRenderStereoPanorama --help

  • Follow the steps in CALIBRATION.md and RENDER.md to know how to get the best results when using the Surround360 software

  • We recommend configuring CMake to compile in Release mode because the code will execute faster. However, you can also set it up for debug mode with:

  cmake -DCMAKE_BUILD_TYPE=Debug
  • Sometimes it is useful to compile with XCode instead of CMake (e.g., to use its profiling and debugging tools). To do so:
  cd <install_path>/surround360/surround360_render
  mkdir XCodeDebug
  cd XCodeDebug
  cmake -DCMAKE_BUILD_TYPE=Debug -G Xcode ..

How the Surround 360 Rendering Software Works

Check out our blog post about how rendering for Surround 360 works here: https://code.facebook.com/posts/265413023819735

License

The Surround 360 rendering code is BSD-licensed, as it appears in LICENSE_render.md under /surround360_render. We also provide an additional patent grant.