GithubHelp home page GithubHelp logo

facebook / facebook360_dep Goto Github PK

View Code? Open in Web Editor NEW
222.0 27.0 42.0 45.16 MB

Facebook360 Depth Estimation Pipeline -

License: Other

CMake 0.11% Dockerfile 0.05% Python 3.77% Shell 0.03% C++ 5.80% C 0.13% JavaScript 1.24% CSS 0.49% HTML 88.37%

facebook360_dep's Introduction

DEP Logo

Facebook360 Depth Estimation Pipeline (facebook360_dep) is a computational imaging software pipeline supporting on-line marker-less calibration, high-quality reconstruction, and real-time streaming and rendering of 6DoF content.

This work is based on the 2019 SIGGRAPH Asia publication "An Integrated 6DoF Video Camera and System Design" (paper, supplemental material).

Build Status Build Status


📋 Requirements

facebook360_dep can be run on Windows, macOS, or Linux as your development operating system with the use of Docker. Building source natively on operating systems has been tested on Mac but is not the recommended way to use the software pipeline. Certain capabilities are restricted on the operating systems, due in part to restrictions to the GPU from Docker.

📖 Documentation

Here you can find short guides for the most common scenarios: facebook360_dep.

👏 How to Contribute

The main purpose of this repository is to continue evolving facebook360_dep core. We want to make contributing to this project as easy and transparent as possible, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving facebook360_dep.

Code of Conduct

Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Contributing Guide

Read our Contributing Guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to facebook360_dep.

Good First Issues

We have a list of good first issues that contain bugs which have a relatively limited scope. This is a great place to get started, gain experience, and get familiar with our contribution process.


If you need help with your facebook360_dep app, the right place to go depends on the type of help that you need.

📄 License

facebook360_dep is BSD licensed, as found in the LICENSE file.

facebook360_dep's People


aparrapo avatar h-friederich avatar bkcabral avatar tschrager avatar amyreese avatar weichunyuan avatar facebook-github-bot avatar


George Kontridze avatar davci avatar Yuanchen Guo avatar Yanpei Cao avatar Ruby avatar  avatar Giseop Kim avatar Mohammad Reza Taesiri avatar Nrupatunga avatar Kai Zhang avatar David Joseph, Founder @ iA Labs avatar  avatar  avatar Alejandro Jesus del Campillo Jaime avatar Joey mengistu avatar Chen Yao avatar Seung-Hwan Baek avatar BenMack avatar  avatar  avatar JRusinova avatar  avatar Michael  Martin avatar  avatar  avatar  avatar JIAGANG CHEN avatar cck avatar Sai Marpaka avatar Keany Vy KHUN avatar Paulo Manso avatar Matthew avatar XiaomingYu avatar gongyiqun avatar Jisung Yoo avatar  avatar  avatar Kotchaphan Muangsan avatar pushpendra pratap avatar Pyjcsx avatar Alex Yu avatar NANKI Haruo avatar lilkypimp1 avatar  avatar Gleb Sterkin avatar JD avatar Shuyuan Mao avatar liu qiang avatar Mohammad Ali Zamani avatar  avatar Tian Pi avatar Koya IWAMURA avatar Thomas Bruhn avatar Jiwon Kim avatar Radek Dabrowski avatar takafumi-ko avatar  avatar Changil Kim avatar  avatar Kazuyuki Arimatsu avatar Kazlecall avatar  avatar  avatar  avatar su ning avatar Ning-Hsu Albert Wang avatar Mpk avatar Xuejian Rong avatar XianyanLin avatar  avatar  avatar Gábor Mihálcz avatar  avatar 刘国友 avatar Pablo Martin avatar Qiang Lu avatar Dahyun Kang avatar Momo the Monster avatar linuer avatar Vatary avatar Dedual Enterprises avatar Ian Moore-Kilgannon avatar  avatar Hengkai Guo avatar  avatar Yee avatar 不安分的猿人 avatar  avatar phillee avatar  avatar Brahim Hadriche avatar Jerome Maurey-Delaunay avatar  avatar Franklin Lyons avatar Liam Walsh avatar Chris Novello avatar Patrick Hogenboom avatar HarlanC avatar Ajinkya Puar avatar arpu avatar


