---
title: "Getting Started with XGeoRTR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with XGeoRTR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`XGeoRTR` is explainable geometry backend infrastructure for workflows that need
portable analytic state. It standardizes analytic outputs into `xgeo_state`
objects with:

- geometry
- attributes
- indices
- selection
- level-of-detail summaries
- selected backend tables
- metadata

Packages such as `shapViz3D`, `rTDA3D`, and renderer frontends consume this
backend state downstream. XGeoRTR does not include use-case presentation code or
front-end adapters.

## Create an `xgeo_state`

```{r}
library(XGeoRTR)

demo_path <- system.file("extdata", "spatial_demo.csv", package = "XGeoRTR")
demo_tbl <- utils::read.csv(demo_path, stringsAsFactors = FALSE)

state <- as_xgeo_state(
  demo_tbl,
  x_col = "x",
  y_col = "y",
  z_col = "z",
  value_col = "value",
  feature_col = "feature",
  method = "spatial-field-demo",
  meta = list(source = "synthetic-demo", sample_id = "grid-01")
)

state
summary(state)
```

## Compute backend state operators

```{r}
state <- compute_xgeo_embedding(state, method = "pca", source = "points", dims = 2)
state <- set_active_embedding(state, "pca_points")
state <- compute_xgeo_diagnostics(state, embedding = "pca_points", source = "points", k = 3)
state <- build_xgeo_lod(state, embedding = "pca_points", levels = c(8L, 16L), auto_threshold = 10L)
state <- set_xgeo_selection(state, point_ids = state$indices$point_ids[[1]])

summary(state)
```

## Access backend-neutral fields

```{r}
names(xgeo_geometry(state))
names(xgeo_attributes(state))
names(xgeo_indices(state))
xgeo_selection(state)
names(xgeo_metadata(state))
```

## Build selected backend tables

```{r}
long_tbl <- xgeo_explanation_table(state)
point_tbl <- xgeo_point_values(state)
grid <- xgeo_regular_grid(point_tbl)

utils::head(long_tbl)
utils::head(point_tbl)
names(grid)
```

Downstream use-case packages should consume these public tables rather than
internal ingestion objects.

## Downstream consumers

`shapViz3D` can consume explanation and point-value tables for Shapley-oriented
workflows. `rTDA3D` can consume point and grid summaries for topology-oriented
workflows. Renderer frontends such as `ggWebGL` can consume `xgeo_state` through
their own adapter contracts. Those packages own presentation, interaction, and
front-end behavior.

## Downstream use-case consumers

XGeoRTR stops at backend state and backend tables. It does not ship
use-case-specific presentation assets. SHAP semantics belong downstream in a
Shapley-oriented package, topology semantics belong downstream in a
topology-oriented package, and display orchestration belongs in renderer 
frontends such as `ggWebGL`.

The backend-only example below shows the intended downstream-consumption pattern:

```{r eval = FALSE}
source("inst/examples/downstream_shapviz3d_state_tables.R")
```

When the sibling `shapViz3D` repository is available, that example reads the
three deterministic evidence CSVs from `shapViz3D`, builds `xgeo_state`
objects, applies selection, computes optional embedding/diagnostic/LOD state,
and emits only backend tables. When the downstream repo is unavailable, it
falls back to the bundled `spatial_demo.csv` so the example still runs without
renderer or SHAP-package dependencies.

## Write and reload state

```{r}
json_file <- tempfile(fileext = ".json")
write_xgeo_state(state, json_file)
restored <- read_xgeo_state(json_file)

restored$attributes$embeddings$active
```

## Package boundary

`XGeoRTR` exposes backend state, derived tables, and serialized state exchange.
It does not expose scene/camera/viewport APIs or renderer-specific
orchestration.