Metadata-Version: 2.2
Name: localcartesian
Version: 0.1.0
Summary: Fast GPS to local Cartesian coordinate conversion using GeographicLib
Keywords: gps,coordinates,cartesian,geographic,geospatial
Author-Email: Daniel Pastor <danpasmor@gmail.com>, Cevat Ustun <custun@beyond.ai>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: cibuildwheel; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: numpy; extra == "test"
Description-Content-Type: text/markdown

# LocalCartesian

Fast GPS to local Cartesian coordinate conversion using GeographicLib.

## Description

This package provides efficient conversion between GPS coordinates (latitude, longitude) and local Cartesian coordinates (x, y). It uses the GeographicLib C++ library through Python bindings created with pybind11.

The package exists because GeographicLib's Python bindings don't include the equivalent of the C++ `LocalCartesian` class, which is essential for many geospatial applications.

## Installation

### System Dependencies

Before installing, you need to have GeographicLib installed on your system:

**Ubuntu/Debian:**
```bash
sudo apt-get install libgeographic-dev
```

**macOS (with Homebrew):**
```bash
brew install geographiclib
```

### Python Package

Install from PyPI:
```bash
pip install localcartesian
```

Or install from source:
```bash
git clone <repository-url>
cd localcartesian
pip install .
```

## Usage

```python
import numpy as np
from localcartesian import gps2xy, xy2gps

# Define some GPS coordinates (lat, lon pairs)
gps_coords = [
    [40.7128, -74.0060],  # New York City
    [40.7589, -73.9851],  # Times Square
    [40.6892, -74.0445],  # Statue of Liberty
]

# Define origin point (lat, lon, altitude)
origin = [40.7128, -74.0060, 0.0]  # NYC as origin

# Convert GPS to local Cartesian coordinates
local_coords = gps2xy(gps_coords, origin)
print("Local coordinates:", local_coords)

# Convert back to GPS coordinates
gps_back = xy2gps(local_coords, origin)
print("GPS coordinates:", gps_back)
```

## API Reference

### `gps2xy(latlon, origin_latlonalt)`

Convert GPS coordinates to local Cartesian coordinates.

**Parameters:**
- `latlon`: List of [latitude, longitude] pairs
- `origin_latlonalt`: Origin point as [latitude, longitude, altitude]

**Returns:**
- List of [x, y] coordinate pairs in meters

### `xy2gps(xy, origin_latlonalt)`

Convert local Cartesian coordinates to GPS coordinates.

**Parameters:**
- `xy`: List of [x, y] coordinate pairs in meters
- `origin_latlonalt`: Origin point as [latitude, longitude, altitude]

**Returns:**
- List of [latitude, longitude] pairs

## Development

### Building from Source

Requirements:
- C++11 compatible compiler
- GeographicLib development headers
- pybind11
- Python development headers

```bash
# Install build dependencies
pip install pybind11 setuptools wheel

# Build and install
pip install .

# For development installation
pip install -e .
```

### Running Tests

```bash
pip install pytest
pytest tests/
```

## License

This project is licensed under the MIT License.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.