obj2gltf/README.md

98 lines
3.7 KiB
Markdown
Raw Normal View History

2015-10-14 17:21:45 -04:00
# OBJ2GLTF
2015-10-18 23:33:54 -04:00
2015-10-20 09:44:21 -04:00
Convert OBJ assets to [glTF](https://www.khronos.org/gltf) 1.0.
2015-10-18 23:33:54 -04:00
## Getting Started
2016-07-20 14:48:49 -04:00
Install [Node.js](https://nodejs.org/en/) if you don't already have it, and then:
2015-10-18 23:33:54 -04:00
```
2016-07-20 14:48:49 -04:00
npm install --save obj2gltf
2015-10-18 23:33:54 -04:00
```
2016-07-20 14:48:49 -04:00
Using obj2gltf as a library:
```javascript
var obj2gltf = require('obj2gltf');
var options = {
2017-03-13 15:28:51 -04:00
separateTextures : true // Don't embed textures in the converted glTF
2016-07-20 14:48:49 -04:00
}
2017-04-10 17:57:56 -04:00
obj2gltf('model.obj', 'model.gltf', options)
2016-07-22 16:17:27 -04:00
.then(function() {
console.log('Converted model');
});
2016-07-20 14:48:49 -04:00
```
Using obj2gltf as a command-line tool:
2017-04-10 17:57:56 -04:00
`node bin/obj2gltf.js -i model.obj`
2016-07-20 14:48:49 -04:00
`node bin/obj2gltf.js -i model.obj -o model.gltf`
2015-10-19 17:38:55 -04:00
## Usage
2017-04-12 16:55:03 -04:00
### Command line flags:
2015-10-19 17:38:55 -04:00
|Flag|Description|Required|
|----|-----------|--------|
2017-04-10 17:57:56 -04:00
|`-h`, `--help`|Display help.|No|
|`-i`, `--input`|Path to the obj file.| :white_check_mark: Yes|
|`-o`, `--output`|Path of the converted glTF file.|No|
|`-b`, `--binary`|Save as binary glTF.|No, default `false`|
|`-s`, `--separate`|Writes out separate geometry data files, shader files, and textures instead of embedding them in the glTF file.|No, default `false`|
|`-t`, `--separateTextures`|Write out separate textures only.|No, default `false`|
|`--checkTransparency`|Do a more exhaustive check for texture transparency by looking at the alpha channel of each pixel. By default textures are considered to be opaque.|No, default `false`|
2017-04-04 16:45:21 -04:00
|`--secure`|Prevent the converter from reading image or mtl files outside of the input obj directory.|No, default `false`|
2017-04-20 14:41:39 -04:00
|`--inputUpAxis`|Up axis of the obj. Choices are 'X', 'Y', and 'Z'.|No, default `Y`|
|`--outputUpAxis`|Up axis of the converted glTF. Choices are 'X', 'Y', and 'Z'.|No, default `Y`|
|`--packOcclusion`|Pack the occlusion texture in the red channel of metallic-roughness texture.|No, default `false`|
2017-05-04 15:39:01 -04:00
|`--metallicRoughness`|The values in the mtl file are already metallic-roughness PBR values and no conversion step should be applied. Metallic is stored in the Ks and map_Ks slots and roughness is stored in the Ns and map_Ns slots.|No, default `false`|
|`--specularGlossiness`|The values in the mtl file are already specular-glossiness PBR values and no conversion step should be applied. Specular is stored in the Ks and map_Ks slots and glossiness is stored in the Ns and map_Ns slots. The glTF will be saved with the `KHR_materials_pbrSpecularGlossiness` extension.|No, default `false`|
|`--materialsCommon`|The glTF will be saved with the KHR_materials_common extension.|No, default `false`|
2015-10-19 17:38:55 -04:00
2017-01-06 11:36:44 -05:00
## Build Instructions
Run the tests:
```
npm run test
```
To run ESLint on the entire codebase, run:
2017-01-06 11:36:44 -05:00
```
npm run eslint
2017-01-06 11:36:44 -05:00
```
To run ESLint automatically when a file is saved, run the following and leave it open in a console window:
2017-01-06 11:36:44 -05:00
```
npm run eslint-watch
2017-01-06 11:36:44 -05:00
```
2017-04-12 16:55:03 -04:00
## Running Test Coverage
2017-01-06 11:36:44 -05:00
2017-06-20 13:24:03 -04:00
Coverage uses [nyc](https://github.com/istanbuljs/nyc). Run:
2017-01-06 11:36:44 -05:00
```
npm run coverage
```
For complete coverage details, open `coverage/lcov-report/index.html`.
The tests and coverage covers the Node.js module; it does not cover the command-line interface, which is tiny.
## Generating Documentation
To generate the documentation:
```
npm run jsdoc
```
The documentation will be placed in the `doc` folder.
2017-04-12 16:55:03 -04:00
## Debugging
2017-01-06 11:36:44 -05:00
* To debug the tests in Webstorm, open the Gulp tab, right click the `test` task, and click `Debug 'test'`.
* To run a single test, change the test function from `it` to `fit`.
2015-10-20 09:50:37 -04:00
## Contributions
2015-10-18 23:33:54 -04:00
Pull requests are appreciated. Please use the same [Contributor License Agreement (CLA)](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/CONTRIBUTING.md) used for [Cesium](http://cesiumjs.org/).
---
Developed by the Cesium team.
<p align="center">
2017-03-13 15:28:51 -04:00
<a href="http://cesiumjs.org/"><img src="doc/cesium.png" onerror="this.src='cesium.png'"/></a>
2015-10-18 23:33:54 -04:00
</p>