Metadata-Version: 2.4
Name: apbase
Version: 0.1.1
Summary: High-performance automated pipeline for map creation -- the geospatial core for precision agriculture AI agents
Author-email: Leonardo Felipe Maldaner <leonardofm@alumni.usp.br>
License-Expression: Apache-2.0
Keywords: geospatial,kriging,idw,variogram,interpolation,fortran,co-kriging,cross-variogram
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: pyproj<4.0,>=3.6
Requires-Dist: shapely<3.0,>=2.0
Provides-Extra: smoketest
Requires-Dist: pyarrow<20.0.0,>=18.0.0; python_version < "3.14" and extra == "smoketest"
Requires-Dist: pyarrow<26.0.0,>=22.0.0; python_version >= "3.14" and extra == "smoketest"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: sphinx-intl>=2.2.0; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.6.2; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Requires-Dist: sphinx-design>=0.6.0; extra == "docs"
Dynamic: license-file

# APbase

[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](pyproject.toml)
[![Kernel: Fortran](https://img.shields.io/badge/kernel-Fortran-734f96.svg)](#performance)
[![Parallel: OpenMP](https://img.shields.io/badge/parallel-OpenMP-orange.svg)](#performance)

APbase is the high-performance geospatial core for precision agriculture maps.
It filters irregular field points, fits a variogram, validates IDW versus local
ordinary kriging, selects the lower-RMSE model, and returns compact map points.

Full documentation: https://apbase.io

Python package repository: https://github.com/ap-base/apbase-python

## Quick Use

```python
import numpy as np

import apbase
from apbase import Map

apbase.config["n_threads"] = 4

x = np.ascontiguousarray(x_metric, dtype=np.float64)
y = np.ascontiguousarray(y_metric, dtype=np.float64)
z = np.ascontiguousarray(values, dtype=np.float64)

result = Map(resolution=10.0)(x, y, z)

result.method                # "idw" or "kriging"
result.x, result.y, result.z # compact output points

X, Y, Z = result.to_raster() # dense raster, NaN outside the boundary
```

Functional shortcut:

```python
result = apbase.create_map(x, y, z, resolution=10.0)
```

## Main API

- `apbase.Map`: automated map pipeline.
- `apbase.create_map`: one-shot map creation.
- `apbase.config`: process configuration, including OpenMP threads.

Advanced modules are available under `apbase.filtering`, `apbase.grid`,
`apbase.variogram`, `apbase.idw`, `apbase.kriging`, `apbase.cokriging`, and
`apbase.cross_validate`.

## Data Requirements

- Use one-dimensional `x`, `y`, and `z` arrays.
- Prefer projected metric coordinates, such as UTM.
- `Map` also accepts lon/lat and converts internally before distance-based
  operations; in that case, distance settings such as `resolution` are meters.
- For speed, pass contiguous `float64` NumPy arrays.

## Performance

- Critical kernels run in native Fortran through F2PY, NumPy, and OpenMP.
- The pipeline uses local neighborhoods and neighbor limits instead of full
  distance matrices.
- Configure threads before creating maps:

```python
import apbase

apbase.config["n_threads"] = 4
```

For services:

```text
process_workers * APBASE_N_THREADS <= available_vCPU
```

## Install

Published package:

```bash
pip install apbase
```

Development export:

```bash
python tools/build_native_extensions.py
python tools/export_distribution.py ../apbase-python --force
```

Local editable install:

```bash
pip install -e .
```

## Documentation

The documentation source lives in `../apbase-docs` and is published at
https://apbase.io. Keep long examples, methodology, deployment notes, and API
reference there; keep this README short.
