diff --git a/README.md b/README.md index e69de29..be2c703 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,246 @@ + +Description +=========== + +Draco is used to compress and decompress 3d geometry data and point clouds. +Draco was designed and built for compression efficiency and speed. The code +supports compressing points, connectivity information, texture coordinates, +color information, normals, and any other generic attributes associated with +geometry. + +Draco is released as C++ source code that can compress and decompress 3d +geometry data and point clouds. The package also contains Javascript decoders +for the encoded data. + +Note: This is not an official Google product. + + +Building +======== + +For all the platforms first you need to generate the project files, then you +need to compile the examples. + + +CMake Basics +------------ + +To generate project/make files for the default toolchain on your system simply +run `cmake` in the root of the Draco repo: + +~~~~~ +$ cmake . +~~~~~ + +On Windows the above command will produce Visual Studio project files for the +newest Visual Studio detected on the system. On Mac OS X and Linux systems, the +above command will produce a makefile. + +To control what types of projects are generated the `-G` parameter is added to +the `cmake` command line. This argument must be followed by the name of a +generator. Running `cmake` with the `--help` argument will list the available +generators for your system. + +On Mac OS X you would run the following command to generate Xcode projects: + +~~~~~ +$ cmake . -G Xcode +~~~~~ + +On a Windows box you would run the following command to generate Visual Studio +2015 projects: + +~~~~~ +$ cmake . -G "Visual Studio 14 2015" +~~~~~ + +To generate 64-bit Windows Visual Studio 2015 projects: + +~~~~~ +$ cmake . "Visual Studio 14 2015 Win64" +~~~~~ + + +CMake Makefiles: Debugging and Optimization +------------------------------------------- + +Unlike Visual Studio and Xcode projects, the build configuration for make builds +is controlled when you run `cmake`. The following examples demonstrate various +build configurations. + +Omitting the build type produces makefiles that use build flags containing +neither optimization nor debug flags: + +~~~~~ +$ cmake . +~~~~~ + +A makefile using release (optimized) flags is produced like this: + +~~~~~ +$ cmake . -DCMAKE_BUILD_TYPE=release +~~~~~ + +A release build with debug info can be produced as well: + +~~~~~ +$ cmake . -DCMAKE_BUILD_TYPE=relwithdebinfo +~~~~~ + +And your standard debug build will be produced using: + +~~~~~ +$ cmake . -DCMAKE_BUILD_TYPE=debug +~~~~~ + + +Android Studio Project Integration +---------------------------------- + +To include Draco in an existing or new Android Studio project it simply needs +to be referenced from the `cmake` file of an existing native project that has a +minimum SDK version of 18 or higher. To add Draco to your project: + + 1. Add the following somewhere within the `CMakeLists.txt` for your project + before the `add_library()` for your project's native-lib: + + ~~~~~ + # Note "/path/to/draco" must be changed to the path where you have cloned + # the Draco sources. + + add_subdirectory(/path/to/draco + ${CMAKE_BINARY_DIR}/draco_build) + include_directories("${CMAKE_BINARY_DIR}" /path/to/draco) + ~~~~~ + + 2. Add the library target "draco" to the `target_link_libraries()` call for your + project's native-lib. The `target_link_libraries()` call for an empty + activity native project looks like this after the addition of Draco: + + ~~~~~ + target_link_libraries( # Specifies the target library. + native-lib + + # Tells cmake this build depends on libdraco. + draco + + # Links the target library to the log library + # included in the NDK. + ${log-lib} ) + ~~~~~ + +Examples +======== + +Commandline Applications +------------------------ + +The default target create from the build files will be the `draco_encoder` and +`draco_decoder` command line applications. For both applications if you run them +without any arguments or `-h`, the applications will output the usage and +options. + + +Encoding Tool +------------- + +`draco_encoder` will read OBJ or PLY files as input and output Draco encoded +files. We have included Stanford's [Bunny] mesh for testing. The basic command +line looks like this: + +~~~~~ +$ ./draco_encoder -i testdata/bun_zipper.ply -o out.drc +~~~~~ + +A value of `0` for the quantization parameters will not perform any quantization +on the specified attribute. Any value other than `0` will quantize the input +values for the specified attribute to that number of bits. + +E.g. `./draco_encoder -i testdata/bun_zipper.ply -o out.drc -qp 14` will +quantize the positions to 14 bits (default for the position coordinates). + +In general the more you quantize your attributes the better compression rate +you will get. It is up to your project on how much deviation it will tolerate. +In general most projects can set quantizations values of about 14 without any +noticeable difference in quality. + +The compression level parameter turns on/off different compression features. +In general the highest setting, 10, will have the worst compression ratio but +best decompression speed. And 0 will have the best compression ratio, but worst +decompression speed. + + +Encoding Point Clouds +--------------------- + +You can encode point cloud data with `draco_encoder` by specifying the +`point_cloud parameter`. If you specify the `point_cloud parameter` with a mesh +input file, `draco_encoder` will ignore the connectivity data and encode the +positions from the mesh file. E.g.: + +~~~~~ +$ ./draco_encoder -point_cloud -i testdata/bun_zipper.ply -o out.drc +~~~~~ + +This command line will encode the mesh input as a point cloud, even though the +input might not produce compression that is representative of other point +clouds. Specifically, one can expect much better compression rates for larger +and denser point clouds. + + +Decoding Tool +------------- + +`draco_decoder` will read Draco files as input and output OBJ or PLY files. The +basic command line looks like this: + +~~~~~ +$ ./draco_decoder -i in.drc -o out.obj +~~~~~ + +Javascript Decoder +------------------ + +The Javascript decoder is located in `javascript/draco_decoder.js`. The +Javascript decoder can currently only decode mesh geometry. In order to use the +decoder you must create `DecoderBuffer` and `WebIDLWrapper` objects. Set the +encoded data in the `DecoderBuffer`. Then call `DecodeMeshFromBuffer()`, which +will return a Mesh object. E.g. + +~~~~~ +var buffer = new Module.DecoderBuffer(); +buffer.Init(encFileData, encFileData.length); + +var wrapper = new WebIDLWrapper(); +var outputMesh = wrapper.DecodeMeshFromBuffer(buffer); + +destroy(outputMesh); +destroy(wrapper); +destroy(buffer); +~~~~~ + +Please see `javascript/emscripten/draco_web.idl` for the full API. + + +Javascript Decoder Performance +------------------------------ + +The Javascript decoder is built with dynamic memory. This will let the decoder +work with all of the compressed data. But this option is not the fastest. +Pre-allocating the memory sees about a 2x decoder speed improvement. If you +know all of your project's memory requirements you can turn on static memory +by changing `Makefile.emcc` and running `make -f Makefile.emcc`. + + +three.js renderer example +------------------------- + +Please see the `javascript/example/README` file for more information. + + +Support +======= + +For questions/comments please email + +[Bunny]: https://graphics.stanford.edu/data/3Dscanrep/