Skip to content

Add opt-in Zstd supercompression for UASTC KTX2 - #103

Merged
HeDo88TH merged 2 commits into
OpenDroneMap:masterfrom
Xananthium:feat/ktx2-uastc-zstd
Jul 30, 2026
Merged

Add opt-in Zstd supercompression for UASTC KTX2#103
HeDo88TH merged 2 commits into
OpenDroneMap:masterfrom
Xananthium:feat/ktx2-uastc-zstd

Conversation

@Xananthium

Copy link
Copy Markdown
Contributor

Summary

  • add opt-in --ktx2-zstd-level 1-22 for UASTC KTX2 output
  • keep 0 as the default, preserving the existing output path
  • call the existing libktx ktxTexture2_DeflateZstd API after ktxTexture2_CompressBasisEx
  • reject out-of-range levels, non-KTX output, and ETC1S/BasisLZ combinations
  • document the UASTC-only constraint and memory caution for levels above 20

The range and ETC1S restriction follow the official KTX tools contract. This PR is independent of #102 and does not include its thread-count CLI change.

Validation

  • dotnet test Obj2Tiles.sln --configuration Release --verbosity minimal
    • Obj2Tiles.Library.Test: 135 passed
    • Obj2Tiles.Test: 87 passed
  • focused option contract: 7 passed
  • real native conversion using the vendored Windows x64 libktx v4.4.2: exit 0, tileset.json and two B3DM outputs
  • vendored ktx.dll is byte-identical to the official v4.4.2 release DLL
  • all 12 embedded KTX2 images report supercompressionScheme = 2 (Zstd)
  • official Khronos ktx v4.4.2, for every embedded image:
    • validate --warnings-as-errors --gltf-basisu: passed
    • transcode --target rgba8: passed
    • validation of transcoded KTX2: passed

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds an opt-in CLI option to apply Zstandard supercompression to UASTC KTX2 texture output, wiring the setting from the CLI through GltfConverterOptions into the libktx encoding path, and documenting the constraint/usage in the README.

Changes:

  • Add --ktx2-zstd-level 0|1-22 option (default 0 disabled) and validate it in CLI option checks.
  • Plumb the option into GltfConverterOptions and invoke ktxTexture2_DeflateZstd after ktxTexture2_CompressBasisEx when enabled.
  • Add focused option-contract tests and documentation updates for the UASTC-only Zstd constraint.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
README.md Documents the new --ktx2-zstd-level option, constraints, and an example invocation.
Obj2Tiles/Program.cs Validates --ktx2-zstd-level constraints and passes the value into GltfConverterOptions for tiling.
Obj2Tiles/Options.cs Adds the new CLI option definition and help text.
Obj2Tiles.Test/Ktx2ZstdOptionsTests.cs Adds tests covering parsing and validation rules for the new option.
Obj2Gltf/Ktx2/Ktx2Encoder.cs Adds P/Invoke for ktxTexture2_DeflateZstd and applies it conditionally for UASTC KTX2 output.
Obj2Gltf/GltfConverterOptions.cs Adds Ktx2ZstdLevel to carry the setting from CLI into the encoder.

Comment thread Obj2Gltf/Ktx2/Ktx2Encoder.cs
Comment thread Obj2Tiles.Test/Ktx2ZstdOptionsTests.cs
# Conflicts:
#	Obj2Tiles/Options.cs
#	Obj2Tiles/Program.cs
#	README.md
@HeDo88TH HeDo88TH self-assigned this Jul 30, 2026
@HeDo88TH HeDo88TH added the enhancement New feature or request label Jul 30, 2026
@HeDo88TH
HeDo88TH merged commit 89c5cc5 into OpenDroneMap:master Jul 30, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants