% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grouped.R
\name{explode_grouped}
\alias{explode_grouped}
\title{Create a three-level grouped exploded map}
\usage{
explode_grouped(
  sf_obj,
  region_col,
  mode = c("auto", "auto_collision", "manual"),
  anchors = NULL,
  alpha_l = NULL,
  p = 1.25,
  gamma_l = 1.136,
  kappa = 1.8,
  padding = 50000,
  delta = 15000,
  lambda = 0.18,
  eta = 0.18,
  padding_sep = 20000,
  anchor_expand = NULL,
  anchor_buffer = NULL,
  density_scale = NULL,
  block_sep = NULL,
  max_iter = 60,
  fix_invalid = TRUE,
  centroid_fun = c("centroid", "point_on_surface"),
  plot = TRUE,
  export = NULL,
  label = "Grouped Layout",
  quiet = FALSE
)
}
\arguments{
\item{sf_obj}{Projected sf object with region column}

\item{region_col}{Grouping column name}

\item{mode}{"auto", "auto_collision", or "manual"}

\item{anchors}{For mode = "manual": data.frame with anchor positions}

\item{alpha_l}{Local expansion parameter for Level 1 (metres)}

\item{p}{Distance scaling exponent (default 1.25)}

\item{gamma_l}{Local clearance coefficient (default 1.136); used if alpha_l is NULL}

\item{kappa}{Radial expansion factor (default 1.8)}

\item{padding}{Base padding (default 50000)}

\item{delta}{Log-density scaling (default 15000)}

\item{lambda}{Spring coefficient (default 0.18)}

\item{eta}{Repulsion step (default 0.18)}

\item{padding_sep}{Minimum block separation (default 20000)}

\item{anchor_expand, anchor_buffer, density_scale, block_sep}{Optional aliases
for \code{kappa}, \code{padding}, \code{delta}, and \code{padding_sep}, respectively. These
names are convenient in Shiny dashboards where the controls describe the
visual effect rather than the solver term.}

\item{max_iter}{Max collision iterations (default 60)}

\item{fix_invalid}{Auto-repair invalid geometries (default TRUE)}

\item{centroid_fun}{"centroid" or "point_on_surface"}

\item{plot}{Print plots (default TRUE). Automatically suppressed inside a
live Shiny session; use \code{\link[=plot.grouped_exploded_map]{plot.grouped_exploded_map()}} inside \code{renderPlot()}.}

\item{export}{NULL, TRUE, or file path}

\item{label}{Title for plots}

\item{quiet}{If \code{TRUE}, suppress \code{message()} output. Default \code{FALSE}.}
}
\value{
A \code{grouped_exploded_map} S3 object (inherits from \code{exploded_map})
}
\description{
Combines Level 1 (local explosion within regions) with Level 2/3
(anchor-based region block placement). This is the full three-level
extension from Section 12 of the paper.
}
\details{
The guarantees of Propositions 1-3 apply strictly at Level 1.
Higher levels preserve structural grouping and directional correspondence
rather than topological coverage.
}
