Geographic topic

This module provides a compact set of value objects and spatial primitives for working with geographic locations, bounding areas, and route geometry in WGS‑84 coordinates. Use these classes to represent points on the globe, define search or geofence boundaries, compute containment and centroids, and manipulate linear path data. Key concepts include coordinate precision, axis-aligned bounding rectangles, polygonal and circular area representations, and tile-based coverage for complex regions.

• Coordinates: Represents a position in WGS‑84 (latitude, longitude and optional altitude). Use this value object wherever a geographic point is required; it supports distance and azimuth calculations, validation and cloning.
• GeographicArea: Abstract base that defines common spatial operations such as containment testing, bounding-box calculation, center point access and conversion between area types. Implementations provide concrete algorithms for area math - see CircleGeographicArea, RectangleGeographicArea, PolygonGeographicArea, and TilesCollectionGeographicArea for details.
• CircleGeographicArea: Circular region defined by a center Coordinates and a radius in meters. Ideal for proximity checks and simple geofencing; provides bounding-box computation and conversion support.
• RectangleGeographicArea: Axis-aligned rectangle defined by top-left and bottom-right Coordinates. Use it for bounding boxes, search areas, and map viewport calculations; includes intersection, union, containment, and construction helpers. Is always aligned to latitude/longitude axes.
• PolygonGeographicArea: Arbitrary polygon defined by an ordered list of Coordinates vertices. Use polygons for precise administrative or irregular area shapes, centroid computation, and point-in-polygon containment tests.
• TilesCollectionGeographicArea: Area represented as a collection of map tiles.
• Path: An ordered sequence of Coordinates representing a linear geometry; supports creation from raw coordinates or binary files, cloning, export to multiple formats, and converting to a landmark list for routing.
• PathMatch: Lightweight result model representing the outcome of a hit-test against a path collection (includes the matched path index, the matched coordinates, distance and segment index).

The geographic components work together to provide a consistent spatial model: Coordinates are the core data unit, area types wrap coordinates into meaningful spatial extents, and Path objects model linear geometry used by routing and map display. Together they enable accurate containment checks, bounding-box calculations, centroid computations and conversions between area representations which simplifies search, routing, and geofencing workflows.

Use Coordinates as the canonical representation of points, then choose the area type that best matches your use case: RectangleGeographicArea for simple bounds and search hints, CircleGeographicArea for proximity filters and radius-based geofencing, PolygonGeographicArea for precise irregular boundaries. These models are used throughout the SDK to define search areas, geofences, and other geographical indicators.

Learn more about geographic base entities: https://developer.magiclane.com/docs/flutter/guides/core/base-entities