Make composite tile

generator/README.md

@@ -1 +1,17 @@
-Tools for generating sample 3D Tiles tilesets.
+Tools for generating sample 3D Tiles tilesets.
+
+# Make Composite Tile
+
+Creates a composite tile from multiple source tiles.
+
+## Example
+`node ./bin/makeCompositeTile.js batched.b3dm instanced.i3dm points.pnts -o output/composite.cmpt`
+
+## Command-Line Flags
+
+| Flag | Description | Required |
+| --- | --- | --- |
+| `-o`, `--output` | Output path where the composite tile should be written. | No, default `output/composite.cmpt` |
+| `-z`, `--gzip` | Gzip the output composite tile. | No, default `false` |
+
+All unflagged arguments are treated as source tiles to place in the composite tile.

generator/bin/makeCompositeTile.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+'use strict';
+var Promise = require('bluebird');
+
+var argv = require('yargs')
+    .usage('Usage: $0 \<tiles\> [options]')
+    .example('$0 batched.b3dm instanced.i3dm points.pnts -o output/composite.cmpt')
+    .alias('o', 'output')
+    .default('o', 'output/composite.cmpt')
+    .nargs('o', 1)
+    .describe('o', 'Output path where the composite tile should be written.')
+    .boolean('z')
+    .alias('z', 'gzip')
+    .default('z', false)
+    .describe('z', 'Flag to gzip the output composite tile.')
+    .help('h')
+    .alias('h', 'help')
+    .demand(1)
+    .argv;
+
+var readTile = require('../lib/readTile');
+var writeTile = require('../lib/writeTile');
+
+var tilePaths = argv._;
+var outputPath = argv.o;
+
+Promise.map(tilePaths, function(tilePath) {
+    return readTile(tilePath);
+})
+    .then(function(tiles) {
+        var header = new Buffer(16);
+        var buffers = [];
+        buffers.push(header);
+        var byteLength = header.length;
+        for (var i = 0; i < tiles.length; i++) {
+            var tile = tiles[i];
+            // Byte align all tiles to 4 bytes
+            var tilePadding = tile.length % 4;
+            if (tilePadding !== 0) {
+                tile = Buffer.concat([tile, new Buffer(4 - tilePadding)]);
+            }
+            tile.writeUInt32LE(tile.length, 8); // byteLength
+            byteLength += tile.length;
+            buffers.push(tile);
+        }
+        header.write('cmpt', 0);                // magic
+        header.writeUInt32LE(1, 4);             // version
+        header.writeUInt32LE(byteLength, 8);    // byteLength
+        header.writeUInt32LE(tiles.length, 12); // tilesLength
+        var buffer = Buffer.concat(buffers);
+        var options = {};
+        if (argv.z) {
+            options.gzip = true;
+        }
+        return writeTile(outputPath, buffer, options);
+    });

generator/lib/isGzipped.js

@@ -0,0 +1,22 @@
+'use strict';
+var Cesium = require('cesium');
+
+var DeveloperError = Cesium.DeveloperError;
+var defined = Cesium.defined;
+
+module.exports = isGzipped;
+
+/**
+ * Test if the provided data is gzipped.
+ *
+ * @param {Buffer} data A buffer containing the data to test.
+ * @returns {Boolean} True if the data is gzipped, False if not.
+ *
+ * @throws {DeveloperError} Will throw an error if data is undefined.
+ */
+function isGzipped(data) {
+    if (!defined(data)) {
+        throw new DeveloperError('data must be defined.');
+    }
+    return data[0] === 0x1f && data[1] === 0x8b;
+}

generator/lib/readTile.js

@@ -0,0 +1,39 @@
+'use strict';
+var Cesium = require('cesium');
+var Promise = require('bluebird');
+var fs = require('fs-extra');
+var zlib = require('zlib');
+
+var DeveloperError = Cesium.DeveloperError;
+var defined = Cesium.defined;
+
+var isGzipped = require('./isGzipped');
+
+var fsReadFile = Promise.promisify(fs.readFile);
+var zlibGunzip = Promise.promisify(zlib.gunzip);
+
+module.exports = readTile;
+
+/**
+ * Reads tile data from a file.
+ *
+ * @param {String} filePath The file path to read from.
+ * @returns {Promise} A promise that resolves with the data when the read operation completes.
+ *
+ * @throws {DeveloperError} Will throw an error if filePath is undefined.
+ */
+function readTile(filePath) {
+    return Promise.resolve()
+        .then(function() {
+            if (!defined(filePath)) {
+                throw new DeveloperError('filePath must be defined');
+            }
+            return fsReadFile(filePath);
+        })
+        .then(function(buffer) {
+            if (isGzipped(buffer)) {
+                return zlibGunzip(buffer, undefined);
+            }
+            return buffer;
+        });
+}

