Draft: v0.4.0 Release Notes

[sargunv]

WIP draft of release notes copied below:

Spatial K v0.4.0

This release represents a revival and overhaul of the library with adoption into the MapLibre org and significant breaking changes for better type safety, a more idiomatic Kotlin API, and improved Java interoperability.

Contributors

@sargunv @jgillich @westnordost @elcolto @CommanderStorm @dellisd @Fabi755

Special thanks to @dellisd for originally creating and maintaining Spatial K.

Overview

[!WARNING]
Nearly the entire public API surface has been revised with significant breaking changes from v0.3.0, so the breaking changes aren't called out explicitly in this list.

• New Maven coordinates from io.github.dellisd to org.maplibre
• Package restructuring from io.github.dellisd to org.maplibre
• Expanded Kotlin Multiplatform support including WASM targets and all native platforms
• Improvements to GeoJSON type safety with generics and union types
• GeoJSON DSL overhaul with builder-style API and Java-compatible builders
• New units module for type-safe measures and unit conversions
• Turf module API revised to be more Kotlin idiomatic with extension functions and new naming conventions and signatures.
• Additional Turf.js functions ported.

Changes

Maven Coordinates

The library has moved from io.github.dellisd to org.maplibre:

// Before (v0.3.0)
dependencies {
    implementation("io.github.dellisd.spatialk:geojson:0.3.0")
    implementation("io.github.dellisd.spatialk:turf:0.3.0")
}

// After (v0.4.0)
dependencies {
    implementation("org.maplibre.spatialk:geojson:0.4.0")
    implementation("org.maplibre.spatialk:turf:0.4.0")
    implementation("org.maplibre.spatialk:units:0.4.0")  // new module
}

Package Restructuring

All packages have been renamed from io.github.dellisd.spatialk to org.maplibre.spatialk:

// Before (v0.3.0)
import io.github.dellisd.spatialk.geojson.*
import io.github.dellisd.spatialk.turf.*

// After (v0.4.0)
import org.maplibre.spatialk.geojson.*
import org.maplibre.spatialk.turf.*

Additional Kotlin Multiplatform Support

Spatial K now supports all Kotlin Multiplatform targets:

JavaScript & WebAssembly:

• JavaScript (Browser and Node.js)
• WebAssembly/JS (Browser, Node.js, and D8)
• WebAssembly/WASI (Node.js)

Native Platforms:

• Tier 1: macOS (ARM64), iOS (ARM64 and Simulator ARM64)
• Tier 2: macOS (x64), iOS (x64), Linux (x64 and ARM64), watchOS (Simulator ARM64, x64, ARM32, and ARM64), tvOS (Simulator ARM64, x64, and ARM64)
• Tier 3: Windows (x64 via mingw), Android Native (ARM32, ARM64, x86, and x64), watchOS Device (ARM64)

GeoJSON DSL Overhaul

The GeoJSON DSL has been completely redesigned with a builder-style API (#253):

// Before (v0.3.0)
val feature = feature(
    geometry = lineString {
        +lngLat(0.0, 0.0)
        +lngLat(1.0, 1.0)
    }
) {
    put("name", "Example")
}

// After (v0.4.0)
val feature = buildFeature {
    geometry = lineStringOf(
        Position(0.0, 0.0),
        Position(1.0, 1.0),
    )
    properties = buildJsonObject {
        put("name", "Example")
    }
}

The underlying builders are now also usable in Java:

FeatureBuilder<LineString, JsonObject> builder = 
    new FeatureBuilder<>(
        new LineString(new Position(0.0, 0.0), new Position(1.0, 1.0)),
        null
    );
Feature<LineString, JsonObject> feature = builder.build();

Units System Replaced

The old Units enum has been replaced with a type-safe units module inspired by kotlin.time.Duration (#185):

// Before (v0.3.0)
val distance = distance(point1, point2, Units.KILOMETERS)

// After (v0.4.0)
val distance: Length = distance(point1, point2)
val km = distance.inKilometers

Length, Area, Rotation, and Bearing are Kotlin value classes, so they're not available in Java. Java users can use the convert helper from Utils to convert between units as double values:

double distanceKm = Utils.convert(
    Measurement.distance(point1, point2, Meters),
    Meters,
    Kilometers
);

Turf API Changes

• Many Turf functions are now extension functions
• Many Turf functions have been renamed to follow Kotlin naming conventions
• Input and output formats have been standardized to prefer the simplest type that serves the purpose of the function. In practice, this means most functions operate directly on Geometry, not Feature.
• Some new functions have been added to aid in conversions between GeoJSON types.
• Functions have been reorganized by package.

In Java, Turf functions are organized as static methods by package (e.g., Measurement.distance(), Transformation.circle()).

// Before (v0.3.0)
val center = Turf.center(featureCollection)
val bbox = Turf.bbox(geometry)

// After (v0.4.0)
val center = featureCollection.center()
val bbox = geometry.computeBbox()

New Turf Functions

Many new geospatial analysis functions have been ported from Turf.js:

Measurement:

• envelope - Calculate bounding envelope (#134)
• rhumbDistance - Calculate rhumb line distance (#148)

Transformation:

• circle - Generate circle polygons (#139)
• simplify - Simplify geometries (#149)

Feature Conversion:

• combine - Combine geometries (#242)
• explode - Explode features into points (#243)
• Conversion functions: lineToPolygon, polygonToLine (#254)

Miscellaneous:

• pointsWithinPolygon - Spatial join operations (#257)
• nearestPoint - Find nearest points (#256)
• lineSliceAlong - Slice LineStrings by distance (#255)

Generic Geometry Support

GeoJSON types GeometryCollection, FeatureCollection, and Feature are now generic on the type of geometry they contain. FeatureCollection and Feature are also generic on the type of their properties object.

For dynamically typed properties, use JsonObject?:

val feature = Feature.fromJson<Geometry?, JsonObject?>(json)

Full Changelog

For a complete list of changes, see: v0.3.0...v0.4.0

[sargunv]

TODO:

• double check the list of newly ported turf functions (I had an LLM generate the list from a git log)
• Also the before DSL, I wrote it from memory and I'm confident it's not right

[westnordost]

properties = buildJsonObject {
   put("name", "Example")

}

Is something like properties = mapOf("name" to "Example").toJsonObject() or similar possible? Because, most usage of properties will just use a Map<String, String>

[sargunv]

With #258, I think so yeah without .toJsonObject() even. Will include that case in the tests.

EDIT: Yup, confirmed, added to tests, and merged #258.

[sargunv]

Draft has been saved under releases. Milestone is wrapping up; release should be good to go soon after some final reviews and documentation updates.

[westnordost]

// After (v0.4.0)
val feature = buildFeature {
    geometry = lineStringOf(
        Point(0.0, 0.0),
        Point(1.0, 1.0),
    )
    properties = buildJsonObject {
        put("name", "Example")
    }
}

Shouldn't it be Positions?

[sargunv]

yup, fixed!