Quickstart

Basic Usage

Simple Example

from sargeom.coordinates import Cartographic

# Create coordinate in Paris
paris = Cartographic(longitude=2.3522, latitude=48.8566, height=35.0)

# Convert to ECEF and back
paris_ecef = paris.to_ecef()
paris_geo = paris_ecef.to_cartographic()

Multiple Points

import numpy as np

# Multiple cities
cities = Cartographic(
    longitude=[2.3522, -0.1276, 139.6917],  # Paris, London, Tokyo
    latitude=[48.8566, 51.5074, 35.6895],
    height=[35.0, 11.0, 40.0]
)

# Convert all to ECEF
cities_ecef = cities.to_ecef()

Local Coordinate Systems

# Reference point (Paris)
ref = Cartographic(longitude=2.3522, latitude=48.8566, height=35.0)

# Target point (London)
london = Cartographic(longitude=-0.1276, latitude=51.5074, height=11.0)
london_ecef = london.to_ecef()

# Convert to local ENU relative to Paris
london_enu = london_ecef.to_enu(origin=ref)

Trajectories

from sargeom import Trajectory
import numpy as np

# Time vector
t = np.linspace(0, 60, 100)  # 60 seconds, 100 points

# Aircraft trajectory
trajectory_coords = Cartographic(
    longitude=2.0 + 0.01 * t,           # Moving east
    latitude=48.0 + 0.005 * t,          # Moving north
    height=1000 + 10 * np.sin(0.1 * t)  # Varying altitude
)

# Create trajectory
traj = Trajectory(
   timestamps=t,
   positions=trajectory_coords
)

Distance Calculations

from sargeom.coordinates import Cartesian3

# Two points
point1 = Cartographic(longitude=2.3522, latitude=48.8566, height=0)
point2 = Cartographic(longitude=-0.1276, latitude=51.5074, height=0)

# Convert to ECEF for distance calculation
p1_ecef = point1.to_ecef()
p2_ecef = point2.to_ecef()

# Euclidean distance
distance = Cartesian3.distance(p2_ecef, p1_ecef)
print(f"Distance: {distance/1000:.1f} km")

Advanced Usage

Large Dataset Processing

Efficient processing of large coordinate arrays:

# Generate large dataset
n_points = 100000

# Random coordinates
coords = Cartographic(
    longitude=np.random.uniform(-180, 180, n_points),
    latitude=np.random.uniform(-90, 90, n_points),
    height=np.random.uniform(0, 10000, n_points)
)

# Batch conversion (much faster than individual conversions)
ecef_coords = coords.to_ecef()

Working with Grids

# Create a grid of coordinates
lon_grid, lat_grid = np.meshgrid(
    np.linspace(2.0, 3.0, 10),   # Longitude range
    np.linspace(48.0, 49.0, 10)  # Latitude range
)

# Flatten for coordinate creation
grid_coords = Cartographic(
    longitude=lon_grid.flatten(),
    latitude=lat_grid.flatten(),
    height=np.zeros(100)  # on IAG GRS 80 ellipsoid
)

# Convert all points to ECEF at once
grid_ecef = grid_coords.to_ecef()

Utility Functions

from sargeom.coordinates.utils import negativePiToPi

# Wrap angles to [-π, π] range
angles = np.array([3*np.pi, -2*np.pi, np.pi/2])
wrapped = negativePiToPi(angles)

Next Steps

• Explore the Examples for more detailed use cases

• Check the API Reference for complete function documentation