% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CubicalComplex.R
\name{build_cubical_filtration}
\alias{build_cubical_filtration}
\title{Build a cubical (grid) filtration from an image}
\usage{
build_cubical_filtration(image, superlevel = FALSE)
}
\arguments{
\item{image}{A numeric matrix (grid of pixel/voxel values, e.g. a
grayscale image with values in \code{[0, 255]}).}

\item{superlevel}{If \code{TRUE}, filters by decreasing value instead
(equivalent to negating \code{image} first) - useful for tracking
bright structures shrinking rather than dark structures growing.}
}
\value{
A filtration list: one \code{list(simplex = <integer vector of
  pixel ids>, t = <numeric>)} per simplex, sorted by (t, dimension,
  lexicographic order) - the same format as
  \code{\link{build_filtration}}.
}
\description{
Build a cubical (grid) filtration from an image
}
\examples{
# a ring (value 1) around a hole (value 5) around a background (value 9):
# the hole is born once the ring closes and dies once its center fills in
image <- matrix(c(
  9, 9, 9, 9, 9,
  9, 1, 1, 1, 9,
  9, 1, 5, 1, 9,
  9, 1, 1, 1, 9,
  9, 9, 9, 9, 9
), nrow = 5, byrow = TRUE)
filtration <- build_cubical_filtration(image)
pairs <- persistence_pairs(filtration)
pairs[pairs$dim == 1, ] # one H1 bar: birth = 1 (ring closes), death = 5
plot_persistence(pairs)
}
