GeometryUtils Directory Reference

Directories
	dart
	java
	kotlin
	objc
	swift

Detailed Description

This directory contains comprehensive examples demonstrating the usage of the Navigine SDK's GeometryUtils across all supported platforms.

Overview

The GeometryUtils provides a comprehensive set of geometric calculation functions for working with points, segments, polygons, and lines. It offers functionality for:

• Distance Calculations: Computing distances between points and global coordinates
• Segment Operations: Length calculations, intersections, and projections
• Polygon Analysis: Area calculations, center points, and point containment
• Line Processing: Multi-segment line operations and length calculations
• Geometric Transformations: Ratio calculations and coordinate projections

Key Components

GeometryUtils

The main utility class providing geometric calculation methods:

• distanceBetweenGlobalPoints() - Calculate distance between WGS84 coordinates
• distanceBetweenPoints() - Calculate distance between metric coordinates
• segmentLength() - Calculate segment length
• polygonArea() - Calculate polygon area
• polygonCenter() - Calculate polygon geometric center
• polygonContainsPoint() - Check if polygon contains a point
• segmentPointDistance() - Calculate distance from segment to point
• segmentIntersectsSegment() - Check if segments intersect
• segmentIntersectionSegment() - Calculate intersection point
• divisionRatioBySegment() - Calculate division ratio between segments
• getRatioPoint() - Get point at specific ratio on segment
• getProjectionRatio() - Calculate projection ratio of point on segment

Point

Represents a point in metric coordinates:

• x, y - Coordinates in meters

GlobalPoint

Represents a point in WGS84 coordinates:

• latitude, longitude - Geographic coordinates

Segment

Represents a line segment between two points:

• start, end - Start and end points

Polygon

Represents a polygon defined by a list of points:

• points - List of points forming the polygon boundary

Line

Represents a polyline composed of multiple segments:

• segments - List of segments forming the line

Platform-Specific Files

Dart/Flutter

• dart/geometry_utils_example.dart - Complete example with all GeometryUtils features

Java

• java/GeometryUtilsExample.java - Java implementation with comprehensive API coverage

Kotlin

• kotlin/GeometryUtilsExample.kt - Kotlin implementation using coroutines for async operations

Objective-C

• objc/GeometryUtilsExample.h - Header file with interface declarations
• objc/GeometryUtilsExample.m - Implementation with all GeometryUtils methods

Swift

• swift/GeometryUtilsExample.swift - Swift implementation with modern syntax

Key Documentation Tags

GeometryUtils Methods

• [platform_GeometryUtils_distanceBetweenGlobalPoints] - Distance between global coordinates
• [platform_GeometryUtils_distanceBetweenPoints] - Distance between metric points
• [platform_GeometryUtils_segmentLength] - Segment length calculation
• [platform_GeometryUtils_polygonArea] - Polygon area calculation
• [platform_GeometryUtils_polygonCenter] - Polygon center calculation
• [platform_GeometryUtils_polygonContainsPoint] - Point containment check
• [platform_GeometryUtils_segmentPointDistance] - Distance from segment to point
• [platform_GeometryUtils_segmentIntersectsSegment] - Segment intersection check
• [platform_GeometryUtils_segmentIntersectionSegment] - Intersection point calculation
• [platform_GeometryUtils_divisionRatioBySegment] - Division ratio calculation
• [platform_GeometryUtils_getRatioPoint] - Ratio point calculation
• [platform_GeometryUtils_getProjectionRatio] - Projection ratio calculation

Point Properties

• [platform_Point_constructor] - Creating points
• [platform_Point_getX] - Getting X coordinate
• [platform_Point_getY] - Getting Y coordinate

GlobalPoint Properties

• [platform_GlobalPoint_constructor] - Creating global points
• [platform_GlobalPoint_getLatitude] - Getting latitude
• [platform_GlobalPoint_getLongitude] - Getting longitude

Segment Properties

• [platform_Segment_constructor] - Creating segments
• [platform_Segment_getStart] - Getting start point
• [platform_Segment_getEnd] - Getting end point

Polygon Properties

• [platform_Polygon_constructor] - Creating polygons
• [platform_Polygon_getPoints] - Getting polygon points

Line Properties

• [platform_Line_constructor] - Creating lines
• [platform_Line_getSegments] - Getting line segments

Common Usage Patterns

1. Distance Calculations

// Calculate distance between metric points
Point point1 = Point(10.0, 20.0);
Point point2 = Point(30.0, 40.0);
double distance = GeometryUtils.distanceBetweenPoints(point1, point2);
 
// Calculate distance between global coordinates
GlobalPoint moscow = GlobalPoint(55.7558, 37.6176);
GlobalPoint london = GlobalPoint(51.5074, -0.1278);
double globalDistance = GeometryUtils.distanceBetweenGlobalPoints(moscow, london);

2. Segment Operations

// Create and analyze segments
Segment segment = Segment(Point(0.0, 0.0), Point(10.0, 10.0));
double length = GeometryUtils.segmentLength(segment);
 
// Check intersections
Segment segment2 = Segment(Point(0.0, 10.0), Point(10.0, 0.0));
bool intersects = GeometryUtils.segmentIntersectsSegment(segment, segment2);
Point intersection = GeometryUtils.segmentIntersectionSegment(segment, segment2);
 
// Calculate projections
Point testPoint = Point(5.0, 5.0);
double distanceToPoint = GeometryUtils.segmentPointDistance(segment, testPoint);
double projectionRatio = GeometryUtils.getProjectionRatio(segment, testPoint);
Point ratioPoint = GeometryUtils.getRatioPoint(segment, 0.5);

3. Polygon Analysis

// Create and analyze polygons
List<Point> polygonPoints = [
  Point(0.0, 0.0),
  Point(10.0, 0.0),
  Point(10.0, 10.0),
  Point(0.0, 10.0),
];
Polygon polygon = Polygon(polygonPoints);
 
double area = GeometryUtils.polygonArea(polygon);
Point center = GeometryUtils.polygonCenter(polygon);
 
// Check point containment
Point testPoint = Point(5.0, 5.0);
bool contains = GeometryUtils.polygonContainsPoint(polygon, testPoint);

4. Line Processing

// Create multi-segment lines
List<Segment> segments = [
  Segment(Point(0.0, 0.0), Point(10.0, 10.0)),
  Segment(Point(10.0, 10.0), Point(20.0, 5.0)),
  Segment(Point(20.0, 5.0), Point(30.0, 15.0)),
];
Line line = Line(segments);
 
// Calculate total length
double totalLength = 0.0;
for (Segment segment in line.segments) {
  totalLength += GeometryUtils.segmentLength(segment);
}

5. Advanced Geometric Operations

// Test various intersection scenarios
Segment parallel1 = Segment(Point(0.0, 0.0), Point(10.0, 0.0));
Segment parallel2 = Segment(Point(0.0, 5.0), Point(10.0, 5.0));
bool parallelIntersects = GeometryUtils.segmentIntersectsSegment(parallel1, parallel2);
 
// Test different polygon shapes
List<Point> triangle = [
  Point(0.0, 0.0),
  Point(10.0, 0.0),
  Point(5.0, 10.0),
];
Polygon trianglePolygon = Polygon(triangle);
double triangleArea = GeometryUtils.polygonArea(trianglePolygon);

Running Examples

Dart/Flutter

cd examples/GeometryUtils/dart
dart geometry_utils_example.dart

Java

cd examples/GeometryUtils/java
javac GeometryUtilsExample.java
java GeometryUtilsExample

Kotlin

cd examples/GeometryUtils/kotlin
kotlinc GeometryUtilsExample.kt -include-runtime -d GeometryUtilsExample.jar
java -jar GeometryUtilsExample.jar

Objective-C

cd examples/GeometryUtils/objc
clang -framework Foundation GeometryUtilsExample.m -o GeometryUtilsExample
./GeometryUtilsExample

Swift

cd examples/GeometryUtils/swift
swift GeometryUtilsExample.swift

