Metadata-Version: 2.4
Name: sudapy
Version: 1.2.1
Summary: Sudan-focused Python toolkit for Geomatics: GIS, remote sensing, and surveying workflows.
Project-URL: Homepage, https://github.com/Osman-Geomatics93/sudapy
Project-URL: Documentation, https://osman-geomatics93.github.io/sudapy/
Project-URL: Repository, https://github.com/Osman-Geomatics93/sudapy
Project-URL: Issues, https://github.com/Osman-Geomatics93/sudapy/issues
Project-URL: Changelog, https://github.com/Osman-Geomatics93/sudapy/blob/main/CHANGELOG.md
Author-email: Osman Osama Ahmed Ibrahim <osmangeomatics93@gmail.com>
Maintainer-email: Osman Osama Ahmed Ibrahim <osmangeomatics93@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: geomatics,geospatial,gis,remote-sensing,sudan,surveying
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Requires-Dist: geographiclib<3,>=2.0
Requires-Dist: pandas<3,>=2.0
Requires-Dist: pyproj<4,>=3.6
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: rich<14,>=13.0
Requires-Dist: typer[all]<1,>=0.9
Provides-Extra: all
Requires-Dist: contextily<2,>=1.4; extra == 'all'
Requires-Dist: earthpy<1,>=0.9; extra == 'all'
Requires-Dist: fiona<2,>=1.9; extra == 'all'
Requires-Dist: folium<1,>=0.15; extra == 'all'
Requires-Dist: geopandas<2,>=0.14; extra == 'all'
Requires-Dist: matplotlib<4,>=3.7; extra == 'all'
Requires-Dist: numpy<3,>=1.24; extra == 'all'
Requires-Dist: rasterio<2,>=1.3; extra == 'all'
Requires-Dist: scipy<2,>=1.10; extra == 'all'
Requires-Dist: sentinelsat<2,>=1.2; extra == 'all'
Requires-Dist: shapely<3,>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.5; extra == 'dev'
Requires-Dist: pytest-cov<6,>=4.0; extra == 'dev'
Requires-Dist: pytest<9,>=7.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.3; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-gen-files<1,>=0.5; extra == 'docs'
Requires-Dist: mkdocs-literate-nav<1,>=0.6; extra == 'docs'
Requires-Dist: mkdocs-material<10,>=9.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]<1,>=0.24; extra == 'docs'
Provides-Extra: geo
Requires-Dist: fiona<2,>=1.9; extra == 'geo'
Requires-Dist: geopandas<2,>=0.14; extra == 'geo'
Requires-Dist: numpy<3,>=1.24; extra == 'geo'
Requires-Dist: rasterio<2,>=1.3; extra == 'geo'
Requires-Dist: scipy<2,>=1.10; extra == 'geo'
Requires-Dist: shapely<3,>=2.0; extra == 'geo'
Provides-Extra: rs
Requires-Dist: earthpy<1,>=0.9; extra == 'rs'
Requires-Dist: sentinelsat<2,>=1.2; extra == 'rs'
Provides-Extra: viz
Requires-Dist: contextily<2,>=1.4; extra == 'viz'
Requires-Dist: fiona<2,>=1.9; extra == 'viz'
Requires-Dist: folium<1,>=0.15; extra == 'viz'
Requires-Dist: geopandas<2,>=0.14; extra == 'viz'
Requires-Dist: matplotlib<4,>=3.7; extra == 'viz'
Requires-Dist: numpy<3,>=1.24; extra == 'viz'
Requires-Dist: rasterio<2,>=1.3; extra == 'viz'
Requires-Dist: scipy<2,>=1.10; extra == 'viz'
Requires-Dist: shapely<3,>=2.0; extra == 'viz'
Description-Content-Type: text/markdown

# SudaPy

**Sudan-focused Python toolkit for Geomatics** -- GIS, remote sensing, and surveying workflows that are fast, reliable, reproducible, and easy to install.

SudaPy is designed for Sudanese GIS professionals who need a single toolkit that works on Windows, handles common coordinate systems used in Sudan, and provides both a Python API and a friendly command-line interface.

## Features

- Built-in CRS presets for Sudan (WGS 84 UTM 34-37N, Adindan UTM 35-37N)
- Vector operations: reproject, clip, dissolve, area, buffer, simplify, fix-geometry
- Raster operations: clip, reproject, resample, mosaic, hillshade, slope
- Quick map export (PNG or interactive HTML)
- Project scaffolding (`sudapy init`), batch processing, and data reporting
- Environment diagnostics (`sudapy doctor`)
- Remote sensing helpers (Sentinel search/download) via optional extras
- Offline-friendly installation support
- Modern Python packaging with optional extras