generator/lib/writeTile.js

@@ -0,0 +1,47 @@
+'use strict';
+var Cesium = require('cesium');
+var Promise = require('bluebird');
+var fs = require('fs-extra');
+var zlib = require('zlib');
+
+var DeveloperError = Cesium.DeveloperError;
+var defaultValue = Cesium.defaultValue;
+var defined = Cesium.defined;
+
+var fsOutputFile = Promise.promisify(fs.outputFile);
+var zlibGzip = Promise.promisify(zlib.gzip);
+
+module.exports = writeTile;
+
+/**
+ * Writes the tile data to a file.
+ *
+ * @param {String} filePath The file path where the tile should be written.
+ * @param {Buffer} tileData A buffer containing the tile data to write.
+ * @param {Object} [options] Defines custom behavior for writing.
+ * @param {Boolean} [options.gzip=false] Flag to gzip the buffer data before writing.
+ * @returns {Promise} A promise that resolves when the write operation completes.
+ *
+ * @throws {DeveloperError} Throws an error if filePath is undefined.
+ * @throws {DeveloperError} Throws an error if tileData is undefined.
+ */
+function writeTile(filePath, tileData, options) {
+    return Promise.resolve()
+        .then(function() {
+            if (!defined(filePath)) {
+                throw new DeveloperError('filePath must be defined.');
+            }
+            if (!defined(tileData)) {
+                throw new DeveloperError('tileData must be defined.');
+            }
+            options = defaultValue(options, {});
+            var gzip = defaultValue(options.gzip, false);
+            if (gzip) {
+                return zlibGzip(tileData, undefined);
+            }
+            return Promise.resolve(tileData);
+        })
+        .then(function(buffer) {
+            return fsOutputFile(filePath, buffer);
+        });
+}

generator/package.json

