mirror of
https://git.mirrors.martin98.com/https://github.com/google/draco
synced 2025-08-12 02:48:58 +08:00
Merge pull request #2 from louquillio/port-readme.md-2-markdown
Bring README content into README.md
This commit is contained in:
Lou Quillio
GitHub
commit
92afa1a4bd
246
README.md
246
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 <draco-3d-discuss@googlegroups.com>
|
||||
|
||||
[Bunny]: https://graphics.stanford.edu/data/3Dscanrep/
|
||||
Loading…
x
Reference in New Issue
Block a user