Metadata-Version: 2.4
Name: field_coverage
Version: 0.1.1
Summary: Pathfinding for autonomous robots
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pathfinding
Requires-Dist: numpy
Requires-Dist: ortools
Requires-Dist: matplotlib
Requires-Dist: networkx>=3.6.1
Requires-Dist: requests
Requires-Dist: shapely
Requires-Dist: pydantic
Requires-Dist: pandas
Requires-Dist: pyarrow
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"

# Damage-Aware Coverage Path Planning

A Python library for damage-aware coverage path planning (DACPP) in rectilinear environments, with a focus on agricultural fields. Produces coverage paths that jointly minimise tile revisits and turns — both of which contribute to soil compaction in agricultural applications.

This library is the reference implementation for the paper *"Damage-Aware Coverage Path Planning as a Generalised Travelling Salesperson"* (Cutteridge, Frenkel, and Mansouri).

---

## Overview

Classical coverage path planning minimises path length or completion time, treating revisits as an incidental side effect. In applications such as agricultural seeding, however, revisits are actively harmful: each additional pass crushes seedlings and compacts the soil. This library formalises coverage as an optimisation problem that explicitly penalises revisits and turns, and solves it as a Generalised Travelling Salesperson Problem (GTSP).

The solver has three stages:

1. **Setup** — the field is decomposed into rectilinear regions (via Fields2Cover), and up to eight boustrophedon sweep patterns are generated for each region.
2. **Ant Colony Optimisation (ACO)** — a parallel ACO solver finds a high-quality visiting order over the sweep patterns, formulated as a GTSP.
3. **Simulated Annealing (SA)** — a refinement stage with a novel *absorption* operator, which removes revisits by reassigning shared tiles from connector paths into adjacent regions.

Evaluated on 200 real UK field geometries from the Sentinel-2 dataset, the algorithm achieves an average revisit rate of 4.2% and 33 turns per 100 tiles.

---

## Repository Structure

| Directory | Contents |
|---|---|
| `field_coverage/` | Core library (GTSP construction, ACO, SA, absorption operator) |
| `docs/` | Architecture diagrams and flowcharts |
| `results/` | Experimental data, CSV outputs, and figures from the paper |
| `data/` | GeoJSON field geometries |

> **Note:** This repository contains the backend library only. The AuTo-mato web interface used to produce Fig. 7 of the paper is not yet public.

---

## Setup

> This Docker image has been tested on ARM CPUs only; results on other architectures may differ.

### 1. Build the Fields2Cover container

From the root of `field_coverage/`:
```bash
docker build -f decomp/dockerfile -t fields2cover-api:v3 --platform linux/arm64 .
docker run -d -p 8000:8000 --platform linux/arm64 fields2cover-api:v3
```

### 2. Install the Python package

Install [uv](https://github.com/astral-sh/uv), then:
```bash
uv pip install -e .
```
If `field_coverage` is not installed automatically:
```bash
uv pip install field_coverage
```

### 3. Start the backend API

```bash
uvicorn coverage_api:app --reload --port 8000
```

## Tests

```bash
pytest
```
