3d-tiles-optimize 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1 @@
+# 3d-tiles-optimize

package/bin/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import {program} from '../dist/cli.mjs';
+
+program.disableGlobalOption('--silent');
+program.run();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "3d-tiles-optimize",
+  "version": "0.0.1",
+  "description": "3d tiles 压缩优化器",
+  "license": "Apache-2.0",
+  "repository": "github:itfsw/3d-tiles-optimize",
+  "private": false,
+  "type": "module",
+  "types": "./dist/cli.d.mts",
+  "exports": {
+    "types": "./dist/cli.d.mts",
+    "default": "./dist/cli.mjs"
+  },
+  "bin": {
+    "3d-tiles-optimize": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsdown src/cli.ts",
+    "build:watch": "tsdown src/cli.ts --watch",
+    "test": "3d-tiles-optimize optimize ./data/input ./data/output --logLevel trace"
+  },
+  "dependencies": {
+    "@donmccurdy/caporal": "^0.0.10",
+    "@gltf-transform/core": "^4.3.0",
+    "@gltf-transform/extensions": "^4.3.0",
+    "@gltf-transform/functions": "^4.3.0",
+    "3d-tiles-tools": "^0.5.1",
+    "draco3dgltf": "^1.5.7",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "@types/draco3dgltf": "^1.4.3",
+    "@types/node": "^25.2.1",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "src/",
+    "README.md",
+    "LICENSE.md",
+    "package-lock.json"
+  ],
+  "publishConfig":   {
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,38 @@
+import {program, Validator} from './program.js';
+import {optimize} from "./optimize/functions.js";
+import {Loggers} from "3d-tiles-tools";
+
+const logger = Loggers.get("CLI");
+
+// OPTIMIZE
+program.command('optimize', 'Optimize 3d-tiles by 3d-tiles-tools and glTF-Transform')
+    // input output
+    .argument('<input>', 'Dir to read 3d-tiles')
+    .argument('<output>', 'Dir to write output')
+    // options
+    .option('--logLevel <logLevel>', 'The log level. Valid values are trace, debug, info, warn, error, fatal, and silent')
+    // action
+    .action(async ({args, options}) => {
+        // 日志
+        const logLevel = options.logLevel as string;
+        if (logLevel !== undefined) {
+            const validLogLevels = [
+                "trace",
+                "debug",
+                "info",
+                "warn",
+                "error",
+                "fatal",
+                "silent",
+            ];
+            if (validLogLevels.includes(logLevel)) {
+                Loggers.setLevel(logLevel);
+            } else {
+                logger.warn(`Invalid log level: ${logLevel}`);
+                Loggers.setLevel("info");
+            }
+        }
+        return optimize(args.input as string, args.output as string);
+    });
+
+export {Validator, program};

package/src/optimize/functions.ts

@@ -0,0 +1,47 @@
+import {type Pipeline, type TilesetStage} from '3d-tiles-tools'
+import {ExPipelineExecutor} from "../pipeline/ExPipelineExecutor.js";
+
+/**
+ * 优化
+ * @param input 输入路径
+ * @param output 输出路径
+ */
+export function optimize(input: string, output: string): Promise<void> {
+    // 创建流水线
+    const tilesetStages: TilesetStage[] = [];
+    const pipeline: Pipeline = {
+        input: input,
+        output: output,
+        tilesetStages: tilesetStages
+    }
+    // 添加流水线步骤
+    // 1. upgrade
+    tilesetStages.push({
+        name: "upgrade",
+        description: "Upgrade the input tileset to the latest version"
+    })
+    // 2. combine
+    tilesetStages.push({
+        name: "combine",
+        description: "Combine all external tilesets into one"
+    })
+    // 3. 优化
+    tilesetStages.push({
+        name: "_optimizeGlb",
+        description: "Optimize GLB",
+        contentStages: [
+            {
+                name: "optimizeGlb",
+                description: "Apply glTF-Transform to each GLB content, with the given options",
+                options: {
+                    "dracoOptions": {
+                        "compressionLevel": 10
+                    }
+                }
+            }
+        ]
+    })
+
+    // 执行流水线
+    return ExPipelineExecutor.executePipeline(pipeline, true)
+}

package/src/optimize/glb.ts

@@ -0,0 +1,67 @@
+import sharp from "sharp";
+import draco3d from 'draco3dgltf';
+import {logger} from "./logger.js";
+import {ALL_EXTENSIONS} from "@gltf-transform/extensions";
+import {NodeIO, type Transform} from "@gltf-transform/core";
+import {dedup, draco, prune, resample, textureCompress} from '@gltf-transform/functions';
+
+/**
+ * Given an input buffer containing a binary glTF asset, optimize it
+ * using glTF-Transform with the provided options.
+ *
+ * This method also performs a few updates of certain legacy
+ * features that are specific for the GLB data that is part
+ * of I3DM and B3DM. Details are not specified here.
+ *
+ * @param glbBuffer - The buffer containing the binary glTF.
+ * @param options - Options specifying custom glTF-Transform behavior.
+ * @returns A promise that resolves to the optimized binary glTF.
+ */
+export async function optimizeGlb(glbBuffer: Buffer, options: any): Promise<Buffer> {
+    options = options ?? {};
+    return new Promise((resolve, reject) => {
+        // 读取 buffer
+        createNodeIO().then(io => {
+            io.readBinary(glbBuffer).then(document => {
+                // 优化配置
+                const transforms: Transform[] = []
+
+                // Losslessly resample animation frames.
+                transforms.push(resample())
+                // Remove unused nodes, textures, or other data.
+                transforms.push(prune())
+                // Remove duplicate vertex or texture data, if any.
+                transforms.push(dedup())
+                // Compress mesh geometry with Draco.
+                transforms.push(draco())
+                // Convert textures to WebP (Requires glTF Transform v3 and Node.js).
+                transforms.push(textureCompress({
+                    encoder: sharp,
+                    targetFormat: 'webp',
+                    resize: [1024, 2024],
+                }))
+
+                document.transform(...transforms).then(doc => {
+                    // 数据输出
+                    io.writeBinary(doc).then(data => {
+                        resolve(Buffer.from(data));
+                    }).catch(reject)
+                }).catch(reject)
+            }).catch(reject)
+        }).catch(reject)
+    });
+}
+
+/**
+ * 创建NodeIO
+ */
+async function createNodeIO() {
+    // Configure I/O.
+    return new NodeIO()
+        .setLogger(logger)
+        .registerExtensions(ALL_EXTENSIONS)
+        .registerDependencies({
+            'draco3d.decoder': await draco3d.createDecoderModule(),
+            'draco3d.encoder': await draco3d.createEncoderModule(),
+        });
+}

package/src/optimize/logger.ts

@@ -0,0 +1,27 @@
+import type {ILogger} from "@gltf-transform/core";
+import {Loggers} from "3d-tiles-tools";
+
+const log = Loggers.get('glTF-Transform')
+
+/**
+ * Logger 实现
+ */
+export class Logger implements ILogger {
+    debug(text: string): void {
+        log.debug(text);
+    }
+
+    info(text: string): void {
+        log.info(text);
+    }
+
+    warn(text: string): void {
+        log.warn(text);
+    }
+
+    error(text: string): void {
+        log.error(text);
+    }
+}
+
+export const logger: Logger = new Logger()

package/src/pipeline/ExContentStageExecutor.ts

@@ -0,0 +1,87 @@
+import {
+    type BasicTilesetProcessor,
+    ContentDataTypes,
+    type ContentStage,
+    ContentStageExecutor,
+    ContentStages,
+    PipelineError,
+    type TilesetEntry
+} from "3d-tiles-tools";
+import {optimizeGlb} from "../optimize/glb.js";
+
+/**
+ * 拓展 ContentStageExecutor
+ */
+export class ExContentStageExecutor {
+    /**
+     * Execute the given `ContentStage`.
+     *
+     * @param contentStage - The `ContentStage` object
+     * @param tilesetProcessor - The `BasicTilesetProcessor`
+     * @returns A promise that resolves when the process is finished
+     * @throws PipelineError If one of the processing steps causes
+     * an error.
+     */
+    static async executeContentStage(
+        contentStage: ContentStage,
+        tilesetProcessor: BasicTilesetProcessor
+    ) {
+        try {
+            if (contentStage.name === ContentStages.CONTENT_STAGE_OPTIMIZE_GLB) {
+                const options = contentStage.options;
+                await ExContentStageExecutor.executeOptimizeGlb(tilesetProcessor, options);
+            } else {
+                await ContentStageExecutor.executeContentStage(
+                    contentStage,
+                    tilesetProcessor
+                );
+            }
+        } catch (e) {
+            throw new PipelineError(`${e}`);
+        }
+    }
+
+    /**
+     * Performs the 'optimizeGlb' content stage with the given processor.
+     *
+     * This will process all tile contents entries of the source tileset
+     * that have the `CONTENT_TYPE_GLB`, and apply the `gltf-pipeline`
+     * optimization with the given options to them.
+     *
+     * @param tilesetProcessor - The `BasicTilesetProcessor`
+     * @param options - The options for `gltf-pipeline`
+     * @returns A promise that resolves when the process is finished
+     * @throws Error If one of the processing steps causes
+     * an error.
+     */
+    private static async executeOptimizeGlb(
+        tilesetProcessor: BasicTilesetProcessor,
+        options: any
+    ): Promise<void> {
+        // The entry processor receives the source entry, and
+        // returns a target entry where the the `value` contains
+        // GLB data that was optimized with `gltf-pipeline`
+        // and the given options
+        const entryProcessor = async (
+            sourceEntry: TilesetEntry,
+            type: string | undefined
+        ) => {
+            if (type !== ContentDataTypes.CONTENT_TYPE_GLB) {
+                return sourceEntry;
+            }
+            const targetValue = await optimizeGlb(
+                sourceEntry.value,
+                options
+            );
+            const targetEntry = {
+                key: sourceEntry.key,
+                value: targetValue,
+            };
+            return targetEntry;
+        };
+        await tilesetProcessor.processTileContentEntries(
+            (uri: string) => uri,
+            entryProcessor
+        );
+    }
+}

package/src/pipeline/ExPipelineExecutor.ts

@@ -0,0 +1,92 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import {Loggers, type Pipeline} from "3d-tiles-tools";
+import {ExTilesetStageExecutor} from "./ExTilesetStageExecutor.js";
+
+const logger = Loggers.get("pipeline");
+
+/**
+ * Copy PipelineExecutor
+ */
+export class ExPipelineExecutor {
+    /**
+     * The directory to store temporary files in.
+     *
+     * If this is `undefined`, then a directory in the
+     * default system temp directory will be used.
+     */
+    private static tempBaseDirectory: string | undefined;
+
+    /**
+     * Set the directory to store temporary files in.
+     *
+     * If this is `undefined`, then a directory in the
+     * default system temp directory will be used.
+     *
+     * This is primarily intended for testing, demos, and
+     * debugging.
+     *
+     * @param directory - The directory
+     */
+    static setTempBaseDirectory(directory: string | undefined) {
+        ExPipelineExecutor.tempBaseDirectory = directory;
+    }
+
+    /**
+     * Executes the given `Pipeline`.
+     *
+     * @param pipeline - The `Pipeline` object
+     * @param overwrite - Whether outputs should be overwritten if
+     * they already exist
+     * @returns A promise that resolves when the process is finished
+     * @throws PipelineError If one of the processing steps causes
+     * an error.
+     */
+    static async executePipeline(pipeline: Pipeline, overwrite: boolean) {
+        let currentInput = pipeline.input;
+        let currentOutput: string | undefined = undefined;
+        let currentOverwrite = true;
+
+        const tilesetStages = pipeline.tilesetStages;
+
+        // Create a temporary directory for the intermediate
+        // processing steps (if there are more than one)
+        // TODO: This is not cleaned up at the end...
+        let tempBasePath = ExPipelineExecutor.tempBaseDirectory;
+        if (!tempBasePath) {
+            if (tilesetStages.length > 1) {
+                tempBasePath = fs.mkdtempSync(
+                    path.join(os.tmpdir(), "3d-tiles-tools-pipeline-")
+                );
+            }
+        }
+
+        // Execute each `TilesetStage`
+        for (let t = 0; t < tilesetStages.length; t++) {
+            const tilesetStage = tilesetStages[t];
+
+            const message =
+                `  Executing tilesetStage ${t} of ` +
+                `${tilesetStages.length}: ${tilesetStage.name}`;
+            logger.debug(message);
+
+            if (t == tilesetStages.length - 1) {
+                currentOutput = pipeline.output;
+                currentOverwrite = overwrite;
+            } else {
+                const nameSuffix = tilesetStage.name.replace(/[^\w\s]/gi, "");
+                currentOutput = `${tempBasePath}/tilesetStage-${t}-${nameSuffix}`;
+                currentOverwrite = true;
+            }
+
+            await ExTilesetStageExecutor.executeTilesetStage(
+                tilesetStage,
+                currentInput,
+                currentOutput,
+                currentOverwrite
+            );
+            currentInput = currentOutput;
+        }
+    }
+}

package/src/pipeline/ExTilesetStageExecutor.ts

@@ -0,0 +1,255 @@
+import {
+    BasicTilesetProcessor,
+    Buffers,
+    ContentDataTypeChecks,
+    ContentDataTypes,
+    Loggers,
+    PipelineError,
+    TilesetCombiner,
+    TilesetDataProcessor,
+    type TilesetEntry,
+    type TilesetStage,
+    TilesetStages,
+    TilesetUpgrader
+} from "3d-tiles-tools";
+import {ExContentStageExecutor} from "./ExContentStageExecutor.js";
+
+const logger = Loggers.get("pipeline");
+
+/**
+ * Copy TilesetStageExecutor
+ */
+export class ExTilesetStageExecutor {
+    /**
+     * Executes the given `TilesetStage`.
+     *
+     * @param tilesetStage - The `TilesetStage` object
+     * @param currentInput - The current input name, or a temporary
+     * name for intermediate steps (see `Pipeline.input` for details)
+     * @param currentOutput - The current output name, or a temporary
+     * name for intermediate steps (see `Pipeline.input` for details)
+     * @param overwrite - Whether outputs should be overwritten if
+     * they already exist
+     * @returns A promise that resolves when the process is finished
+     * @throws PipelineError If one of the processing steps causes
+     * an error.
+     */
+    static async executeTilesetStage(
+        tilesetStage: TilesetStage,
+        currentInput: string,
+        currentOutput: string,
+        overwrite: boolean
+    ) {
+        logger.debug(`  Executing tilesetStage : ${tilesetStage.name}`);
+        logger.debug(`    currentInput:  ${currentInput}`);
+        logger.debug(`    currentOutput: ${currentOutput}`);
+
+        try {
+            await ExTilesetStageExecutor.executeTilesetStageInternal(
+                tilesetStage,
+                currentInput,
+                currentOutput,
+                overwrite
+            );
+        } catch (e) {
+            throw new PipelineError(`${e}`);
+        }
+    }
+
+    /**
+     * Implementation for `executeTilesetStage`.
+     *
+     * For details about the arguments, see `executeTilesetStage`.
+     *
+     * @param tilesetStage - The `TilesetStage` object
+     * @param currentInput - The current input name
+     * @param currentOutput - The current output name
+     * @param overwrite - Whether outputs should be overwritten
+     * @returns A promise that resolves when the process is finished
+     * @throws Error If one of the processing steps causes
+     * an error.
+     */
+    private static async executeTilesetStageInternal(
+        tilesetStage: TilesetStage,
+        currentInput: string,
+        currentOutput: string,
+        overwrite: boolean
+    ) {
+        if (tilesetStage.name === TilesetStages.TILESET_STAGE_GZIP) {
+            const condition = ContentDataTypeChecks.createTypeCheck(
+                tilesetStage.includedContentTypes,
+                tilesetStage.excludedContentTypes
+            );
+            await ExTilesetStageExecutor.executeGzip(
+                currentInput,
+                currentOutput,
+                overwrite,
+                condition
+            );
+        } else if (tilesetStage.name === TilesetStages.TILESET_STAGE_UNGZIP) {
+            await ExTilesetStageExecutor.executeGunzip(
+                currentInput,
+                currentOutput,
+                overwrite
+            );
+        } else if (tilesetStage.name === TilesetStages.TILESET_STAGE_UPGRADE) {
+            const gltfUpgradeOptions = undefined;
+            const targetVersion = "1.1";
+            const tilesetUpgrader = new TilesetUpgrader(
+                targetVersion,
+                gltfUpgradeOptions
+            );
+            await tilesetUpgrader.upgrade(currentInput, currentOutput, overwrite);
+        } else if (tilesetStage.name === TilesetStages.TILESET_STAGE_COMBINE) {
+            const externalTilesetDetector = ContentDataTypeChecks.createIncludedCheck(
+                ContentDataTypes.CONTENT_TYPE_TILESET
+            );
+            const tilesetCombiner = new TilesetCombiner(externalTilesetDetector);
+            await tilesetCombiner.combine(currentInput, currentOutput, overwrite);
+        } else {
+            await ExTilesetStageExecutor.executeTilesetContentStages(
+                tilesetStage,
+                currentInput,
+                currentOutput,
+                overwrite
+            );
+        }
+    }
+
+    /**
+     * Performs the 'gzip' tileset stage with the given parameters.
+     *
+     * This will process all entries of the source tileset. The
+     * data of entries that match the given condition will be
+     * compressed with gzip. Other entries remain unaffected.
+     *
+     * @param currentInput - The current input name
+     * @param currentOutput - The current output name
+     * @param overwrite - Whether outputs should be overwritten
+     * @param condition - The condition that was created from
+     * the included- and excluded types that have been defined
+     * in the `ContentStage`.
+     * @returns A promise that resolves when the process is finished
+     * @throws Error If one of the processing steps causes
+     * an error.
+     */
+    private static async executeGzip(
+        currentInput: string,
+        currentOutput: string,
+        overwrite: boolean,
+        condition: (type: string | undefined) => boolean
+    ): Promise<void> {
+        const tilesetProcessor = new TilesetDataProcessor();
+        await tilesetProcessor.begin(currentInput, currentOutput, overwrite);
+
+        // The entry processor receives the source entry, and
+        // returns a target entry where the `value` is zipped
+        // if the source entry matches the given condition.
+        const entryProcessor = async (
+            sourceEntry: TilesetEntry,
+            type: string | undefined
+        ) => {
+            let targetValue = sourceEntry.value;
+            const shouldZip = condition(type);
+            if (shouldZip) {
+                targetValue = Buffers.gzip(sourceEntry.value);
+            }
+            const targetEntry = {
+                key: sourceEntry.key,
+                value: targetValue,
+            };
+            return targetEntry;
+        };
+
+        await tilesetProcessor.processAllEntries(entryProcessor);
+        await tilesetProcessor.end();
+    }
+
+    /**
+     * Performs the 'gunzip' tileset stage with the given parameters.
+     *
+     * This will process all entries of the source tileset. The
+     * data of entries that is compressed with gzip will be
+     * uncompressed. Other entries remain unaffected.
+     *
+     * @param currentInput - The current input name
+     * @param currentOutput - The current output name
+     * @param overwrite - Whether outputs should be overwritten
+     * @returns A promise that resolves when the process is finished
+     * @throws Error If one of the processing steps causes
+     * an error.
+     */
+    private static async executeGunzip(
+        currentInput: string,
+        currentOutput: string,
+        overwrite: boolean
+    ): Promise<void> {
+        const tilesetProcessor = new TilesetDataProcessor();
+        await tilesetProcessor.begin(currentInput, currentOutput, overwrite);
+
+        // The entry processor receives the source entry, and
+        // returns a target entry where the `value` is unzipped
+        // (If the data was not zipped, then `Buffers.gunzip`
+        // returns an unmodified result)
+        const entryProcessor = async (
+            sourceEntry: TilesetEntry,
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            type: string | undefined
+        ) => {
+            const targetEntry = {
+                key: sourceEntry.key,
+                value: Buffers.gunzip(sourceEntry.value),
+            };
+            return targetEntry;
+        };
+
+        await tilesetProcessor.processAllEntries(entryProcessor);
+        await tilesetProcessor.end();
+    }
+
+    /**
+     * Execute all `ContentStage` objects in the given `TilesetStage`.
+     *
+     * For details about the arguments, see `executeTilesetStage`.
+     *
+     * @param tilesetStage - The `TilesetStage` object
+     * @param currentInput - The current input name
+     * @param currentOutput - The current output name
+     * @param overwrite - Whether outputs should be overwritten
+     * @returns A promise that resolves when the process is finished
+     * @throws Error If one of the processing steps causes
+     * an error.
+     */
+    private static async executeTilesetContentStages(
+        tilesetStage: TilesetStage,
+        currentInput: string,
+        currentOutput: string,
+        overwrite: boolean
+    ) {
+        try {
+            const tilesetProcessor = new BasicTilesetProcessor();
+            await tilesetProcessor.begin(currentInput, currentOutput, overwrite);
+
+            const contentStages = tilesetStage.contentStages;
+            if (contentStages) {
+                for (let c = 0; c < contentStages.length; c++) {
+                    const contentStage = contentStages[c];
+
+                    const message =
+                        `    Executing contentStage ${c} of ` +
+                        `${contentStages.length}: ${contentStage.name}`;
+                    logger.debug(message);
+
+                    await ExContentStageExecutor.executeContentStage(
+                        contentStage,
+                        tilesetProcessor
+                    );
+                }
+
+                await tilesetProcessor.end();
+            }
+        } catch (e) {
+            throw new PipelineError(`${e}`);
+        }
+    }
+}

package/src/program.ts

@@ -0,0 +1,164 @@
+import {
+	type Command,
+	type ParsedOption,
+	program as _program,
+	type Validator as CaporalValidator,
+} from '@donmccurdy/caporal';
+
+const PAD_EMOJI = new Set(['🫖', '🖼', '⏯']);
+
+/**********************************************************************************************
+ * Program.
+ */
+
+export interface IProgram {
+    command: (name: string, desc: string) => ICommand;
+    option: (name: string, desc: string, options: IProgramOptions) => this;
+    section: (name: string, icon: string) => this;
+}
+
+interface IExecOptions {
+    silent?: boolean;
+}
+
+interface IInternalProgram extends IProgram {
+    version: (version: string) => this;
+    description: (desc: string) => this;
+    disableGlobalOption: (name: string) => this;
+    run: () => this;
+    exec: (args: unknown[], options?: IExecOptions) => Promise<void>;
+}
+
+export interface IProgramOptions<T = unknown> {
+    default?: T;
+    validator?: CaporalValidator;
+    action?: IActionFn;
+    hidden?: boolean;
+}
+
+export type IActionFn = (params: {
+    args: Record<string, unknown>;
+    options: Record<string, unknown>;
+}) => void;
+
+export interface IHelpOptions {
+    sectionName?: string;
+}
+
+class ProgramImpl implements IInternalProgram {
+    version(version: string): this {
+        _program.version(version);
+        return this;
+    }
+
+    description(desc: string): this {
+        _program.description(desc);
+        return this;
+    }
+
+    help(help: string, options?: IHelpOptions): this {
+        _program.help(help, options);
+        return this;
+    }
+
+    section(_name: string, _icon: string): this {
+        const icon = _icon + (PAD_EMOJI.has(_icon) ? ' ' : '');
+        const name = _name.toUpperCase();
+        const line = ''.padEnd(50 - name.length - 1, '─');
+        _program.command('', `\n\n${icon} ${name} ${line}`);
+        return this;
+    }
+
+    command(name: string, desc: string): ICommand {
+        return new CommandImpl(_program, name, desc);
+    }
+
+    option<T>(name: string, desc: string, options: IProgramOptions<T>): this {
+        // biome-ignore lint/suspicious/noExplicitAny: TODO
+        _program.option(name, desc, {global: true, ...options} as any);
+        return this;
+    }
+
+    disableGlobalOption(name: string): this {
+        _program.disableGlobalOption(name);
+        return this;
+    }
+
+    run(): this {
+        _program.run();
+        return this;
+    }
+
+    async exec(args: unknown[], options?: IExecOptions): Promise<void> {
+        // biome-ignore lint/suspicious/noExplicitAny: TODO
+        await _program.exec(args as any, options as any);
+    }
+}
+
+/**********************************************************************************************
+ * Command.
+ */
+
+export interface ICommand {
+    help: (text: string) => this;
+    argument: (name: string, desc: string) => this;
+    option: (name: string, desc: string, options?: ICommandOptions) => this;
+    action: (fn: IActionFn) => this;
+    alias: (name: string) => this;
+}
+
+export interface ICommandOptions {
+    required?: boolean;
+    default?: ParsedOption;
+    validator?: CaporalValidator;
+    hidden?: boolean;
+}
+
+class CommandImpl implements ICommand {
+    _ctx: Command;
+
+    constructor(program: typeof _program, name: string, desc: string) {
+        this._ctx = program.command(name, desc);
+    }
+
+    help(text: string) {
+        this._ctx.help(text);
+        return this;
+    }
+
+    argument(name: string, desc: string) {
+        this._ctx.argument(name, desc);
+        return this;
+    }
+
+    option(name: string, desc: string, options?: ICommandOptions) {
+        this._ctx.option(name, desc, options);
+        return this;
+    }
+
+    action(fn: IActionFn) {
+        this._ctx.action(async (args) => {
+            // biome-ignore lint/suspicious/noExplicitAny: TODO
+            return fn({...args} as any);
+        });
+        return this;
+    }
+
+    alias(name: string) {
+        this._ctx.alias(name);
+        return this;
+    }
+}
+
+export const program: ProgramImpl = new ProgramImpl();
+
+/**********************************************************************************************
+ * Validator.
+ */
+
+export const Validator: Record<'NUMBER' | 'ARRAY' | 'BOOLEAN' | 'STRING', CaporalValidator> = {
+    NUMBER: _program.NUMBER,
+    ARRAY: _program.ARRAY,
+    BOOLEAN: _program.BOOLEAN,
+    STRING: _program.STRING,
+};