Rasterise ROIs to a mask ("Schablone")

Produce a binary, labelled, or multi-class integer mask from annotations. This is the package's core output artifact.

Usage

at_mask(
  x,
  type = c("binary", "labelled", "multiclass"),
  layer = NULL,
  label = NULL,
  level = 0L,
  background = 0L,
  touches = FALSE,
  dims = NULL,
  values = NULL,
  overlap = c("last", "first", "max", "min", "error", "bitor"),
  engine = c("stars", "terra"),
  call = rlang::caller_env()
)

Arguments

x

An annot_roi, annot_layer, or annot_project.

type

"binary" (a logical matrix), "labelled" (one integer id per ROI), or "multiclass" (one id per label class).

layer

Optional layer name(s) to restrict to (projects only).

label

Optional label(s) to restrict to.

level

Integer pyramid level at which to rasterise. Default 0.

background

Integer background value. Default 0.

touches

Logical; see the coverage contract. Default FALSE.

dims

Optional c(width, height); taken from the image (projects) or the geometry bounding box otherwise.

values

Optional named integer vector mapping labels to explicit class codes (e.g. c(specular = 1L, blood = 2L, shadow = 4L)), used only for type = "multiclass". When NULL (default) codes follow first-seen label order. Supply power-of-two codes together with overlap = "bitor" to build a bitfield mask.

overlap

How overlapping ROIs resolve: "last" (later z-order wins, the default), "first", "max", "min", "error" (abort on any overlap), or "bitor" (bitwise-OR the overlapping values, for bitfield masks; use with power-of-two values and background = 0).

engine

"stars" (reference) or "terra" (accelerated, if installed); the two produce identical masks.

call

The calling environment, for error reporting.

Value

An annot_mask: a matrix (logical for "binary", otherwise integer) with attributes legend (a tibble with columns value, label, layer, roi_id, n_px, colour), level, dims, type, and created. An all-background mask of the correct dimensions is returned when there are no ROIs.

Details

Pixel-coverage contract. Pixel (i, j) covers the half-open square [j-1, j) x [i-1, i) with (0, 0) at the top-left corner of the top-left pixel; its centre is (j - 0.5, i - 0.5). With touches = FALSE (default) a pixel is included when its centre lies inside the polygon; with touches = TRUE a pixel is included if the polygon touches it at all. ROI coordinates use the image convention (top-left origin, y down).

See also

at_write_mask(), at_read_mask(), at_mask_stats()

Other masks: at_mask_agreement(), at_mask_boundary(), at_mask_derive(), at_mask_legend(), at_mask_preview(), at_mask_stack(), at_mask_stats(), at_read_mask(), at_read_npy(), at_write_mask(), at_write_masks(), at_write_npy()

Examples

proj <- at_example_project()
m <- at_mask(proj, type = "multiclass")
table(as.integer(m))
#> 
#>      0      1      2      3 
#> 135640  19600  72704  34200