Home

Awesome

SUNCG Data Documentation

We provide a simple C++ based toolbox for the SUNCG dataset.
Please see our webpage and paper for more details about the data and downloads.

Contents

  1. [Data Organization](#Data Organization)
  2. [Data Format](#Data Format)
  3. [C++ Toolbox](#C++ Toolbox)
  4. [Basic Functionalities](#Basic Functionalities)
  5. Resources

Data Organization

The downloaded and unzipped SUNCG files should be organized as follows:

data_root
    |-- house
        |-- <sceneid>
            |-- house.json
    |-- room
        |-- <sceneid>
            |- fr_0rm_0c.mtl    
            |- fr_0rm_0c.obj
            ...
    |-- object
        |-- <objectid>
            |--objectid.obj
    |-- texture

Data Format

Each 3D scene is saved as "house.json", and structured as follows:

house.json

C++ Toolbox

The code is organized as follows:

gaps
    |-- pkgs - source and include files for all packages (software libraries)
    |-- apps - source files for several applications and example programs
    |-- makefiles - unix-style make file definitions
    |-- vc - visual studio solution files
    |-- lib - archive library (.lib) files (created during compilation)
    |-- bin - executable files (created during compilation)
metadata
    |-- ModelCategoryMapping.csv
    |-- suncgModelLights.json

Compilation

Compile with OpenGL, it will use GPU for rendering:

cd gaps
make clean 
make

Compile with OSMesa, it will use CPU for off-screen rendering:

cd gaps
make clean 
make mesa

Basic Functionalities

Viewing the scene (requires compiling with GPU)

cd data_root/house/<sceneid>/
gaps/bin/x86_64/sceneview house.json -v

Camera Controls

Other function keys

Convert to OBJ+MTL

cd data_root/projects/<sceneid>/
gaps/bin/x86_64/scn2iscn house.json house.obj

It will write out "house.obj" and "house.mtl" in the current folder.

Generating Cameras

cd data_root/projects/<sceneid>/
gaps/bin/x86_64/scn2cam house.json outputcamerasfile  -categories ModelCategoryMapping.csv  -v

Input options -width: Output image width -height: Output image height -xfov: Camera FOV -eye_height: Camera height

Use the following command to check the generated camera file. Press key "c" to show the camera. Press key "v" to go though each view point.

gaps/bin/x86_64/sceneview house.json -cameras outputcamerasfile

Render Images and Ground Truth

cd data_root/projects/<sceneid>/
gaps/bin/x86_64/scn2img house.json inputcamerasfile outputimagedirectory -categories ModelCategoryMapping.csv  -v

The program will generate the following files, you can use the corresponding flags to choose which files to generate:

Resources

Room category: living room, kitchen, bedroom, child room, dining room, bathroom, toilet, hall, hallway, office, guest room, wardrobe, room, lobby, storage, boiler room, balcony, loggia, terrace, entryway, passenger elevator, freight elevator, aeration, garage and gym.

Object category mapping between SUNCG to NYU depth V2 40 object class can be found in $data_root/metadata/ModelClassMapping.csv.

Bibtex

If you find SUNCG useful in your research, please consider citing:

@article{song2016ssc, 
    title= {Semantic Scene Completion from a Single Depth Image}, 
    author= {Song, Shuran and Yu, Fisher and Zeng, Andy and Chang, Angel X and Savva, Manolis and Funkhouser, Thomas}, 
    journal={arXiv preprint arXiv:1611.08974}, 
    year={2016} 
}

GAPS README

This toolbox is adapted from GAPS written by Thomas Funkhouser. Here is the orignal GAPS README:

GAPS Users -

This directory contains all code for the GAPS software library. There are several subdirectories:

pkgs - source and include files for all packages (software libraries).
apps - source files for several application and example programs. 
makefiles - unix-style make file definitions
vc - visual studio solution files
lib - archive library (.lib) files (created during compilation).
bin - executable files (created during compilation).

If you are using linux or cygwin and have gcc and OpenGL development libraries installed, or if you are using MAC OS X with the xcode development environment, you should be able to compile all the code by typing "make clean; make" in this directory. If you are using Windows Visual Studio 10 or later, then you should be able to open the solution file vc.sln in the vc subdirectory and then "Rebuild Solution." For other development platforms, you should edit the shared compilation settings in the makefiles/Makefiles.std to meet your needs.

To write a program that uses the GAPS pkgs, then you should include "-I XXX/gaps/pkgs" in your compile flags (CFLAGS) and "-L XXX/gaps/lib" in your link flags (LDFLAGS), where XXX is the directory where you installed the gaps software.

The software is distributed under the MIT license (see LICENSE.txt) and thus can be used for any purpose without warranty, any liability, or any suport of any kind.