Advanced Features

Distance Calculation Scenarios

The examples demonstrate various distance calculation scenarios:

// Test known distance values
Point origin = Point(0.0, 0.0);
Point pythagorean = Point(3.0, 4.0);  // Should be 5.0 distance
double distance = GeometryUtils.distanceBetweenPoints(origin, pythagorean);
 
// Test global coordinate distances
GlobalPoint moscow = GlobalPoint(55.7558, 37.6176);
GlobalPoint tokyo = GlobalPoint(35.6762, 139.6503);
double globalDistance = GeometryUtils.distanceBetweenGlobalPoints(moscow, tokyo);

Intersection Analysis

Comprehensive intersection testing:

// Parallel segments (should not intersect)
Segment parallel1 = Segment(Point(0.0, 0.0), Point(10.0, 0.0));
Segment parallel2 = Segment(Point(0.0, 5.0), Point(10.0, 5.0));
bool parallelIntersects = GeometryUtils.segmentIntersectsSegment(parallel1, parallel2);
 
// Perpendicular segments (should intersect)
Segment perpendicular1 = Segment(Point(0.0, 0.0), Point(10.0, 0.0));
Segment perpendicular2 = Segment(Point(5.0, -5.0), Point(5.0, 5.0));
bool perpendicularIntersects = GeometryUtils.segmentIntersectsSegment(perpendicular1, perpendicular2);

Polygon Shape Analysis

Testing different polygon shapes and properties:

// Regular square
List<Point> square = [
  Point(0.0, 0.0), Point(10.0, 0.0),
  Point(10.0, 10.0), Point(0.0, 10.0)
];
Polygon squarePolygon = Polygon(square);
double squareArea = GeometryUtils.polygonArea(squarePolygon);  // Should be 100.0
 
// Triangle
List<Point> triangle = [
  Point(0.0, 0.0), Point(10.0, 0.0), Point(5.0, 10.0)
];
Polygon trianglePolygon = Polygon(triangle);
double triangleArea = GeometryUtils.polygonArea(trianglePolygon);  // Should be 50.0

Projection and Ratio Calculations

Advanced geometric transformations:

Segment segment = Segment(Point(0.0, 0.0), Point(10.0, 10.0));
 
// Test different ratio points
List<double> ratios = [0.0, 0.25, 0.5, 0.75, 1.0];
for (double ratio in ratios) {
  Point ratioPoint = GeometryUtils.getRatioPoint(segment, ratio);
  print("Ratio $ratio: (${ratioPoint.x}, ${ratioPoint.y})");
}
 
// Test projection calculations
Point testPoint = Point(5.0, 5.0);
double projectionRatio = GeometryUtils.getProjectionRatio(segment, testPoint);
double distanceToPoint = GeometryUtils.segmentPointDistance(segment, testPoint);

Performance Considerations

Distance Calculations

• Global coordinate calculations are more computationally intensive
• Use metric coordinates when possible for better performance
• Consider caching frequently used distance calculations

Polygon Operations

• Area calculations scale with polygon complexity
• Point containment tests use ray casting algorithm
• Complex polygons may require optimization for real-time applications

Segment Operations

• Intersection calculations are efficient for most use cases
• Multiple segment operations can be batched for better performance
• Consider spatial indexing for large numbers of segments

Memory Usage

• Point and segment objects are lightweight
• Polygon memory usage scales with vertex count
• Line objects aggregate multiple segments efficiently

Notes

• All examples demonstrate the same functionality across platforms
• Coordinate systems use meters for metric coordinates
• Global coordinates use WGS84 standard (latitude/longitude)
• Polygon points should be ordered counter-clockwise for proper area calculation
• Segment intersections handle edge cases (parallel, overlapping, etc.)
• Distance calculations use Euclidean geometry for metric coordinates
• Global distance calculations use Haversine formula for spherical earth approximation
• All geometric operations are numerically stable and handle edge cases
• Performance varies with geometric complexity and coordinate system
• Memory usage is minimal for most geometric operations
• Error handling is built into the geometric calculations