sudapy 1.2.0

Sudan-focused Python toolkit for Geomatics: GIS, remote sensing, and surveying workflows.

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 -- 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 for all Windows installation options.

From PyPI

# 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)

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:

conda env create -f environment.yml
conda activate sudapy

Offline installation

See Offline Installation Guide for instructions on installing SudaPy without internet access.

Quickstart

1. Check your environment

sudapy doctor

2. Find the right CRS for a location in Sudan

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

3. Reproject a vector file

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

4. Calculate area

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

5. Quick map

# 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

sudapy init my_survey_project

7. Get a report on a dataset

sudapy report --in data/parcels.gpkg

Python API

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

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 for release history.

License

MIT