---
title: "Whole-Slide Prediction Basics"
vignette: >
  %\VignetteIndexEntry{Whole-Slide Prediction Basics}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
format:
  html:
    toc: true
execute:
  warning: false
  message: false
  eval: false
---

This vignette walks through a whole-slide style inference workflow using a
pretrained **detection** model. The focus is:

- loading a pretrained model
- running sliced inference on a large image
- reviewing overlays and tabular outputs
- summarizing detections for downstream analysis

For now this is detection-first. Segmentation can also be run on large images,
but its workflow is different because RF-DETR segmentation does not yet use the
SAHI path in this package.

## Load the Toolkit

```{r setup}
library(petrographer)
library(dplyr)
library(fs)
```

## Point to a Large Image

Replace the placeholder path with a whole-slide image or any large thin-section
image you want to analyze.

```{r whole-slide-path}
wsi_path <- "path/to/whole_slide_image.tif"
file_exists(wsi_path)
```

## Load a Pretrained Model

Use `from_pretrained()` to load a detector from your local board or the public
hub.

```{r load-model}
model <- from_pretrained(
  model_id = "inclusions_small",
  device = "cpu",
  confidence = 0.5
)

model
```

The loaded object keeps the parsed manifest and training summary, so you can
inspect provenance if needed:

```{r inspect-model}
model$manifest$model
model$training_summary$training
```

## Run SAHI Inference

For large images, sliced inference usually works better than trying to process
the entire image at once. `slice_size` and `overlap` let you trade off runtime,
memory use, and boundary stability.

```{r predict-slide}
output_dir <- path("results", path_file(path_ext_remove(wsi_path)))

predictions <- predict_image(
  image_path = wsi_path,
  model = model,
  use_slicing = TRUE,
  slice_size = 1024,
  overlap = 0.2,
  output_dir = output_dir,
  save_visualizations = TRUE
)

predictions
```

The returned tibble contains one row per detected object, including class
labels, confidence scores, bounding-box-derived geometry, and summary fields
added by `enhance_results()`.

## Review the Overlay

```{r visualise-results}
dir_ls(output_dir)

viz_path <- dir_ls(output_dir, glob = "*_prediction.png", fail = FALSE)
if (length(viz_path)) {
  knitr::include_graphics(viz_path[[1]])
}
```

## Summarize Detections

```{r summarise-stats}
per_image <- summarize_by_image(predictions)
per_image

population <- get_population_stats(predictions)
population
```

These summaries are useful for:

- slide-level QA
- comparing slides or treatment groups
- spotting large shifts in count or size distributions

## Batch Process a Directory

Once you are happy with the settings on one image, scale out to a directory.

```{r batch-predict}
batch_results <- predict_images(
  input_dir = "path/to/whole_slide_directory",
  model = model,
  use_slicing = TRUE,
  slice_size = 1024,
  overlap = 0.2,
  output_dir = "results/batch_whole_slides",
  save_visualizations = TRUE
)

batch_results
```

## Next Steps

- adjust `slice_size` and `overlap` to match your image scale and memory budget
- filter `predictions` with tidyverse tools for class-specific summaries
- use `summarize_by_image()` and `get_population_stats()` for reporting
- for segmentation-oriented workflows, use the training and prediction
  templates/notebooks rather than this detection-first vignette