README.md 6.7 KB
Newer Older
P
Patrick Cozzi 已提交
1 2
# glTF Pipeline

S
Sean Lilley 已提交
3 4
[![License](https://img.shields.io/:license-apache-blue.svg)](https://github.com/CesiumGS/gltf-pipeline/blob/master/LICENSE.md)
[![Build Status](https://travis-ci.org/CesiumGS/gltf-pipeline.svg?branch=master)](https://travis-ci.org/CesiumGS/gltf-pipeline)
P
Patrick Cozzi 已提交
5

P
Patrick Cozzi 已提交
6
<p align="center">
R
Robert Taglang 已提交
7
<a href="https://www.khronos.org/gltf"><img src="doc/gltf.png" onerror="this.src='gltf.png'"/></a>
P
Patrick Cozzi 已提交
8 9
</p>

S
Sean Lilley 已提交
10
Content pipeline tools for optimizing [glTF](https://www.khronos.org/gltf) assets by [Richard Lee](http://leerichard.net/) and the [Cesium team](https://cesium.com/).
P
Patrick Cozzi 已提交
11

S
Sean Lilley 已提交
12 13 14
Supports common operations including:
* Converting glTF to glb (and reverse)
* Saving buffers/textures as embedded or separate files
S
Updates  
Sean Lilley 已提交
15
* Converting glTF 1.0 models to glTF 2.0 (using the [KHR_techniques_webgl](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_techniques_webgl) and [KHR_blend](https://github.com/KhronosGroup/glTF/pull/1302) extensions)
S
Sean Lilley 已提交
16
* Applying [Draco](https://github.com/google/draco) mesh compression
P
Patrick Cozzi 已提交
17

S
Sean Lilley 已提交
18
`gltf-pipeline` can be used as a command-line tool or Node.js module.
P
Patrick Cozzi 已提交
19

S
Sean Lilley 已提交
20
## Getting Started
P
Patrick Cozzi 已提交
21

S
Sean Lilley 已提交
22
Install [Node.js](https://nodejs.org/en/) if you don't already have it, and then:
P
Patrick Cozzi 已提交
23
```
S
Sean Lilley 已提交
24
npm install -g gltf-pipeline
P
Patrick Cozzi 已提交
25 26
```

S
Sean Lilley 已提交
27 28 29
### Using gltf-pipeline as a command-line tool:

#### Converting a glTF to glb
S
Sean Lilley 已提交
30
`gltf-pipeline -i model.gltf -o model.glb`
S
Sean Lilley 已提交
31

S
Sean Lilley 已提交
32
`gltf-pipeline -i model.gltf -b`
S
Sean Lilley 已提交
33 34

#### Converting a glb to glTF
S
Sean Lilley 已提交
35
`gltf-pipeline -i model.glb -o model.gltf`
S
Sean Lilley 已提交
36

S
Sean Lilley 已提交
37
`gltf-pipeline -i model.glb -j`
S
Sean Lilley 已提交
38

39
#### Converting a glTF to Draco glTF
S
Sean Lilley 已提交
40
`gltf-pipeline -i model.gltf -o modelDraco.gltf -d`
41

S
Sean Lilley 已提交
42
### Saving separate textures
S
Sean Lilley 已提交
43
`gltf-pipeline -i model.gltf -t`
S
Sean Lilley 已提交
44 45 46 47 48 49

### Using gltf-pipeline as a library:

#### Converting a glTF to glb:

```javascript
S
Sean Lilley 已提交
50 51 52 53
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const gltfToGlb = gltfPipeline.gltfToGlb;
const gltf = fsExtra.readJsonSync('model.gltf');
S
Sean Lilley 已提交
54 55 56
gltfToGlb(gltf)
    .then(function(results) {
        fsExtra.writeFileSync('model.glb', results.glb);
S
Sean Lilley 已提交
57
    });
P
Patrick Cozzi 已提交
58 59
```

S
Sean Lilley 已提交
60 61 62
#### Converting a glb to glTF

```javascript
S
Sean Lilley 已提交
63 64 65 66
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const glbToGltf = gltfPipeline.glbToGltf;
const glb = fsExtra.readFileSync('model.glb');
S
Sean Lilley 已提交
67 68 69
glbToGltf(glb)
    .then(function(results) {
        fsExtra.writeJsonSync('model.gltf', results.gltf);
S
Sean Lilley 已提交
70
    });
71
```
S
Sean Lilley 已提交
72

S
Sean Lilley 已提交
73 74 75
#### Converting a glTF to Draco glTF

```javascript
S
Sean Lilley 已提交
76 77 78 79 80
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const processGltf = gltfPipeline.processGltf;
const gltf = fsExtra.readJsonSync('model.gltf');
const options = {
S
Sean Lilley 已提交
81 82 83
    dracoOptions: {
        compressionLevel: 10
    }
S
Sean Lilley 已提交
84
};
S
Sean Lilley 已提交
85 86
processGltf(gltf, options)
    .then(function(results) {
S
Sean Lilley 已提交
87
        fsExtra.writeJsonSync('model-draco.gltf', results.gltf);
S
Sean Lilley 已提交
88
    });
S
Sean Lilley 已提交
89 90
```

S
Sean Lilley 已提交
91 92 93
#### Saving separate textures

```javascript
S
Sean Lilley 已提交
94 95 96 97 98
const gltfPipeline = require('gltf-pipeline');
const fsExtra = require('fs-extra');
const processGltf = gltfPipeline.processGltf;
const gltf = fsExtra.readJsonSync('model.gltf');
const options = {
S
Sean Lilley 已提交
99
    separateTextures: true
S
Sean Lilley 已提交
100 101 102
};
processGltf(gltf, options)
    .then(function(results) {
S
Sean Lilley 已提交
103
        fsExtra.writeJsonSync('model-separate.gltf', results.gltf);
104
        // Save separate resources
S
Sean Lilley 已提交
105 106
        const separateResources = results.separateResources;
        for (const relativePath in separateResources) {
107
            if (separateResources.hasOwnProperty(relativePath)) {
S
Sean Lilley 已提交
108
                const resource = separateResources[relativePath];
S
Sean Lilley 已提交
109
                fsExtra.writeFileSync(relativePath, resource);
S
Sean Lilley 已提交
110 111
            }
        }
S
Sean Lilley 已提交
112
    });
113 114
```

P
Tweak  
Patrick Cozzi 已提交
115
### Command-Line Flags
116 117 118

|Flag|Description|Required|
|----|-----------|--------|
R
Robert Taglang 已提交
119
|`--help`, `-h`|Display help|No|
S
Sean Lilley 已提交
120
|`--input`, `-i`|Path to the glTF or glb file.|:white_check_mark: Yes|
121
|`--output`, `-o`|Output path of the glTF or glb file. Separate resources will be saved to the same directory.|No|
S
Sean Lilley 已提交
122 123 124 125
|`--binary`, `-b`|Convert the input glTF to glb.|No, default `false`|
|`--json`, `-j`|Convert the input glb to glTF.|No, default `false`|
|`--separate`, `-s`|Write separate buffers, shaders, and textures instead of embedding them in the glTF.|No, default `false`|
|`--separateTextures`, `-t`|Write out separate textures only.|No, default `false`|
S
Updates  
Sean Lilley 已提交
126
|`--stats`|Print statistics to console for output glTF file.|No, default `false`|
127
|`--keepUnusedElements`|Keep unused materials, nodes and meshes.|No, default `false`|
128
|`--draco.compressMeshes`, `-d`|Compress the meshes using Draco. Adds the KHR_draco_mesh_compression extension.|No, default `false`|
129
|`--draco.compressionLevel`|Draco compression level [0-10], most is 10, least is 0. A value of 0 will apply sequential encoding and preserve face order.|No, default `7`|
S
Sean Lilley 已提交
130 131 132 133
|`--draco.quantizePositionBits`|Quantization bits for position attribute when using Draco compression.|No, default `14`|
|`--draco.quantizeNormalBits`|Quantization bits for normal attribute when using Draco compression.|No, default `10`|
|`--draco.quantizeTexcoordBits`|Quantization bits for texture coordinate attribute when using Draco compression.|No, default `12`|
|`--draco.quantizeColorBits`|Quantization bits for color attribute when using Draco compression.|No, default `8`|
S
Sean Lilley 已提交
134 135
|`--draco.quantizeGenericBits`|Quantization bits for skinning attribute (joint indices and joint weights) and custom attributes when using Draco compression.|No, default `12`|
|`--draco.unifiedQuantization`|Quantize positions of all primitives using the same quantization grid. If not set, quantization is applied separately.|No, default `false`|
136

P
Patrick Cozzi 已提交
137 138
## Build Instructions

P
Patrick Cozzi 已提交
139 140
Run the tests:
```
S
Sean Lilley 已提交
141
npm run test
P
Patrick Cozzi 已提交
142
```
143
To run ESLint on the entire codebase, run:
P
Patrick Cozzi 已提交
144
```
145
npm run eslint
P
Patrick Cozzi 已提交
146
```
147
To run ESLint automatically when a file is saved, run the following and leave it open in a console window:
P
Patrick Cozzi 已提交
148
```
149
npm run eslint-watch
P
Patrick Cozzi 已提交
150
```
P
Patrick Cozzi 已提交
151

S
Sean Lilley 已提交
152
### Building for CesiumJS integration
153

S
Sean Lilley 已提交
154
Some functionality of gltf-pipeline is used by CesiumJS as a third party library. The necessary files can be generated using:
155 156 157 158 159

```
npm run build-cesium
```

S
Sean Lilley 已提交
160
This will output a portion of the gltf-pipeline code into the `dist/cesium` folder for use with CesiumJS in the browser.
161

R
Robert Taglang 已提交
162
### Running Test Coverage
P
Patrick Cozzi 已提交
163

O
Ottavio Hartman 已提交
164
Coverage uses [nyc](https://github.com/istanbuljs/nyc).  Run:
P
Patrick Cozzi 已提交
165 166 167 168 169
```
npm run coverage
```
For complete coverage details, open `coverage/lcov-report/index.html`.

P
Patrick Cozzi 已提交
170
The tests and coverage covers the Node.js module; it does not cover the command-line interface, which is tiny.
J
JoshuaStorm 已提交
171

R
Robert Taglang 已提交
172 173 174 175 176 177 178 179 180
## Generating Documentation

To generate the documentation:
```
npm run jsdoc
```

The documentation will be placed in the `doc` folder.

181 182
## Contributions

S
Sean Lilley 已提交
183
Pull requests are appreciated!  Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/master/CONTRIBUTING.md) and [Coding Guide](https://github.com/CesiumGS/cesium/blob/master/Documentation/Contributors/CodingGuide/README.md) used for [Cesium](https://github.com/CesiumGS/cesium).