openeocraft.Rmd

---
title: "Introduction to OpenEOcraft"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to OpenEOcraft}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

OpenEOcraft implements an [openEO](https://openeo.org/)-style HTTP API in R (on top of [Plumber](https://www.rplumber.io/)): clients send JSON **process graphs**; the backend parses them, runs them in a controlled R context, and returns results (e.g. GeoTIFF). This vignette summarises how the R side is structured and shows a **minimal** runnable example that does **not** require optional heavy dependencies such as **sits** (the full ML backend uses `inst/ml/processes.R`; see the [README](https://github.com/Open-Earth-Monitor/openeocraft) for Docker and workflows).

## Layers

Roughly, the stack has three parts:

- **API** — openEO routes (`/processes`, `/jobs`, `/result`, …), auth, STAC-related wiring where enabled.
- **Core** — process graph parsing and translation to R expressions (see `?pgraph_expr`).
- **R engine** — execution in a sandboxed namespace; process functions are loaded from a processes source file via `load_processes()`.

## Declaring processes with `#* @openeo-process`

Processes are ordinary R functions in a `.R` file, marked with a Plumber-style comment block. At startup, `load_processes(api, path/to/processes.R)`:

1. Sources that file into an isolated evaluation environment.
2. Scans for `#* @openeo-process` chunks and registers each function on the API together with JSON from `dirname(processes.R)/processes/<id>.json`.

See `help("openeocraft_decorators", package = "openeocraft")`, `?load_processes`, and `help("openeo-process", package = "openeocraft")` for details.

Example (pattern only; the real ML file lives in the package as `inst/ml/processes.R` and needs **sits** and related packages):

```{r eval = FALSE}
#* @openeo-process
ndvi <- function(data, nir = "nir", red = "red", target_band = NULL) {
  ## implementation using your cube library (sits, stars, terra, gdalcubes, …)
}
```

## Minimal example: mock processes

The package ships a tiny mock module under `inst/mock/` with two processes (`load_collection`, `save_result`) and matching JSON. The following builds an openEO v1 API object and registers those processes—enough to illustrate the decorator pipeline without **sits**.

```{r minimal}
library(openeocraft)

work_dir <- tempfile("oc_vignette")
dir.create(work_dir)

api <- create_openeo_v1(
  id = "vignette-mock",
  title = "Vignette mock backend",
  description = "Minimal processes for documentation",
  backend_version = as.character(utils::packageVersion("openeocraft")),
  stac_api = "1.0.0",
  work_dir = work_dir,
  production = FALSE
)

mock_processes <- system.file("mock/mock-processes.R", package = "openeocraft")
stopifnot(nzchar(mock_processes))

api <- load_processes(api, mock_processes)
```

After `load_processes()`, the API object holds process metadata (under internal attributes) that the `/processes` handler uses. The mock file only returns placeholders; a production server sources `inst/ml/processes.R` instead (see `docker/server.R` and the README).

## Going further

- **Full stack (sits, torch, …):** use the Docker image or local install described in the README; run `Rscript docker/server.R` from the repository root so `inst/ml/processes.R` is found.
- **Adding processes:** edit or extend the processes `.R` file and add or adjust JSON under the adjacent `processes/` directory (`DEVELOPMENT.md`).
- **Mixing R packages:** different processes can call different libraries (e.g. **terra** for rasters, **tidymodels** or **torch** for ML) as long as inputs/outputs match your job pipeline and openEO parameter contracts.

```{r cleanup, include = FALSE}
unlink(work_dir, recursive = TRUE)
```