Convert up axis

README.md

@@ -46,6 +46,8 @@ Using obj2gltf as a command-line tool:
 |`--bypassPipeline`|Bypass the gltf-pipeline for debugging purposes. This option overrides many of the options above and will save the glTF with the KHR_materials_common extension.|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`|
 |`--secure`|Prevent the converter from reading image or mtl files outside of the input obj directory.|No, default `false`|
+|`--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`|
 
 ## Build Instructions
 

bin/obj2gltf.js

@@ -95,6 +95,18 @@ var argv = yargs
             describe: 'Prevent the converter from reading image or mtl files outside of the input obj directory.',
             type: 'boolean',
             default: defaults.secure
+        },
+        inputUpAxis : {
+            describe: 'Up axis of the obj.',
+            choices: ['X', 'Y', 'Z'],
+            type: 'string',
+            default: 'Y'
+        },
+        outputUpAxis : {
+            describe: 'Up axis of the converted glTF.',
+            choices: ['X', 'Y', 'Z'],
+            type: 'string',
+            default: 'Y'
         }
     }).parse(args);
 
@@ -119,7 +131,9 @@ var options = {
     kmc : argv.kmc,
     bypassPipeline : argv.bypassPipeline,
     checkTransparency : argv.checkTransparency,
-    secure : argv.secure
+    secure : argv.secure,
+    inputUpAxis : argv.inputUpAxis,
+    outputUpAxis : argv.outputUpAxis
 };
 
 console.time('Total');

lib/loadObj.js

@@ -8,9 +8,12 @@ var loadImage = require('./loadImage');
 var loadMtl = require('./loadMtl');
 var readLines = require('./readLines');
 
+var Axis = Cesium.Axis;
+var Cartesian3 = Cesium.Cartesian3;
 var ComponentDatatype = Cesium.ComponentDatatype;
 var defaultValue = Cesium.defaultValue;
 var defined = Cesium.defined;
+var Matrix4 = Cesium.Matrix4;
 var RuntimeError = Cesium.RuntimeError;
 
 module.exports = loadObj;
@@ -46,6 +49,8 @@ var facePattern2 = /f( +(-?\d+)\/(-?\d+)\/?)( +(-?\d+)\/(-?\d+)\/?)( +(-?\d+)\/(
 var facePattern3 = /f( +(-?\d+)\/(-?\d+)\/(-?\d+))( +(-?\d+)\/(-?\d+)\/(-?\d+))( +(-?\d+)\/(-?\d+)\/(-?\d+))( +(-?\d+)\/(-?\d+)\/(-?\d+))?/;    // f vertex/uv/normal vertex/uv/normal vertex/uv/normal ...
 var facePattern4 = /f( +(-?\d+)\/\/(-?\d+))( +(-?\d+)\/\/(-?\d+))( +(-?\d+)\/\/(-?\d+))( +(-?\d+)\/\/(-?\d+))?/;                                // f vertex//normal vertex//normal vertex//normal ...
 
+var scratchCartesian = new Cartesian3();
+
 /**
  * Parse an obj file.
  *
@@ -53,6 +58,8 @@ var facePattern4 = /f( +(-?\d+)\/\/(-?\d+))( +(-?\d+)\/\/(-?\d+))( +(-?\d+)\/\/(
  * @param {Object} options An object with the following properties:
  * @param {Boolean} options.checkTransparency Do a more exhaustive check for texture transparency by looking at the alpha channel of each pixel.
  * @param {Boolean} options.secure Prevent the converter from reading image or mtl files outside of the input obj directory.
+ * @param {String} options.inputUpAxis Up axis of the obj.
+ * @param {String} options.outputUpAxis Up axis of the converted glTF.
  * @param {Boolean} options.logger A callback function for handling logged messages. Defaults to console.log.
  * @returns {Promise} A promise resolving to the obj data.
  * @exception {RuntimeError} The file does not have any geometry information in it.
@@ -60,6 +67,8 @@ var facePattern4 = /f( +(-?\d+)\/\/(-?\d+))( +(-?\d+)\/\/(-?\d+))( +(-?\d+)\/\/(
  * @private
  */
 function loadObj(objPath, options) {
+    var axisTransform = getAxisTransform(options.inputUpAxis, options.outputUpAxis);
+
     // Global store of vertex attributes listed in the obj file
     var positions = new ArrayStorage(ComponentDatatype.FLOAT);
     var normals = new ArrayStorage(ComponentDatatype.FLOAT);
@@ -223,13 +232,27 @@ function loadObj(objPath, options) {
             var paths = line.substring(7).trim().split(' ');
             mtlPaths = mtlPaths.concat(paths);
         } else if ((result = vertexPattern.exec(line)) !== null) {
-            positions.push(parseFloat(result[1]));
+            var position = scratchCartesian;
-            positions.push(parseFloat(result[2]));
+            position.x = parseFloat(result[1]);
-            positions.push(parseFloat(result[3]));
+            position.y = parseFloat(result[2]);
+            position.z = parseFloat(result[3]);
+            if (defined(axisTransform)) {
+                Matrix4.multiplyByPoint(axisTransform, position, position);
+            }
+            positions.push(position.x);
+            positions.push(position.y);
+            positions.push(position.z);
         } else if ((result = normalPattern.exec(line) ) !== null) {
-            normals.push(parseFloat(result[1]));
+            var normal = scratchCartesian;
-            normals.push(parseFloat(result[2]));
+            normal.x = parseFloat(result[1]);
-            normals.push(parseFloat(result[3]));
+            normal.y = parseFloat(result[2]);
+            normal.z = parseFloat(result[3]);
+            if (defined(axisTransform)) {
+                Matrix4.multiplyByPointAsVector(axisTransform, normal, normal);
+            }
+            normals.push(normal.x);
+            normals.push(normal.y);
+            normals.push(normal.z);
         } else if ((result = uvPattern.exec(line)) !== null) {
             uvs.push(parseFloat(result[1]));
             uvs.push(1.0 - parseFloat(result[2])); // Flip y so 0.0 is the bottom of the image
@@ -446,3 +469,19 @@ function cleanNodes(nodes) {
     setDefaults(nodes);
     return nodes;
 }
+
+function getAxisTransform(inputUpAxis, outputUpAxis) {
+    if (inputUpAxis === 'X' && outputUpAxis === 'Y') {
+        return Axis.X_UP_TO_Y_UP;
+    } else if (inputUpAxis === 'X' && outputUpAxis === 'Z') {
+        return Axis.X_UP_TO_Z_UP;
+    } else if (inputUpAxis === 'Y' && outputUpAxis === 'X') {
+        return Axis.Y_UP_TO_X_UP;
+    } else if (inputUpAxis === 'Y' && outputUpAxis === 'Z') {
+        return Axis.Y_UP_TO_Z_UP;
+    } else if (inputUpAxis === 'Z' && outputUpAxis === 'X') {
+        return Axis.Z_UP_TO_X_UP;
+    } else if (inputUpAxis === 'Z' && outputUpAxis === 'Y') {
+        return Axis.Z_UP_TO_Y_UP;
+    }
+}

lib/obj2gltf.js

@@ -35,6 +35,8 @@ module.exports = obj2gltf;
  * @param {Boolean} [options.bypassPipeline=false] Bypass the gltf-pipeline for debugging purposes. This option overrides many of the options above and will save the glTF with the KHR_materials_common extension.
  * @param {Boolean} [options.checkTransparency=false] Do a more exhaustive check for texture transparency by looking at the alpha channel of each pixel.
  * @param {Boolean} [options.secure=false] Prevent the converter from reading image or mtl files outside of the input obj directory.
+ * @param {String} [options.inputUpAxis='Y'] Up axis of the obj. Choices are 'X', 'Y', and 'Z'.
+ * @param {String} [options.outputUpAxis='Z'] Up axis of the converted glTF. Choices are 'X', 'Y', and 'Z'.
  * @param {Logger} [options.logger] A callback function for handling logged messages. Defaults to console.log.
  */
 function obj2gltf(objPath, gltfPath, options) {
@@ -54,15 +56,18 @@ function obj2gltf(objPath, gltfPath, options) {
     var bypassPipeline = defaultValue(options.bypassPipeline, defaults.bypassPipeline);
     var checkTransparency = defaultValue(options.checkTransparency, defaults.checkTransparency);
     var secure = defaultValue(options.secure, defaults.secure);
+    var inputUpAxis = defaultValue(options.inputUpAxis, defaults.inputUpAxis);
+    var outputUpAxis = defaultValue(options.outputUpAxis, defaults.outputUpAxis);
     var logger = defaultValue(options.logger, defaults.logger);
 
     options.separate = separate;
     options.separateTextures = separateTextures;
     options.checkTransparency = checkTransparency;
     options.secure = secure;
+    options.inputUpAxis = inputUpAxis;
+    options.outputUpAxis = outputUpAxis;
     options.logger = logger;
 
-
     if (!defined(objPath)) {
         throw new DeveloperError('objPath is required');
     }
@@ -197,6 +202,18 @@ obj2gltf.defaults = {
      * @default false
      */
     secure: false,
+    /**
+     * Gets or sets the up axis of the obj.
+     * @type String
+     * @default 'Y'
+     */
+    inputUpAxis: 'Y',
+    /**
+     * Gets or sets the up axis of the converted glTF.
+     * @type String
+     * @default 'Y'
+     */
+    outputUpAxis: 'Y',
     /**
      * @private
      */

specs/data/box-rotated/box-rotated.mtl

@@ -0,0 +1,10 @@
+# Blender MTL File: 'axis.blend'
+# Material Count: 1
+
+newmtl None
+Ns 0
+Ka 0.000000 0.000000 0.000000
+Kd 0.8 0.8 0.8
+Ks 0.8 0.8 0.8
+d 1
+illum 2

specs/data/box-rotated/box-rotated.obj

@@ -0,0 +1,112 @@
+# Blender v2.78 (sub 0) OBJ File: 'axis.blend'
+# www.blender.org
+mtllib box-rotated.mtl
+o Cube.002_Cube
+v -1.707107 -0.292893 0.000000
+v -0.707107 0.707107 1.414214
+v -0.707107 0.707107 -1.414214
+v 0.292893 1.707107 0.000000
+v -0.292893 -1.707107 0.000000
+v 0.707107 -0.707107 1.414214
+v 0.707107 -0.707107 -1.414214
+v 1.707107 0.292893 0.000000
+vn -0.7071 0.7071 0.0000
+vn 0.5000 0.5000 -0.7071
+vn 0.7071 -0.7071 -0.0000
+vn -0.5000 -0.5000 0.7071
+vn -0.5000 -0.5000 -0.7071
+vn 0.5000 0.5000 0.7071
+usemtl None
+s off
+f 1//1 2//1 4//1 3//1
+f 3//2 4//2 8//2 7//2
+f 7//3 8//3 6//3 5//3
+f 5//4 6//4 2//4 1//4
+f 3//5 7//5 5//5 1//5
+f 8//6 4//6 2//6 6//6
+o Cube.001_Cube.002
+v -3.997752 -1.000000 3.997752
+v -3.997752 1.000000 3.997752
+v -3.997752 -1.000000 -3.997752
+v -3.997752 1.000000 -3.997752
+v 3.997752 -1.000000 3.997752
+v 3.997752 1.000000 3.997752
+v 3.997752 -1.000000 -3.997752
+v 3.997752 1.000000 -3.997752
+vn -1.0000 0.0000 0.0000
+vn 0.0000 0.0000 -1.0000
+vn 1.0000 0.0000 0.0000
+vn 0.0000 0.0000 1.0000
+vn 0.0000 -1.0000 0.0000
+vn 0.0000 1.0000 0.0000
+usemtl None
+s off
+f 9//7 10//7 12//7 11//7
+f 11//8 12//8 16//8 15//8
+f 15//9 16//9 14//9 13//9
+f 13//10 14//10 10//10 9//10
+f 11//11 15//11 13//11 9//11
+f 16//12 12//12 10//12 14//12
+o Cube_Cube.001
+v -1.000000 4.235625 1.000000
+v -1.000000 6.235625 1.000000
+v -1.000000 4.235625 -1.000000
+v -1.000000 6.235625 -1.000000
+v 1.000000 4.235625 1.000000
+v 1.000000 6.235625 1.000000
+v 1.000000 4.235625 -1.000000
+v 1.000000 6.235625 -1.000000
+v 0.000000 9.029284 0.000000
+v 1.000000 4.663946 0.571679
+v 1.000000 5.807305 0.571679
+v 1.000000 4.663946 -0.571679
+v 1.000000 5.807305 -0.571679
+v 2.375958 4.663946 0.571679
+v 2.375958 5.807305 0.571679
+v 2.375958 4.663946 -0.571679
+v 2.375958 5.807305 -0.571679
+v -0.310735 4.924891 -1.000000
+v -0.310735 5.546360 -1.000000
+v 0.310735 4.924891 -1.000000
+v 0.310735 5.546360 -1.000000
+v 0.000000 5.235625 -1.538583
+vn -1.0000 0.0000 0.0000
+vn 0.0000 0.0000 -1.0000
+vn 1.0000 0.0000 0.0000
+vn 0.0000 0.0000 1.0000
+vn 0.0000 -1.0000 0.0000
+vn 0.0000 0.3370 -0.9415
+vn -0.9415 0.3370 0.0000
+vn 0.0000 0.3370 0.9415
+vn 0.9415 0.3370 0.0000
+vn 0.0000 1.0000 0.0000
+vn 0.8662 0.0000 -0.4997
+vn 0.0000 -0.8662 -0.4997
+vn 0.0000 0.8662 -0.4997
+vn -0.8662 0.0000 -0.4997
+usemtl None
+s off
+f 17//13 18//13 20//13 19//13
+f 23//14 19//14 34//14 36//14
+f 22//15 21//15 26//15 27//15
+f 21//16 22//16 18//16 17//16
+f 19//17 23//17 21//17 17//17
+f 24//18 20//18 25//18
+f 20//19 18//19 25//19
+f 18//20 22//20 25//20
+f 22//21 24//21 25//21
+f 29//22 27//22 31//22 33//22
+f 21//15 23//15 28//15 26//15
+f 24//15 22//15 27//15 29//15
+f 23//15 24//15 29//15 28//15
+f 32//15 33//15 31//15 30//15
+f 28//14 29//14 33//14 32//14
+f 27//16 26//16 30//16 31//16
+f 26//17 28//17 32//17 30//17
+f 37//23 36//23 38//23
+f 20//14 24//14 37//14 35//14
+f 19//14 20//14 35//14 34//14
+f 24//14 23//14 36//14 37//14
+f 36//24 34//24 38//24
+f 35//25 37//25 38//25
+f 34//26 35//26 38//26

specs/lib/loadObjSpec.js

@@ -5,10 +5,12 @@ var Promise = require('bluebird');
 var loadObj = require('../../lib/loadObj');
 var obj2gltf = require('../../lib/obj2gltf');
 
+var Cartesian3 = Cesium.Cartesian3;
 var clone = Cesium.clone;
 var RuntimeError = Cesium.RuntimeError;
 
 var objUrl = 'specs/data/box/box.obj';
+var objRotatedUrl = 'specs/data/box-rotated/box-rotated.obj';
 var objNormalsUrl = 'specs/data/box-normals/box-normals.obj';
 var objUvsUrl = 'specs/data/box-uvs/box-uvs.obj';
 var objPositionsOnlyUrl = 'specs/data/box-positions-only/box-positions-only.obj';
@@ -341,7 +343,54 @@ describe('loadObj', function() {
             }), done).toResolve();
     });
 
-    it('does not process file with invalid contents', function(done) {
+    function getFirstPosition(data) {
+        var positions = data.nodes[0].meshes[0].positions;
+        return new Cartesian3(positions.get(0), positions.get(1), positions.get(2));
+    }
+
+    function getFirstNormal(data) {
+        var normals = data.nodes[0].meshes[0].normals;
+        return new Cartesian3(normals.get(0), normals.get(1), normals.get(2));
+    }
+
+    function checkAxisConversion(inputUpAxis, outputUpAxis, position, normal) {
+        var sameAxis = (inputUpAxis === outputUpAxis);
+        var options = clone(defaultOptions);
+        options.inputUpAxis = inputUpAxis;
+        options.outputUpAxis = outputUpAxis;
+        return loadObj(objRotatedUrl, options)
+            .then(function(data) {
+                var rotatedPosition = getFirstPosition(data);
+                var rotatedNormal = getFirstNormal(data);
+                if (sameAxis) {
+                    expect(rotatedPosition).toEqual(position);
+                    expect(rotatedNormal).toEqual(normal);
+                } else {
+                    expect(rotatedPosition).not.toEqual(position);
+                    expect(rotatedNormal).not.toEqual(normal);
+                }
+            });
+    }
+
+    it('performs up axis conversion', function(done) {
+        expect(loadObj(objRotatedUrl, defaultOptions)
+            .then(function(data) {
+                var position = getFirstPosition(data);
+                var normal = getFirstNormal(data);
+
+                var axes = ['X', 'Y', 'Z'];
+                var axesLength = axes.length;
+                var promises = [];
+                for (var i = 0; i < axesLength; ++i) {
+                    for (var j = 0; j < axesLength; ++j) {
+                        promises.push(checkAxisConversion(axes[i], axes[j], position, normal));
+                    }
+                }
+                return Promise.all(promises);
+            }), done).toResolve();
+    });
+
+    it('throws when file has invalid contents', function(done) {
         expect(loadObj(objInvalidContentsUrl, defaultOptions), done).toRejectWith(RuntimeError);
     });
 

specs/lib/obj2gltfSpec.js

@@ -68,6 +68,8 @@ describe('obj2gltf', function() {
             textureCompressionOptions : textureCompressionOptions,
             checkTransparency : true,
             secure : true,
+            inputUpAxis : 'Z',
+            outputUpAxis : 'X',
             logger : obj2gltf.defaults.logger
         };