@@ -23,10 +23,11 @@
   },
   "dependencies": {
     "bluebird": "3.4.1",
-    "cesium": "1.24"
+    "cesium": "1.24",
+    "fs-extra": "0.30.0",
+    "yargs": "5.0.0"
   },
   "devDependencies": {
-    "fs-extra": "0.30.0",
     "gulp": "3.9.1",
     "gulp-jshint": "2.0.1",
     "istanbul": "0.4.4",
@@ -37,7 +38,7 @@
     "open": "0.0.5",
     "request": "2.74.0",
     "requirejs": "2.2.0",
-    "yargs": "4.8.1"
+    "rimraf": "2.5.4"
   },
   "scripts": {
     "jsHint": "gulp jsHint",

generator/specs/bin/makeCompositeTileSpec.js

@@ -0,0 +1,82 @@
+'use strict';
+var Promise = require('bluebird');
+var childProcess = require('child_process');
+var fs = require('fs-extra');
+var rimraf = require('rimraf');
+
+var isGzipped = require('../../lib/isGzipped');
+
+var fsReadFile = Promise.promisify(fs.readFile);
+var rimrafAsync = Promise.promisify(rimraf);
+
+var justHeaderI3dmPath = './specs/data/justHeader.i3dm';
+var justHeaderGzippedI3dmPath = './specs/data/justHeaderGzipped.i3dm';
+var testOutputPath = './specs/data/.test/';
+
+describe('makeCompositeTile', function() {
+    afterAll(function(done) {
+        rimrafAsync(testOutputPath, {})
+            .then(done);
+    });
+
+    it('makes a composite tile', function(done) {
+        var outputPath = testOutputPath + 'composite.cmpt';
+        expect(makeCompositeTile([justHeaderI3dmPath, justHeaderI3dmPath, '-o', outputPath])
+            .then(function() {
+                return fsReadFile(outputPath);
+            })
+            .then(function(tileData) {
+                var magic = tileData.toString('utf8', 0, 4);
+                var byteLength = 16 + 32 + 32;
+                expect(tileData.length).toBe(byteLength);
+                expect(magic).toEqual('cmpt');                     // magic
+                expect(tileData.readUInt32LE(4)).toBe(1);          // version
+                expect(tileData.readUInt32LE(8)).toBe(byteLength); // byteLength
+                expect(tileData.readUInt32LE(12)).toBe(2);         // tilesLength
+                var tileMagic = tileData.toString('utf8', 16, 20);
+                expect(tileMagic).toEqual('i3dm');
+            }), done).toResolve();
+    });
+
+    it('makes a composite tile from gzipped tiles', function(done) {
+        var outputPath = testOutputPath + 'compositeFromGzipped.cmpt';
+        expect(makeCompositeTile([justHeaderGzippedI3dmPath, justHeaderGzippedI3dmPath, '-o', outputPath])
+            .then(function() {
+                return fsReadFile(outputPath);
+            })
+            .then(function(tileData) {
+                var magic = tileData.toString('utf8', 0, 4);
+                var byteLength = 16 + 32 + 32;
+                expect(tileData.length).toBe(byteLength);
+                expect(magic).toEqual('cmpt');                     // magic
+                expect(tileData.readUInt32LE(4)).toBe(1);          // version
+                expect(tileData.readUInt32LE(8)).toBe(byteLength); // byteLength
+                expect(tileData.readUInt32LE(12)).toBe(2);         // tilesLength
+                var tileMagic = tileData.toString('utf8', 16, 20);
+                expect(tileMagic).toEqual('i3dm');
+            }), done).toResolve();
+    });
+
+    it('makes a gzipped composite tile', function(done) {
+        var outputPath = testOutputPath + 'compositeGzipped.cmpt';
+        expect(makeCompositeTile([justHeaderI3dmPath, justHeaderI3dmPath, '-o', outputPath, '-z'])
+            .then(function() {
+                return fsReadFile(outputPath);
+            })
+            .then(function(tileData) {
+                expect(isGzipped(tileData)).toBeTruthy();
+            }), done).toResolve();
+    });
+});
+
+function makeCompositeTile(args) {
+    var makeCompositeTileProcess = childProcess.fork('./bin/makeCompositeTile', args);
+    return new Promise(function(resolve, reject) {
+        makeCompositeTileProcess.on('close', function() {
+            resolve();
+        });
+        makeCompositeTileProcess.on('error', function() {
+            reject();
+        });
+    });
+}

generator/specs/lib/isGzippedSpec.js

@@ -0,0 +1,24 @@
+'use strict';
+var Promise = require('bluebird');
+var zlib = require('zlib');
+
+var isGzipped = require('../../lib/isGzipped');
+
+var zlibGzip = Promise.promisify(zlib.gzip);
+
+describe('isGzipped', function() {
+    it('throws DeveloperError if data is undefined', function() {
+        expect(function() {
+            isGzipped(undefined);
+        }).toThrowError();
+    });
+
+    it('detects when data is gzipped', function(done) {
+        var data = new Buffer(40);
+        expect(isGzipped(data)).toBeFalsy();
+        expect(zlibGzip(data, undefined)
+            .then(function(zippedData) {
+                expect(isGzipped(zippedData)).toBeTruthy();
+            }), done).toResolve();
+    });
+});

generator/specs/lib/readTileSpec.js

@@ -0,0 +1,27 @@
+'use strict';
+var readTile = require('../../lib/readTile');
+
+describe('readTile', function() {
+    it('throws DeveloperError if filePath is undefined', function(done) {
+        expect(readTile(undefined)
+            .catch(function(error) {
+                expect(error).toBeDefined();
+            }), done).toResolve();
+    });
+
+    it('reads a tile', function(done) {
+        expect(readTile('./specs/data/justHeader.i3dm')
+            .then(function(tileData) {
+                var magic = tileData.toString('utf8', 0, 4);
+                expect(magic).toEqual('i3dm');
+            }), done).toResolve();
+    });
+
+    it('reads a gzipped tile', function(done) {
+        expect(readTile('./specs/data/justHeaderGzipped.i3dm')
+            .then(function(tileData) {
+                var magic = tileData.toString('utf8', 0, 4);
+                expect(magic).toEqual('i3dm');
+            }), done).toResolve();
+    });
+});