# ptgeo-service

**Repository Path**: lyxstart/ptgeo-service

## Basic Information

- **Project Name**: ptgeo-service
- **Description**: 基于 uv 和 FastAPI 的遥感数据处理服务。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PTGeo Service

PTGeo Service is the standalone geospatial and remote-sensing processing engine for GeoAtlas. It accepts short-lived input URLs or local development files, runs raster/vector analysis and model inference, and returns asynchronous job results.

## Responsibilities

PTGeo owns:

- Raster and vector processing
- NDVI and other remote-sensing indices
- GeoAI pipelines and pretrained model inference
- Raster/vector input processing and artifact generation
- In-process asynchronous jobs and SSE progress
- API Key authentication

GeoAtlas owns satellite search/download, data catalogues, permissions, Redis, MinIO and dashboard presentation. PTGeo does not require PostgreSQL, Redis or MinIO to start.

## Requirements

- Python 3.12+
- `uv`
- GDAL/PROJ/GEOS runtime libraries for local geospatial processing
- Optional model weights under `models/`

## Local Development

```powershell
uv sync --dev
$env:PTGEO_API_KEYS = "ptgeo-dev-key"
uv run dev
```

The service is available at `http://localhost:8000`. OpenAPI is available at `/docs` and the health endpoint is `/health`.

Every `/api/v1/**` request should include:

```http
X-PTGeo-API-Key: ptgeo-dev-key
```

## Standalone Docker

Build and run only the PTGeo image:

```powershell
docker build -t ptgeo-service:latest .
docker run --rm -p 8000:8000 `
  -e PTGEO_API_KEYS=replace-with-a-service-key `
  -v ${PWD}/models:/app/models `
  -v ${PWD}/outputs:/app/outputs `
  -v ${PWD}/uploads:/app/uploads `
  ptgeo-service:latest
```

The image does not start PostgreSQL, Redis or MinIO. GeoAtlas supplies signed input URLs and stores the resulting artefacts.

## Integration Flow

1. GeoAtlas searches and downloads satellite data.
2. GeoAtlas uploads source data to object storage and creates a short-lived URL.
3. GeoAtlas calls a model endpoint such as `POST /api/v1/geoai/pipelines/ship_detection` or `POST /api/v1/indices/jobs`.
4. PTGeo returns a job ID and processes the input asynchronously.
5. GeoAtlas reads `GET /api/v1/jobs/{job_id}`, stores successful outputs and publishes them to the dashboard.

See [`docs/INTEGRATION_CONTRACT.md`](docs/INTEGRATION_CONTRACT.md) and [`docs/MODULES.md`](docs/MODULES.md) for the current API contract.

## Tests

```powershell
uv run pytest -q
uv run python -m compileall -q src tests
```

The repository intentionally keeps local datasets, model weights and generated outputs outside the source package. Deployment images exclude these directories by default; mount or provision the required weights separately.