---
title: "Real-Data Evidence"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Real-Data Evidence}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
ggwebgl_truthy <- function(x) {
  tolower(x) %in% c("1", "true", "yes", "y")
}

ggwebgl_ci_vars <- c(
  "CI",
  "GITHUB_ACTIONS",
  "GITLAB_CI",
  "BUILDKITE",
  "TRAVIS",
  "APPVEYOR",
  "CIRCLECI",
  "JENKINS_URL"
)
ggwebgl_is_ci <- any(vapply(Sys.getenv(ggwebgl_ci_vars), ggwebgl_truthy, logical(1)))
ggwebgl_is_check <- nzchar(Sys.getenv("_R_CHECK_PACKAGE_NAME_"))
ggwebgl_eval_code <- !ggwebgl_is_ci &&
  !ggwebgl_is_check &&
  (
    ggwebgl_truthy(Sys.getenv("NOT_CRAN")) ||
      ggwebgl_truthy(Sys.getenv("GGWEBGL_EVAL_COVERAGE_VIGNETTE"))
  )
ggwebgl_eval_widgets <- ggwebgl_eval_code &&
  ggwebgl_truthy(Sys.getenv("GGWEBGL_EVAL_LIVE_WIDGETS"))

knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = ggwebgl_eval_code)
library(ggWebGL)
helper_path <- system.file("examples", "real", "real-data-helpers.R", package = "ggWebGL")
source(helper_path, local = knitr::knit_global())
real_examples <- if (ggwebgl_eval_code) real_data_plots() else NULL
real_info <- real_data_metadata()
```

# Real-Data Lens

This vignette complements the synthetic showcase with real offline datasets that
exercise the renderer on:

- a raster scalar field
- observed storm trajectories
- a dense 10,000-point projection
- fixed-scale faceted dense point panels

The goal is evidence rather than maximal detail. Every example is built from
packaged data that is available without network access.

Code examples are shown by default. Live WebGL widgets are disabled during
CRAN, package checks, and CI. Rich local or pkgdown rendering requires
`GGWEBGL_EVAL_COVERAGE_VIGNETTE=true` and
`GGWEBGL_EVAL_LIVE_WIDGETS=true`.

For network-enabled environments, `inst/scripts/download_mnist_embedding.R`
provides an optional path to a larger MNIST-style embedding export. The
packaged vignette keeps the offline dense embedding so the article builds
reliably everywhere.

# Example 1: Topographic Raster Field

**Why this example matters.** This is the raster path on a real elevation grid.
It exists to demonstrate that `geom_raster_webgl()` is now a rendered raster
field, not only an exported placeholder.

**What to inspect.** Terrain structure should remain continuous during pan and
zoom, and interpolation should avoid visible block artifacts in the default
example.

```{r volcano-dem, out.width='100%'}
real_examples$volcano_dem
```

```{r volcano-demgl, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$volcano_dem+theme_webgl(shader = "default"), height = 620)
```

```{r volcano-demgl2, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$volcano_dem, height = 620)
```

# Example 2: Observed Storm Trajectories

**Why this example matters.** This is the real trajectory case. It demonstrates
the package on geographic path bundles with real timestamps, wind speeds, and
pressure measurements behind the rendered lines.

**What to inspect.** Age shading and endpoint emphasis should make direction and
final position legible across multiple storms.

```{r storm-tracks, out.width='100%'}
real_examples$storm_tracks
```

```{r storm-tracksgl, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$storm_tracks+theme_webgl(shader = "default"), height = 620)
```

```{r storm-tracksgl2, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$storm_tracks, height = 620)
```

# Example 3: Dense Real-World Embedding

**Why this example matters.** This is the dense point-cloud case using a real
10,000-point feature projection. It tests whether the point renderer remains
legible on a real dense distribution instead of only on synthetic blobs.

**What to inspect.** Look for high-density accumulation without collapse into an
undifferentiated cloud.

```{r dense-embedding, out.width='100%'}
real_examples$dense_embedding
```

```{r dense-embeddinggl, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$dense_embedding+theme_webgl(shader = "default"), height = 620)
```

```{r dense-embeddinggl2, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$dense_embedding, height = 620)
```

# Example 4: Fixed-Scale Faceted Panels

**Why this example matters.** This is the facet-support case. It exercises the
new multi-panel layout on dense real point data.

**What to inspect.** Each panel should clip correctly, preserve its own
interaction state, and remain comparable because scales stay fixed across
panels.

```{r faceted-embedding, out.width='100%'}
real_examples$faceted_embedding
```

```{r faceted-embeddinggl, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$faceted_embedding+theme_webgl(shader = "default"), height = 720)
```

```{r faceted-embeddinggl2, out.width='100%', eval = ggwebgl_eval_widgets}
ggplot_webgl(real_examples$faceted_embedding, height = 720)
```

# Real-Data Demo

The same real-data scenes are available in a Shiny app:

```r
source(system.file("examples", "shiny", "real-data-demo.R", package = "ggWebGL"))
```

And as standalone HTML exports:

```r
source(system.file("examples", "htmlwidget", "real-data-gallery.R", package = "ggWebGL"))
export_real_data_gallery()
```