GeoPointInterface

GeoPointInterface represents a geographic coordinate with latitude, longitude, and optional altitude.

Interface and Implementation

GeoPointInterface Interface

The GeoPointInterface interface has the following properties. It is used for unit testing and other purposes.

interface GeoPointInterface {
    val latitude: Double
    val longitude: Double
    val altitude: Double?
}

GeoPoint

The GeoPoint class is an implementation of the GeoPointInterface interface.

data class GeoPoint(
    override val latitude: Double,
    override val longitude: Double,
    override val altitude: Double = 0.0
) : GeoPointInterface

Creation Methods

Factory Methods

The GeoPoint class provides the following factory methods. Developers can choose the method that is most convenient for them.

// Specify values in latitude, longitude order
GeoPoint.fromLatLong(37.7749, -122.4194)

// Specify values in longitude, latitude order
GeoPoint.fromLongLat(-122.4194, 37.7749)

// Create from an object with GeoPointInterface interface
GeoPoint.from(existingGeoPoint)

// Create by passing values directly to constructor
GeoPoint(latitude = 37.7749, longitude = -122.4194, altitude = 100)

Usage Examples

// Basic marker placement
val sanFrancisco = GeoPoint.fromLatLong(37.7749, -122.4194)

// Replace MapViewContainer with GoogleMapView, MapboxMapView, or other map SDK of your choice
MapViewContainer(state = mapViewState) {
    Marker(
        position = sanFrancisco,
        icon = DefaultIcon(label = "SF")
    )
}

Coordinate System

Latitude

• Range: -90.0 to 90.0 degrees
• -90.0: South Pole
• 0.0: Equator
• 90.0: North Pole

Longitude

• Range: -180.0 to 180.0 degrees
• -180.0: International Date Line (west side)
• 0.0: Prime Meridian (Greenwich)
• 180.0: International Date Line (east side)

Validation and Normalization

Validation

The isValid() extension function checks if the coordinates of a GeoPointInterface are within valid ranges.

• Latitude: Within the range -90.0 to 90.0
• Longitude: Within the range -180.0 to 180.0

Returns true when both conditions are met.

// Usage example
val point = GeoPoint.fromLatLong(37.7749, -122.4194)
if (point.isValid()) {
    // Use the point
}

Normalization

Two methods are available to keep coordinates within valid ranges.

normalize()

The normalize() extension function clamps coordinates to valid ranges.

• Latitude: Clamped to -90.0 to 90.0
• Longitude: Normalized to -180.0 to 180.0 (modulo operation)
• Altitude: Converted to 0.0 if null

fun GeoPointInterface.normalize(): GeoPoint

// Usage example
val invalidPoint = GeoPoint.fromLatLong(100, 200) // Invalid coordinates
val validPoint = invalidPoint.normalize() // Clamped to valid range

wrap()

The wrap() method properly wraps coordinates that cross the poles.

• When latitude exceeds 90 degrees: Wraps from -90 degrees, flips longitude by 180 degrees
• When latitude falls below -90 degrees: Wraps from 90 degrees, flips longitude by 180 degrees
• Longitude: Normalized to -180.0 to 180.0

// Example: Coordinates beyond poles
val point = GeoPoint(95, 10) // Latitude exceeds 90 degrees
val wrapped = point.wrap() // 緯度: -85.0, 経度: 190.0 → -170.0

The difference between normalize() and wrap() is how they handle pole crossing. normalize() simply clamps values, while wrap() calculates the actual coordinates as if crossing the poles on a globe.

Comparison

equals()

The equals() method of GeoPoint performs comparison considering floating-point errors.

• Tolerance: 1e-7 (approximately 0.00000001 degrees, about 1.1cm)
• Comparison targets: Latitude, longitude, and altitude

val point1 = GeoPoint(37.7749, -122.4194, 100)
val point2 = GeoPoint(37.77490001, -122.41940001, 100.00000001)
val isEqual = point1 == point2 // true（within tolerance）

This tolerance allows comparisons to ignore tiny differences from floating-point arithmetic.

Utility Methods

toUrlValue()

The toUrlValue() method converts latitude and longitude to a URL string.

• Format: "latitude,longitude"
• Precision: Default is 6 digits (approximately 11cm), customizable

val point = GeoPoint(37.7749, -122.4194)
val urlValue = point.toUrlValue() // "37.774900,-122.419400" - Default precision (6 digits)
val urlValue3 = point.toUrlValue(precision = 3) // "37.775,-122.419" - Custom precision (3 digits)

Can be used for URL parameters in mapping services like Google Maps or Mapbox.