## Installation

### Portable Windows Bundle (recommended for Windows)

Download the self-contained zip from the [latest release](https://github.com/Osman-Geomatics93/sudapy/releases/latest) -- no Python, pip, conda, or Visual Studio needed:

1. Download **SudaPy-Windows-x64.zip** (~600 MB)
2. Extract to `C:\SudaPy`
3. Run `scripts\sudapy_doctor.bat` to verify

See [INSTALL_WINDOWS.md](https://github.com/Osman-Geomatics93/sudapy/blob/main/INSTALL_WINDOWS.md) for all Windows installation options.

### From PyPI

```bash
# Core (CRS tools, CLI scaffolding, doctor) -- works everywhere, no GDAL needed
pip install sudapy

# Core + vector/raster operations (needs GDAL C libraries)
pip install "sudapy[geo]"

# Core + geo + visualization (matplotlib, folium, contextily)
pip install "sudapy[viz]"

# Everything (geo + viz + remote sensing)
pip install "sudapy[all]"
```

> **Windows note:** The `[geo]` extra requires GDAL C libraries. If `pip install "sudapy[geo]"` fails, use conda to install the geospatial stack first (see below). The core `pip install sudapy` always works.

### Using conda for geospatial dependencies (Windows)

```bash
conda create -n sudapy python=3.11
conda activate sudapy
conda install -c conda-forge geopandas rasterio fiona pyproj
pip install "sudapy[all]"
```

An `environment.yml` is included in the repository for a known-good conda environment:

```bash
conda env create -f environment.yml
conda activate sudapy
```

### Offline installation

See [Offline Installation Guide](https://github.com/Osman-Geomatics93/sudapy/blob/main/INSTALL_OFFLINE.md) for instructions on installing SudaPy without internet access.

## Quickstart

### 1. Check your environment

```bash
sudapy doctor
```

### 2. Find the right CRS for a location in Sudan

```bash
# What UTM zone covers Khartoum?
sudapy crs suggest --lon 32.5 --lat 15.6
```

### 3. Reproject a vector file

```bash
sudapy vector reproject --in data/regions.gpkg --out data/regions_utm.gpkg --to 32636
```

### 4. Calculate area

```bash
sudapy vector area --in data/parcels.gpkg --field area_m2 --out data/parcels_area.gpkg
```

### 5. Quick map

```bash
# Static PNG
sudapy map quick --in data/regions.gpkg --out map.png

# Interactive HTML
sudapy map quick --in data/regions.gpkg --out map.html
```

### 6. Scaffold a new project

```bash
sudapy init my_survey_project
```

### 7. Get a report on a dataset

```bash
sudapy report --in data/parcels.gpkg
```

## Python API

```python
from sudapy.crs.registry import suggest_utm_zone, list_presets
from sudapy.vector.ops import reproject, calculate_area, clip, dissolve, buffer, simplify

# Suggest CRS for a point
suggestions = suggest_utm_zone(lon=32.5, lat=15.6)

# Reproject a file
gdf = reproject("input.gpkg", to_epsg=32636, out="output.gpkg")

# Calculate area with automatic UTM projection
gdf = calculate_area("parcels.gpkg", field="area_m2", out="parcels_area.gpkg")

# Buffer with meters (auto-projects if CRS is geographic)
gdf = buffer("points.gpkg", distance_m=500, out="buffered.gpkg")
```

## Project Structure

```
src/sudapy/
    __init__.py
    core/
        logging.py      # Rich-based logging
        errors.py       # Custom exceptions with hints
    cli/
        main.py         # Typer CLI application
    crs/
        registry.py     # Sudan CRS presets and UTM suggestion
    vector/
        ops.py          # Vector geoprocessing
    raster/
        ops.py          # Raster geoprocessing
    viz/
        maps.py         # Quick map visualization
    rs/
        sentinel.py     # Sentinel satellite search & download
```

## Development

```bash
git clone https://github.com/Osman-Geomatics93/sudapy.git
cd sudapy
pip install -e ".[dev,all]"
pytest
ruff check src/ tests/
```

## Changelog

See [CHANGELOG.md](https://github.com/Osman-Geomatics93/sudapy/blob/main/CHANGELOG.md) for release history.

## License

MIT
