WorldWind Kotlin 3D Virtual Globe API

The worldwind-formats-gltf-ktx2 module provides the KHR_texture_basisu (KTX2 / Basis-Universal) texture decoder for the WorldWind glTF and 3D Tiles pipeline. It supports multiple platforms:

• JVM: Uses native libktx via JNI.
• Android: Uses native libktx via JNI through assets/.
• iOS: Uses Kotlin/Native cinterop (requires opt-in build flag).
• Web (Kotlin/JS/Wasm): Uses THREE.js's bundled basis_transcoder WASM via npm.

Bundle Size Note (Web): Even though the three package is a dependency, Webpack tree-shakes it. Only basis_transcoder.js and basis_transcoder.wasm (~250 KiB total) are included in the bundle; the full THREE.js rendering engine is not included.

The worldwind-formats-gltf-draco module provides a Draco decoder for WorldWind's glTF and 3D Tiles pipeline. It enables the decoding of compressed meshes and point clouds across multiple platforms via the installDracoDecoder() API.

Platform Support:

• JVM: Uses native libdraco_bridge via JNI.
• Android: Uses native libdraco_bridge via JNI (loaded from assets/).
• iOS: Uses Kotlin/Native cinterop.
• Web (Kotlin/JS/Wasm): Uses the npm draco3d package with draco_decoder.wasm.

The moko-resources library uses lazy lookup via NSBundle.loadableBundle(...). If a required bundle is missing, the app will crash at launch with a kotlin.IllegalArgumentException.

To prevent this, you must provide empty stub bundles for every moko module used. For this project, ensure the following directories (containing an Info.plist with matching CFBundleIdentifier) are included in Build Phases → Copy Bundle Resources:

• MokoStubBundles/earth.worldwind.main.bundle/
• MokoStubBundles/earth.worldwind.assets.main.bundle/
• MokoStubBundles/earth.worldwind.tutorials.main.bundle/

Note: Because the framework is static, these bundles are not automatically copied into the .app and must be manually added to the app target.

The ProjectedMediaSurface uses two distinct internal methods to project media onto terrain:

1. 2D-homography path (Default):

   • Triggered when imageProjection = null.
   • Uses a mat3 ground-to-image homography built from four ground-corner KLV tags.
   • Performs a per-fragment mat3 * vec3 calculation to determine image UVs.
   • Pros/Cons: Computationally cheap and exact on flat surfaces, but slightly inaccurate on significant terrain relief.

2. 3D camera-frustum path (Opt-in):

   • Triggered when imageProjection = matrix4 is set.
   • Uses a per-fragment mat4 * vec4(world_position, 1) projection followed by an xy / w divide for image UVs.
   • Pros/Cons: Mathematically exact regardless of terrain relief. Note: This path is currently broken on JS/WebGL.

Default assets such as background imagery, night-time city lights, the star catalogue, and the EGM96 geoid grid are provided via the earth.worldwind:worldwind-assets artifact.

Key details:

• Automatic Resolution: The engine depends on this artifact, so it is resolved automatically. Layers like BackgroundLayer(), StarFieldLayer(), and AtmosphereLayer() work out-of-the-box without extra setup.
• Version Independence: The assets artifact has its own versioning scheme that does not track the engine version.
• Manual Pinning: You can pin a specific asset revision if required by explicitly declaring the dependency:

implementation 'earth.worldwind:worldwind-assets:1.0.0'

To build the CodeMirror project from source, you need Node.js (version 6 or higher) installed.

1. Install dependencies: npm install
2. Run the project: Open index.html directly in your browser (no webserver required).
3. Run tests: Use npm test.

The ProjectedMediaSurface.imageProjection feature (3D camera-frustum projection for draping video onto terrain) is currently broken on JS/WebGL. While it works correctly on JVM and Android, on JS it renders as a tiny, incorrect patch.

Recommended Workaround for JS Users: Do not attempt to use the 3D projection path on JS. Instead, leave imageProjection = null to fall back to the 2D-homography path. This path uses a mat3 ground-to-image homography derived from KLV tags and is mathematically exact on flat ground and sufficient for most use cases on relief.

// On JS, use the default 2D-homography path
projectedMediaSurface.imageProjection = null

To use WorldWind Kotlin in your project, add mavenCentral() to your repositories and include the earth.worldwind:worldwind dependency in your Gradle configuration. The worldwind-assets artifact is included automatically as a transitive dependency, providing default imagery and terrain data.

repositories {
    mavenCentral()
}

dependencies {
    implementation 'earth.worldwind:worldwind:2.1.0'
}

To enable KTX2/Basis-Universal texture decoding on iOS via Kotlin/Native cinterop, you must opt-in during the build process by setting the following Gradle property:

-Pworldwind.ktx2.buildIosNative=true

To access the latest development builds containing the newest features and bug fixes, add the Sonatype Maven snapshots repository and use a dynamic version for the dependency.

repositories {
    maven("https://central.sonatype.com/repository/maven-snapshots/")
}

dependencies {
    implementation 'earth.worldwind:worldwind:+'
}