Killian Murphy avatar Fabien Castan avatar  avatar Nick Porcino avatar James Cloos avatar Mike avatar colleen avatar Vatary avatar Qi Gao avatar Divya Rathore avatar 刘国友 avatar Chetan Gupta avatar Albert Parra Pozo avatar Terence C avatar  avatar Shizhe avatar  avatar  avatar Giseop Kim avatar Hannes Friederich avatar JD avatar Chen Yao avatar Satish Goda avatar Maxime Vandegar avatar  avatar  avatar  avatar

facebook360_dep's Issues

The problem of too few panoramic camera matches

Steps To Reproduce

1.1.After I modified the rig.json file based on the Insta360 Pro camera parameters, I found that the system prompts too few matches and can't generate a rig_calibration.json file.

  1. The generated depth map is not accurate enough.

Describe what you expected to happen:

  1. Could you please help explain why are there too few matches point, and how can I get more matching point?
  2. Could you help to see how the depth map can be seen more clearly?
    new matching data

Snack, code example, or link to a repository:

Docs: How is RGB-D data packed in result?

I couldn't find any examples or relevant code about how the resulting RGB-D videos and images are packed.

In the past I've seen that facebook uses the lower half of the video to pack 24 bits depth in the RGB channels (or YUV for that matter).

Docs: Redirection Issue in a sub-component of a footer section


  1. The home page of facebook360_dep has a navbar which has nav component Github which on clicking redirects to
  2. But if I come in footer and then click Github , it redirects to

Describe what you expected to happen:

I expect when I click on Github in the footer section , it should also redirect to like it does in the navbar

Snack, code example, or link to a repository:

Link to website:



If this issue seems valid , I would like to work on this , so please assign me

Feature: Semantic Segmentation in Masking

Foreground masks act as a rough proxy to objects in the scene. Significant work on semantic segmentation (re: has been done, although they have not been thoroughly integrated with our pipeline to improve results.

The current behavior and new feature

Render (Foreground masks): A weighted sum of a traditional foreground mask and semantic segmentation can be used to obtain a more accurate set of masks for the scene. This can even be extended to have a multi-planar image if the semantic segmentation is accurate enough.

Expected use cases

Significant research effort.

Application fails to launch: qt.qpa.xcb: could not connect to display :0

Upon attempting to launch by running "python3 -u scripts/render/ --flagfile res/flags/run.flags" the following error occurs:

qt.qpa.xcb: could not connect to display :0
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, webgl, xcb.

Fatal Python error: Aborted

Current thread 0x00007f86a2f57740 (most recent call first):
File "", line 282 in main
File "/usr/local/lib/python3.7/dist-packages/absl/", line 251 in _run_main
File "/usr/local/lib/python3.7/dist-packages/absl/", line 300 in run
File "", line 315 in
Fatal Python error: Segmentation fault

Current thread 0x00007f86a2f57740 (most recent call first):
File "", line 282 in main
File "/usr/local/lib/python3.7/dist-packages/absl/", line 251 in _run_main
File "/usr/local/lib/python3.7/dist-packages/absl/", line 300 in run
File "", line 315 in

I have followed the Docker installation instructions. Incidentally I have previously used the application and I think I encountered the same error and managed to resolve however that was many months ago and don't recall how. I think the issue is related to Docker / X11 forwarding. This is occurring using Ubuntu 18.04.5 LTS with an Nvidia GPU.

Feature: Stripe among multiple machines in EC2

The last stage of the 6DoF rendering pipeline is to stripe the binaries into a single binary file. However, it is currently implemented to only be done on a single computer. This means that, regardless of the size of your cluster, the final stage will take the same amount of time, since it is all performed on a single machine. The striping, however, can be parallelized in a mergesort-like fashion.

The current behavior and new feature

The striping is performed by ConvertToBinary (source/mesh_stream/ConvertToBinary.cpp), which produces a single binary file along with a digest JSON that describes the contents of the binary. This is effectively the same as how a .TAR file is created. To stripe across multiple machines, you will need to figure out how to properly merge these binaries together, which should be nothing more than concatenating them, and merge the JSON digest, which will involve updating the offsets of where different pieces are located in this final binary.

Expected use cases

End users will benefit primarily from a great reduction (likely upwards of 5-10%) in rendering time.

Feature: Quick Stitch Option

On set, having quick turnaround times on renders is crucial: it helps uncover setup issues (i.e. flipped cameras). A "quick stitch option" on the UI would skip calibration and background entirely, and directly produce depth estimates and a color equirect at low res.

The current behavior and new feature

Render: To see whether the camera arrangement is proper, we must go through the entire pipeline to produce an equirect. Having a quick stitch allows a quick glance first pass sanity check, which could save hours down the road.

Expected use cases

Will be useful for end users (i.e. producers on set).

Docs: Calibration files of common 360 cameras

Would it be possible to start documenting the calibration files of common 360 cameras? I'm a little head-scratchy when it comes to determining the orientation and origin of the cameras on my Insta360 Pro 2.

UPDATE: The NVIDIA VRWorks SDK has a tool that determines the calibration based on a set of photos. I ran a set from the Insta360 Pro 2 through them to see if I could match them to what the FDEP wants but they don't match up. If you can determine the proper values from them, it might be a nice way to get this data without having the camera specs? The output is attached.

Extraneous "Connected/Authenticated" output on AWS Render

Running any render job on AWS produces extraneous connection/authenticated messages (see the ones logged by


These are caused by running commands over SSH, which is done in the scripts/aws/ run_ssh_command function. We wish to silence that output.

Steps To Reproduce

  1. Ran
python3 scripts/render/ --flagfile res/flags/run.flags

Where res/flags/run.flags is:

  1. Clicked on "Run" on the depth estimation tab with default values except first=000100 and last=000105.

Describe what you expected to happen:

No extraneous output being produced

Multiproccessing in hangs

When I try to start the UI with, the script hangs when it tries to generate the color_levels. Through some investigation, I found that it was hanging in resize_frames(). I'm not sure exactly why the multiprocessing doesn't work, but changing the function to directly resize the images fixed the issue for me. Here's how I altered resize frames:

def resize_frames(src_dir, dst_dir, rig, first, last, threshold=None):
    """Resizes a frame to the appropriate pyramid level sizes. Files are saved in
    level_0/[camera], ..., level_9/[camera] in the destination directory.

        src_dir (str): Path to the source directory.
        dst_dir (str): Path to the destination directory.
        rig (dict[str, _]): Rig descriptor object.
        first (str): Name of the first frame to render.
        last (str): Name of the last frame to render.
        threshold (int): Threshold to be used for binary thresholding. No thresholding
            is performed if None is passed in.
    for frame in range(int(first), int(last) + 1):
        for camera in rig["cameras"]:
            verify_frame(src_dir, camera["id"], get_frame_name(frame))

I'm on Windows 10, using Docker with the WSL 2 configuration. I'm sure this function works on other setups, but in case anyone else sees this issue, this might help.

Can't load images via symbolic links?

On Windows, image file names that are symlinks give 'Missing file' errors. It would be good to test if this is also the case on *nix. While there is a good chance that part of the fault is the Boost filesystem's known difficulties with handling Windows' nasty symlink format, my reading of the project code suggests that symlinks might not even work on Linux. For example these lines in imageUtil.cpp::verifyImagePaths() would likely reject a symlink:
const bool exists = filesystem::is_regular_file(p); CHECK(exists) << "Missing file: " << p;
It is actually possible to read from Windows symlinks with Boost, but this does require some platform-specific code. If the Linux builds already use symlinks OK, I would suggest giving this issue a low priority; but if not, a high one.

Steps To Reproduce

  1. copy a calibration setup where MatchCorners runs correctly
  2. replace image files with symlinks to files stored elsewhere
  3. run MatchCorners

expect "Missing file" failure.

Feature: Machine Learning Based Depth Estimation

Machine learning has replaced most "traditional" computer vision algorithms, especially in domains like annotation and labelling. Attempts to apply ML to depth estimation certainly exist, but only perform consistently well in limited capture environments (i.e. those without moving bodies or humans). Applying them to subsets of our pipeline may shed more light on how they can be used fully though.

The current behavior and new feature

Render pipeline: The algorithm is fully based on "traditional" computer vision. Instead, ML approaches may attempt to improve either foreground mask generation or the depths directly.

Expected use cases

Significant research needed.

Feature: WebGL Viewer Support

The WebGL standard has been adopted by all modern web browsers and offers an API for rendering using the GPU on a browser. The browser is the end-all-be-all for many users, so making 6DoF consumable through the browser is a necessary step towards getting more people to experience the content.

The current behavior and new feature

GLViewer is the viewer for 6DoF content if not using a Rift headset. It is an extensive array of OpenGL and meshing code, so converting them to a similar WebGL viewer will likely be a significant undertaking. There is also the possibility of using wasm and compiling our C++ code to be ingested by a wasm-supported browser, but this seems more experimental and will likely have performance hitches.

Relevant Files:

  • source/viewer/GlViewer.cpp and linked headers, i.e.:
    • source/gpu/GlfwUtil.h
    • source/render/RigScene.h
    • source/render/VideoFile.h

Expected use cases

This would have great impact in making 6DoF content more easily consumable and, therefore, more likely for people to engage with the content. However, it will likely be a significant undertaking, for which we would likely recommend working in a small group (of say 2-3 people) towards completion.

Feature: Compute first N coarsest levels in a single worker during AWS renders

The current behavior and new feature

At any level of the pyramid a worker needs to download the color level for a frame from S3, perform depth estimation, and then pack and send the results back.

At the coarsest levels we end up spending more time downloading and uploading data than actually processing the frames. We can speed up the process by letting workers do the coarsest N levels (e.g. levels 9 to 4) at once.

Note that this means not being able to run the temporal filter after each of these levels, since that stage is also distributed, but it may be a good trade-off.

Expected use cases

Faster renders at the expense of worse temporal smoothing, but may be not noticeable.

Docs: A redirection issue in the footer of facebook360_dep 's documentation website


  1. The home page of facebook360_dep has a navbar which has nav component Tutorial which on clicking redirects to
  2. But if I come in footer and then click Tutorial , it redirects to

Describe what you expected to happen:

I expect when I click on Tutorial in the footer section , it should also redirect to like it does in the navbar

Snack, code example, or link to a repository:

Link to website:



If this issue seems valid , I would like to work on this , so please assign me

Docs: license of the example data

Hi, first of all thanks for providing this software.

The software license (BSD) is clear to me, but I it is not clearly stated if the example data has the same license. Could this be clarified?

There is an active standardization project within MPEG called MPEG Immersive Video (MIV) [ ], and I was wondering if the example data that you have provided could be used at least for "academic and standardization purposes".

Feature: LiDAR Integration

LiDAR ( is used heavily to obtain dense point cloud representations of scenes. By performing a LiDAR scan of a scene before starting captures, we can potentially greatly improve accuracy background disparity estimation and, thus, in creating accurate foreground masks.

The current behavior and new feature

Render pipeline: this would most likely integrate into the background depth estimation and foreground mask generation steps.

Expected use cases

Research effort, potentially being integrated in future shoots if results turn out to be significantly better than they are currently.

A redirection issue in the footer of facebook360_dep 's website

Steps To Reproduce

  1. The home page of facebook360_dep has a navbar which has nav component Tutorial which on clicking redirects to
  2. But if I come in footer and then click Tutorial , it redirects to

Describe what you expected to happen:

I expect when I click on Tutorial in the footer section , it should also redirect to like it does in the navbar

Snack, code example, or link to a repository:

Link to website:



If this issue seems valid , I would like to work on this , so please assign me

[Dockerfile] Eigen repository moved

Eigen moved their repository from Bitbucket to Gitlab recently (the announcement).
So 69-74 lines of the Dockerfile need to be updated like this:

RUN curl -LO && \
    tar -zxf eigen-3.3.4.tar.gz && \
    cd eigen-3.3.4 && \
    mkdir build && cd build && \
    cmake .. && make install -j$(nproc) && \
    cd ../../ && rm -fr eigen-3.3.4

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.