Package 'segmantR'

Description

Constructor for the sg_image S3 class, which represents a multi-channel image with associated metadata.

Usage

new_sg_image(
  pixels,
  channels = NULL,
  resolution = NULL,
  metadata = list(),
  id = NULL,
  plane = NULL,
  origin = NULL,
  bands = NULL,
  value_semantics = "unknown",
  source_digest = NULL,
  transform_digest = NULL,
  provenance = list()
)

Arguments

Details

The pixel array order is always ⁠[y, x, channel]⁠: the first array row is the top image row. All arguments after metadata are optional interchange fields added in segmantR 0.2.0; objects created by older code simply lack them and are treated with the documented defaults.

Value

An object of class sg_image.

Examples

pixels <- matrix(runif(100), nrow = 10, ncol = 10)
img <- new_sg_image(pixels)
print(img)

# With interchange metadata
img2 <- new_sg_image(pixels, channels = "DAPI",
                     resolution = list(x_um = 0.5, y_um = 0.5),
                     id = "slide-001", value_semantics = "intensity")

Description

Constructor for the sg_mask S3 class, which stores an integer label matrix where 0 represents background and positive integers represent individual cell IDs.

Usage

new_sg_mask(
  labels,
  image_id = NULL,
  model_info = NULL,
  mask_type = c("instance", "labelled", "binary"),
  legend = NULL,
  plane = NULL,
  origin = NULL,
  status = c("draft", "staged", "reviewed"),
  provenance = list(),
  id = NULL
)

Arguments

Details

Masks follow the segmantR mask contract: integer values, 0 is the background, positive integers are object instances (mask_type = "instance", the default and historic meaning), class codes ("labelled") or foreground ("binary", values 0/1 only). All arguments after model_info are optional interchange fields.

Value

An object of class sg_mask.

Examples

labels <- matrix(c(0L, 0L, 1L, 1L, 0L, 2L, 2L, 0L, 0L), nrow = 3)
mask <- new_sg_mask(labels)
print(mask)

Description

Constructor for the sg_trained_model S3 class, representing a trained segmentation model with associated metadata.

Usage

new_sg_trained_model(
  model_path,
  backend = c("cellpose", "stardist"),
  base_model,
  training_metrics,
  model_card = list(),
  runtime = NULL,
  dataset_manifest = NULL,
  license = NULL,
  representation = "unknown"
)

Arguments

Value

An object of class sg_trained_model.

Examples

# a dedicated directory with a stand-in weight file
weights <- file.path(tempfile("model"), "cellpose_weights")
dir.create(dirname(weights))
writeBin(as.raw(1:16), weights)
mdl <- new_sg_trained_model(
  model_path = weights,
  backend = "cellpose",
  base_model = "cyto3",
  training_metrics = list(n_epochs = 100L, final_loss = 0.05)
)
print(mdl)

Description

Orchestrates a human-in-the-loop (HITL) active learning workflow: segment, review, correct, retrain, repeat.

Usage

sg_active_learning_loop(
  image,
  model = "cellpose",
  n_rounds = 5L,
  patches_per_round = 10L,
  patch_size = 256L,
  initial_model = "cyto3"
)

Arguments

Value

An sg_hitl_result S3 object with elements ⁠$rounds⁠ (list of per-round results), ⁠$final_model⁠ (trained model path or object), and ⁠$metrics⁠ (training metrics across rounds).

Examples

## Not run: 
# Requires Python with Cellpose and an interactive review session
img <- sg_example_image("fluorescence_nuclei")
result <- sg_active_learning_loop(img, n_rounds = 3L,
                                  patches_per_round = 2L, patch_size = 32L)

## End(Not run)

Description

Returns a shiny.appobj built from package code, with explicit input objects instead of global options. The app offers image/channel/band selection, a protocol picker with a parameter form generated from the protocol registry, mask overlay, backend status for optional DNN protocols, a staged/reviewed workflow with explicit overwrite confirmation, and export of a neutral interchange bundle. There is no code entry of any kind.

Usage

sg_app(input = NULL, state = NULL, control = "off", ...)

Arguments

Value

A shiny.appobj.

See Also

sg_run_app(), sg_control_capabilities()

Examples

app <- sg_app(list(image = sg_example_image("fluorescence_nuclei")))
class(app)
if (interactive()) {
  shiny::runApp(app)
}

Description

Takes a list of correction operations (split, merge, delete, add) and applies them to produce a corrected mask.

Usage

sg_apply_corrections(mask, corrections)

Arguments

Details

Each correction in the list must contain:

action = "delete"

Remove cell. Requires ⁠$cell_id⁠.

action = "merge"

Merge cells. Requires ⁠$cell_ids⁠ (integer vector).

action = "split"

Split a cell. Requires ⁠$cell_id⁠ and ⁠$seed_points⁠ (matrix with columns row, col).

action = "add"

Add a new cell. Requires ⁠$pixels⁠ (matrix of row/col coordinates).

Value

A corrected sg_mask object.

Examples

labels <- matrix(0L, nrow = 20, ncol = 20)
labels[3:8, 3:8] <- 1L
labels[12:18, 12:18] <- 2L
mask <- new_sg_mask(labels)
corrected <- sg_apply_corrections(mask, list(
  list(action = "delete", cell_id = 2L)
))
print(corrected)

Description

The canvas uses local array pixel coordinates (top-left origin, x right, y down). Drawing emits Shiny inputs suffixed ⁠_created⁠, ⁠_edited⁠, and ⁠_erased⁠. Use sg_canvas_correct() to stage changes to a mask.

Usage

sg_canvas(
  image,
  mask = NULL,
  channel = 1L,
  tool = "pan",
  width = NULL,
  height = 600,
  elementId = NULL
)

Arguments

Value

An HTML widget.

Examples

img <- new_sg_image(matrix(seq_len(72), 8, 9), id = "slide")
msk <- new_sg_mask(matrix(0L, 8, 9), image_id = "slide")
widget <- sg_canvas(img, msk, tool = "polygon")
class(widget)
if (interactive()) widget

Description

Geometry is in local array pixels. Changes retain image binding and are staged for explicit review. Overlapping cells are rejected.

Usage

sg_canvas_correct(
  mask,
  geometry = NULL,
  action = "add",
  cell_id = NULL,
  expected_revision
)

Arguments

Value

A staged sg_mask.

Examples

msk <- new_sg_mask(matrix(0L, 8, 9))
box <- list(type = "Polygon",
            coordinates = list(list(c(1, 1), c(4, 1), c(4, 4), c(1, 4), c(1, 1))))
added <- sg_canvas_correct(msk, box, expected_revision = sg_mask_revision(msk))
sum(added$labels > 0)
added$review$status

Description

Applies the postprocess.label-cleanup.v1 rules to an sg_mask in a fixed order: handling of disconnected label parts, hole filling, separation of touching objects, border removal, area filtering and relabelling. The legend (object ids, classes) follows the labels.

Usage

sg_cleanup_labels(
  mask,
  min_area = 0L,
  max_area = NULL,
  min_area_um2 = NULL,
  max_area_um2 = NULL,
  fill_holes = FALSE,
  connectivity = 4L,
  border = c("keep", "remove"),
  touching = c("keep", "separate"),
  disconnected = c("keep", "split", "keep_largest"),
  relabel = c("value", "raster", "none"),
  pixel_size = NULL
)

Arguments

Value

A new sg_mask. Masks derived from staged or reviewed masks are staged.

Examples

labels <- matrix(0L, 12, 12)
labels[2:4, 2:4] <- 1L
labels[7:11, 7:11] <- 2L
labels[9, 9] <- 0L
out <- sg_cleanup_labels(new_sg_mask(labels), min_area = 10L,
                         fill_holes = TRUE)
out$n_cells

Description

The local control service lets a partner (qupflowR, hyperannotatR) drive a running segmantR app through typed commands. It is planned and not implemented; this function reports the planned contract so partners can check for it without guessing. It never starts a server.

Usage

sg_control_capabilities()

Value

A list with schema, status ("planned"), implemented (FALSE), default ("off"), planned_commands and security_requirements.

Examples

sg_control_capabilities()$status

Description

Samples informative image patches for manual annotation or correction. Patches are selected on a grid or, when an initial mask is provided, prioritised by segmentation uncertainty.

Usage

sg_create_annotation_task(
  image,
  initial_mask = NULL,
  region = NULL,
  n_patches = 20L,
  patch_size = 256L
)

Arguments

Value

An sg_annotation_task S3 object (a list with elements patches, image_id, n_patches, patch_size, and created).

Examples

pixels <- matrix(runif(100 * 100), nrow = 100, ncol = 100)
img <- new_sg_image(pixels)
task <- sg_create_annotation_task(img, n_patches = 4L, patch_size = 32L)
print(task)

Description

Builds a tile-level dataset manifest from image/mask pairs without writing pixels. Tiles are laid out on a regular grid (tile_size, overlap), splits are assigned per group (subject_id, sample_id or slide_id) with a fixed seed so tiles of one origin never land in different splits, and every tile records its bounds, plane, object list (label, object id, class) and exclusion reason.

Usage

sg_dataset_manifest(
  pairs,
  tile_size = 256L,
  overlap = 0L,
  group_by = c("subject_id", "sample_id", "slide_id"),
  split = c(train = 0.7, validation = 0.15, test = 0.15),
  seed = 1L,
  mask_type = c("instance", "labelled", "binary"),
  min_objects = 1L,
  partial_tiles = c("exclude", "keep"),
  require_reviewed = FALSE,
  normalization = list(method = "none"),
  backend = NULL
)

Arguments

Details

Masks must satisfy the requested mask_type: integer, background 0, and for "instance" one connected part per label. A foreground/background mask with several objects under one label is rejected (NOT_INSTANCE_MASK) instead of being accepted silently.

Value

An sg_dataset_manifest list conforming to dataset-manifest.schema.json.

Examples

img <- sg_example_image("fluorescence_nuclei")
# The synthetic example mask contains overlapping ellipses; split them
# into separate instances first.
msk <- sg_cleanup_labels(sg_example_mask("fluorescence_nuclei"),
                         disconnected = "split")
pairs <- list(
  list(image = img, mask = msk, subject_id = "A"),
  list(image = img, mask = msk, subject_id = "B")
)
man <- sg_dataset_manifest(pairs, tile_size = 32L, min_objects = 0L,
                           split = c(train = 0.5, validation = 0.5,
                                     test = 0))
table(vapply(man$tiles, function(t) t$split, ""))

Description

Sets the black and full-colour levels of each channel from the signal around reference cells, so that called-negative cells stay dark and called-positive cells reach full colour: for every channel up to n negative and n positive cells are drawn, a statistic of the (2 * half + 1)-pixel square patch around each cell is taken ("mean" or a percentile given as a probability), and the levels are the black quantile of the negative and the white quantile of the positive cell values.

Usage

sg_display_levels(
  path,
  channels,
  cells,
  positive,
  negative,
  x = "x",
  y = "y",
  label = "label",
  pixel_size = 1,
  half = 7,
  statistic = 0.9,
  black = 0.5,
  white = 0.5,
  n = 300,
  seed = 0
)

Arguments

Details

Arguments that vary by channel (half, statistic, black, white) accept a single value or a named list/vector by channel name, with an optional .default entry.

Value

A data frame with columns channel, lo, hi, n_negative and n_positive.

See Also

sg_slide_display_ranges(), sg_display_range()

Examples

f <- tempfile(fileext = ".tif")
plane <- matrix(10, 40, 40)
plane[21:40, ] <- 200
invisible(tiff::writeTIFF(plane / 255, f, bits.per.sample = 8L))
cells <- data.frame(x = c(5, 15, 25, 35), y = c(5, 10, 30, 35),
                    label = c("neg", "neg", "pos", "pos"))
sg_display_levels(f, "ch1", cells, positive = list(ch1 = "pos"),
                  negative = list(ch1 = "neg"), half = 2)

Description

Percentile-based display (black and white) levels for a set of pixel values, as used to scale fluorescence channels for viewing: lo is the lower percentile (or a given value), hi the larger of the upper percentile, an optional floor and lo + min_span. Percentiles use linear interpolation between order statistics (stats::quantile(type = 7)).

Usage

sg_display_range(
  x,
  probs = c(0.01, 0.997),
  lo = NULL,
  hi_floor = NULL,
  min_span = 1
)

Arguments

Value

Named numeric c(lo = , hi = ).

See Also

sg_slide_display_ranges(), sg_display_levels()

Examples

sg_display_range(c(0, 1, 2, 3, 100))
sg_display_range(1:10, probs = c(NA, 0.995), lo = 2, hi_floor = 20)

Description

Read and validate an ENVI header without reading pixel data

Usage

sg_envi_info(path, data_file = NULL)

Arguments

Value

A list of class sg_envi_info with samples, lines, bands, interleave, byte_order, data_type, dtype, header_offset, wavelength_nm, fwhm_nm, band_names, nodata, scale_factor, gain, offset, wavelength_units, data_bytes_expected, data_bytes_present and header_digest. Paths are not stored.

Examples

d <- tempfile("envi")
dir.create(d)
hdr <- file.path(d, "cube.hdr")
writeLines(c("ENVI", "samples = 2", "lines = 2", "bands = 2",
             "header offset = 0", "data type = 12", "interleave = bsq",
             "byte order = 0", "wavelength = {500, 600}"), hdr)
writeBin(1:8, file.path(d, "cube"), size = 2L, endian = "little")
sg_envi_info(hdr)$wavelength_nm

Description

Computes standard instance segmentation metrics by comparing a predicted mask against a ground truth mask.

Usage

sg_evaluate_segmentation(
  predicted,
  ground_truth,
  metrics = c("dice", "jaccard", "aji", "panoptic_quality", "ap50", "ap75",
    "f1_detection")
)

Arguments

Details

Instances are matched one-to-one at an intersection-over-union (IoU) threshold. "ap50" and "ap75" are the instance-segmentation average precision used by Cellpose and StarDist at IoU 0.5 and 0.75, $TP / (TP + FP + FN)$; "f1_detection" is the F1 score of the matches at IoU 0.5, $2TP / (2TP + FP + FN)$.

Value

An sg_eval S3 object (a tibble with columns metric and value) with a custom print method.

Examples

pred_labels <- matrix(0L, nrow = 20, ncol = 20)
pred_labels[3:8, 3:8] <- 1L
pred_labels[12:18, 12:18] <- 2L
gt_labels <- matrix(0L, nrow = 20, ncol = 20)
gt_labels[3:9, 3:9] <- 1L
gt_labels[12:17, 12:17] <- 2L
pred <- new_sg_mask(pred_labels)
gt <- new_sg_mask(gt_labels)
result <- sg_evaluate_segmentation(pred, gt)
print(result)

Description

Returns an sg_image containing synthetic image data for testing and demonstrations. The data are drawn with a fixed seed, so they are the same in every session, and the caller's random number stream is left unchanged.

Usage

sg_example_image(type = c("he_breast", "fluorescence_nuclei", "multiplex_4ch"))

Arguments

Value

An sg_image object.

See Also

sg_example_mask() for the matching label masks.

Examples

img <- sg_example_image("he_breast")
print(img)

Description

Returns an sg_mask matching the corresponding example image. Like sg_example_image(), it leaves the caller's random number stream unchanged.

Usage

sg_example_mask(type = c("he_breast", "fluorescence_nuclei", "multiplex_4ch"))

Arguments

Value

An sg_mask object whose labels are 0 for background and positive integers for the cells of the example image of the same type.

Examples

mask <- sg_example_mask("he_breast")
print(mask)

Description

Writes a bundle directory containing a manifest, the requested representations and an integrity.json inventory with SHA-256 hashes and relative paths. All representations describe the same envelope: the integer mask TIFF holds exact labels, the GeoJSON holds exact pixel-edge polygons in image coordinates with the same object ids, and the measurements table uses the canonical long format (value_state distinguishes missing, NaN and infinite values). RDS is an optional R-native optimisation and never the only representation.

Usage

sg_export_interchange(
  x,
  destination,
  formats = c("manifest", "mask_tiff", "geojson", "measurements"),
  ...,
  image = NULL,
  object_type = c("detection", "annotation", "cell"),
  overwrite = FALSE
)

Arguments

Value

An sg_interchange_bundle (invisibly) with path, manifest and bundle_digest.

Examples

m <- sg_example_mask("fluorescence_nuclei")
img <- sg_example_image("fluorescence_nuclei")
out <- sg_export_interchange(m, tempfile("bundle"), image = img)
list.files(out$path)
out$bundle_digest

Description

Writes a segmentation mask to disk in one of several formats.

Usage

sg_export_mask(
  mask,
  path,
  format = c("tiff", "png", "geojson", "qupath", "csv")
)

Arguments

Value

The output file path, returned invisibly.

Examples

labels <- matrix(0L, nrow = 10, ncol = 10)
labels[3:8, 3:8] <- 1L
mask <- new_sg_mask(labels)
tmp <- tempfile(fileext = ".csv")
sg_export_mask(mask, tmp, format = "csv")

Description

Writes a QuPath program directory: a declarative run.json (schema segmantR-qupath-run-v1), the readable Groovy templates, the resources they bind (a neutral interchange bundle or a hashed model copy), a run_export.json for the way back, checksums.sha256 and a README.md with the interactive and command-line invocations. segmantR never starts QuPath, Java or Groovy itself.

Usage

sg_export_qupath(
  x,
  destination,
  ...,
  image = NULL,
  image_name = NULL,
  model = NULL,
  region_policy = c("whole_image", "selected_annotations", "all_annotations"),
  save_policy = c("none", "project"),
  object_type = c("detection", "annotation", "cell"),
  require_calibration = TRUE,
  min_qupath_version = "0.5.0",
  allow_unsupported = FALSE,
  overwrite = FALSE
)

Arguments

Details

• For an sg_mask, sg_run or list with a mask, the task is import: the mask is exported with sg_export_interchange() into ⁠bundle/⁠ (integer TIFF, exact GeoJSON with object ids, legend, measurements) and segmantR_import.groovy adds the objects to the open image after checking size, calibration, plane, SHA-256 and id collisions.

• For a StarDist protocol ("stardist.2d.v1" or an sg_protocol), the task is stardist: parameters are mapped with sg_stardist_parameter_map() (unsupported non-default options are errors unless allow_unsupported = TRUE, and are always listed in run.json), the model is copied into ⁠models/⁠ and its digest is recorded for verification by the template.

Value

An sg_qupath_program (invisibly) with path, task, run (parsed run.json) and commands (headless command lines).

Examples

m <- sg_example_mask("fluorescence_nuclei")
img <- sg_example_image("fluorescence_nuclei")
prog <- sg_export_qupath(m, tempfile("qupath"), image = img,
                         require_calibration = FALSE)
prog$commands[["import"]]

Description

Computes intensity, morphology, texture, and location features for each segmented cell. Returns a tibble with one row per cell.

Usage

sg_extract_features(
  image,
  mask,
  features = c("intensity", "morphology", "texture", "location"),
  channels = NULL
)

Arguments

Details

Morphology features: perimeter is the number of boundary pixels; circularity is $4 \pi A / P^2$, capped at 1 because the boundary-pixel count underestimates the perimeter of round objects; eccentricity comes from the eigenvalues of the pixel-coordinate covariance (0 for a disc, 1 for a line of pixels); solidity is the area divided by the area of the convex hull of the pixel squares. Circularity, eccentricity and solidity are NA for single-pixel cells.

Value

A tibble with one row per cell and a cell_id column, plus columns for each requested feature.

Examples

pixels <- array(runif(20 * 20 * 2), dim = c(20, 20, 2))
img <- new_sg_image(pixels, channels = c("DAPI", "CD3"))
labels <- matrix(0L, nrow = 20, ncol = 20)
labels[3:8, 3:8] <- 1L
labels[12:18, 12:18] <- 2L
mask <- new_sg_mask(labels)
feats <- sg_extract_features(img, mask, features = c("intensity", "morphology"))
print(feats)

Description

Removes cells from a segmentation mask that fall outside specified morphological thresholds. Useful for quality control after initial segmentation.

Usage

sg_filter_cells(
  mask,
  min_area = 50L,
  max_area = 5000L,
  min_circularity = 0.3,
  max_eccentricity = 0.95,
  border_cells = c("keep", "remove", "flag")
)

Arguments

Value

A filtered sg_mask object. When border_cells = "flag", the returned mask has an additional border_cell_ids element.

Examples

labels <- matrix(0L, nrow = 20, ncol = 20)
labels[3:8, 3:8] <- 1L
labels[12:18, 12:18] <- 2L
mask <- new_sg_mask(labels)
filtered <- sg_filter_cells(mask, min_area = 10L, max_area = 100L)
print(filtered)

Description

Computes SHA-256 digests and sizes for every regular file below root (except the inventory files themselves), using bundle-relative forward-slash paths. The integrity.json form is identical to the qupflowR workflow-bundle rule: ⁠{"format_version": "1.0", "files": [{"path", "size_bytes", "sha256"}]}⁠ sorted by path, and the bundle digest is the SHA-256 of its canonical JSON (keys sorted, no whitespace). checksums.sha256 uses the sha256sum text format.

Usage

sg_hash_assets(
  root,
  files = NULL,
  write = c("none", "integrity", "sha256sum", "both"),
  verify = FALSE
)

Arguments

Details

Symbolic links, absolute or parent-relative paths and special files are rejected. Absolute paths are never written.

Value

An sg_asset_inventory list with files (tibble), integrity (list) and bundle_digest ("sha256:<hex>"), invisibly when writing.

Examples

d <- tempfile("bundle")
dir.create(d)
writeLines("a", file.path(d, "a.txt"))
inv <- sg_hash_assets(d, write = "integrity")
inv$bundle_digest
sg_hash_assets(d, verify = TRUE)$bundle_digest == inv$bundle_digest

Description

Reads the directory structure of a (Q)PTIFF, OME-TIFF or plain multi-page TIFF through GDAL and returns one row per full-resolution channel plane. Channel names come from the per-plane image description (⁠<Biomarker>⁠, then ⁠<Name>⁠, as written by PhenoCycler/Vectra QPTIFF files), from the ⁠Channel Name⁠ attributes of OME-XML on the first plane, or default to ch1, ch2, .... Reduced-resolution pages (overviews, thumbnails, label and macro images) are left out: a plane belongs to the channel set when it has one band and the size of the first plane.

Usage

sg_image_channels(path)

Arguments

Value

A data frame with columns channel (1-based channel number), name, directory (1-based TIFF directory), width, height, block_width, block_height, datatype and dsn (the GDAL dataset name of the plane).

See Also

sg_read_window(), sg_read_field()

Examples

f <- tempfile(fileext = ".tif")
planes <- list(matrix(1:100, 10, 10), matrix(101:200, 10, 10))
invisible(tiff::writeTIFF(lapply(planes, function(p) p / 255), f,
                          bits.per.sample = 8L))
sg_image_channels(f)[, c("channel", "name", "width", "height")]

Description

Reads a segmantR interchange bundle or a single GeoJSON, integer TIFF, measurement CSV or RDS file, verifies it and returns a report with the imported objects. Imported masks are always staged; they never replace reviewed data (see sg_replace_mask()).

Usage

sg_import_interchange(
  path,
  format = "auto",
  expected_digest = NULL,
  ...,
  shape_yx = NULL,
  image = NULL,
  origin = NULL,
  trust_rds = FALSE,
  error = TRUE
)

Arguments

Details

Bundle checks: inventory (missing, extra, duplicate, resized or modified files, unsafe paths, symbolic links), optional expected_digest, schema family and major version, JSON Schema, asset hashes, TIFF dtype, shape and orientation, background code, label legend completeness, plane consistency, content digest and revision, GeoJSON object ids and exact geometry agreement with the TIFF, and measurement object ids.

Value

An sg_import_report list with ok, format, checks (tibble), mask (staged sg_mask or NULL), image, measurements, features (parsed GeoJSON features), manifest, bundle_digest, conversions and error.

Examples

m <- sg_example_mask("fluorescence_nuclei")
b <- sg_export_interchange(m, tempfile("bundle"))
rep <- sg_import_interchange(b$path, expected_digest = b$bundle_digest)
rep$ok
sg_mask_status(rep$mask)$status

Description

Reads the output of the segmantR QuPath templates (a directory with a qupath-export manifest and integrity.json), a QuPath program directory containing such an output (⁠out/⁠ or ⁠qupath_export/⁠), or a plain QuPath GeoJSON export. All checks of sg_import_interchange() run (inventory, schema, dtype, shape/orientation, legend, content digest and revision); in addition the QuPath GeoJSON is rasterised and compared with the QuPath label TIFF, object ids are matched through the legend, the run id and image binding can be checked, and measurements are imported in the canonical long format (namespace = "stored"). The mask is staged.

Usage

sg_import_qupath(path, ..., image = NULL, expected_run_id = NULL, error = TRUE)

Arguments

Value

An sg_import_report with an extra qupath element (QuPath and extension versions, template version, run id, GeoJSON/TIFF agreement).

Examples

# a plain QuPath GeoJSON export, rasterised onto the image grid
cells <- sg_roi_layer_add(sg_roi_layer("cells"),
                          sg_roi_rect(2, 2, 8, 8, label = "cell"))
cells <- sg_roi_layer_add(cells, sg_roi_rect(10, 10, 15, 16, label = "cell"))
p <- tempfile(fileext = ".geojson")
sg_roi_write_qupath(sg_roi_project(sg_roi_frame(c(20, 20)), cells), p)
rep <- sg_import_qupath(p, image = new_sg_image(matrix(0, 20, 20)))
rep$mask$n_cells

Description

Describes what this installation of segmantR can exchange: schema and API versions, interoperability profiles with their status ("supported", "planned" or "unavailable"), file formats, protocols, optional backends and limits. Optional Python backends are only probed when check_backends = TRUE; QuPath is detected from installation files without starting it.

Usage

sg_interchange_capabilities(check_backends = FALSE)

Arguments

Details

Profiles: I0 neutral files (manifest, integer TIFF masks, GeoJSON, measurements, integrity inventory); I1 versioned protocols and run envelopes; models model bundles with runtime and checksums; qupath_programs Groovy templates and run.json; stardist_qupath the StarDist extension adapter; control the local control service (segmantR-control-v1); partner_qupflowR and partner_hyperannotatR the partner contracts, which stay planned until a real consumer and QuPath evidence exist.

Value

An sg_capabilities list conforming to capabilities.schema.json, with a digest over its content.

Examples

caps <- sg_interchange_capabilities()
caps$profiles$I0$status
caps$schema

Description

Describes an image, mask or segmentation run with the shared coordinate convention, plane, pixel size, legend, review state, protocol reference, runtime and asset inventory. The result conforms to inst/schema/segmantR-interchange-v1/manifest.schema.json.

Usage

sg_interchange_manifest(
  x,
  ...,
  image = NULL,
  assets = list(),
  conversions = list(),
  kind = NULL
)

Arguments

Value

An sg_manifest list.

Examples

m <- sg_example_mask("fluorescence_nuclei")
man <- sg_interchange_manifest(m)
man$mask$label_count
man$coordinate_convention$y_axis

Description

Reads a .segmantR archive created by sg_package_model() and returns an sg_trained_model object.

Usage

sg_load_model(path, expected_digest = NULL, allow_legacy = TRUE)

Arguments

Details

Before extracting, entry names are checked (no absolute paths, parent segments, backslashes or drive letters; entry count and total size limits). After extraction, symbolic links are rejected, checksums.sha256 is verified (missing, extra or modified files are errors), the model card schema and major version and the backend are checked. Archives written by segmantR 0.1.0 have no checksums; they load with integrity = "unverified" unless allow_legacy = FALSE.

Value

An sg_trained_model object.

Examples

# a dedicated directory with a stand-in weight file
weights <- file.path(tempfile("model"), "cellpose_weights")
dir.create(dirname(weights))
writeBin(as.raw(1:16), weights)
mdl <- new_sg_trained_model(weights, backend = "cellpose",
                            base_model = "cyto3",
                            training_metrics = list(n_epochs = 50L))
archive <- sg_package_model(mdl, tempfile(fileext = ".segmantR"))
model <- sg_load_model(archive)
model$integrity

Description

Returns the stored legend or, when none is stored, a deterministic legend with one row per positive label. Generated object ids are UUID-shaped strings derived from the image binding, the label content and the label value, so the same mask always yields the same ids. Use sg_mask_legend(mask, materialise = TRUE) to store the legend in the mask so ids stay stable through later edits.

Usage

sg_mask_legend(mask, materialise = FALSE)

Arguments

Value

A tibble with columns label, object_id, class, name, or the updated mask when materialise = TRUE.

Examples

labels <- matrix(0L, 6, 6)
labels[2:3, 2:3] <- 1L
labels[5:6, 5:6] <- 2L
sg_mask_legend(new_sg_mask(labels, image_id = "img-1"))

Description

sg_stage_mask() marks a mask as a staged candidate (for example an imported prediction). sg_review_mask() records that a human reviewed the current content. sg_replace_mask() replaces a mask by a candidate while protecting reviewed data: replacing a reviewed mask requires both expected_revision equal to its current revision and overwrite = TRUE. Replacing with identical content is a no-op that keeps the current status.

Usage

sg_stage_mask(mask, source = NULL, parent = NULL)

sg_review_mask(mask, reviewer = NULL, note = NULL, expected_revision = NULL)

sg_replace_mask(
  current,
  replacement,
  expected_revision = NULL,
  overwrite = FALSE
)

Arguments

Value

The updated sg_mask.

Examples

m <- new_sg_mask(matrix(c(0L, 1L, 1L, 0L), 2))
staged <- sg_stage_mask(m, source = "example")
rev <- sg_mask_revision(staged)
reviewed <- sg_review_mask(staged, reviewer = "me", expected_revision = rev)
sg_mask_status(reviewed)$status

candidate <- new_sg_mask(matrix(c(1L, 1L, 1L, 0L), 2))
try(sg_replace_mask(reviewed, candidate))
replaced <- sg_replace_mask(reviewed, candidate,
                            expected_revision = rev, overwrite = TRUE)
sg_mask_status(replaced)$status

Description

A "sha256:<hex>" digest over the label array (dimensions and row-major little-endian int32 values), the mask type and the effective legend. Identical content always yields the same revision, so repeated imports of the same prediction are idempotent.

Usage

sg_mask_revision(mask)

Arguments

Value

Character scalar.

Examples

m <- new_sg_mask(matrix(c(0L, 1L, 1L, 0L), 2))
sg_mask_revision(m)

Description

Review state of a mask

Usage

sg_mask_status(mask)

Arguments

Value

A list with status, revision (current content revision), reviewed_revision, parent_revision and consistent (FALSE when a reviewed mask was modified after review).

Examples

sg_mask_status(new_sg_mask(matrix(0L, 3, 3)))

Description

Extracts cell boundaries from a label mask and returns them as polygon geometries. If the sf package is available, returns an sf data frame; otherwise returns a tibble of boundary coordinates.

Usage

sg_mask_to_polygons(mask, simplify = TRUE, tolerance = 1)

Arguments

Value

An sf data frame with one row per cell (columns cell_id and geometry) when sf is available, or a tibble with columns cell_id, row, col listing boundary coordinates.

Examples

labels <- matrix(0L, nrow = 20, ncol = 20)
labels[3:8, 3:8] <- 1L
labels[12:18, 12:18] <- 2L
mask <- new_sg_mask(labels)
polys <- sg_mask_to_polygons(mask, simplify = FALSE)
head(polys)

Description

Combines a nuclear segmentation mask with a cell body segmentation mask to produce paired nuclear-cell assignments.

Usage

sg_merge_masks(nuclear_mask, cell_mask, method = c("assign", "expand"))

Arguments

Value

A list with elements ⁠$nuclear⁠ and ⁠$cell⁠, both sg_mask objects with matched cell IDs.

Examples

nuc_labels <- matrix(0L, nrow = 20, ncol = 20)
nuc_labels[5:7, 5:7] <- 1L
nuc_labels[14:16, 14:16] <- 2L
cell_labels <- matrix(0L, nrow = 20, ncol = 20)
cell_labels[3:9, 3:9] <- 1L
cell_labels[12:18, 12:18] <- 2L
nuc_mask <- new_sg_mask(nuc_labels)
cell_mask <- new_sg_mask(cell_labels)
merged <- sg_merge_masks(nuc_mask, cell_mask)
print(merged$nuclear)

Description

Prints a human-readable model card for a trained segmentation model and returns the card contents as a tibble.

Usage

sg_model_card(trained_model)

Arguments

Value

A tibble with columns field and value representing the model card contents, returned invisibly.

Examples

# a dedicated directory with a stand-in weight file
weights <- file.path(tempfile("model"), "cellpose_weights")
dir.create(dirname(weights))
writeBin(as.raw(1:16), weights)
mdl <- new_sg_trained_model(
  model_path = weights,
  backend = "cellpose",
  base_model = "cyto3",
  training_metrics = list(n_epochs = 100L),
  model_card = list(author = "Test User", tissue = "lung")
)
sg_model_card(mdl)

Description

Creates a .segmantR archive (ZIP format) containing model weights, a model_card.json, and optionally training data.

Usage

sg_package_model(
  trained_model,
  output_path,
  name = NULL,
  description = NULL,
  include_training_data = FALSE,
  format = c("segmantR", "cellpose", "both"),
  embed_weights = TRUE,
  license = NULL,
  overwrite = TRUE
)

Arguments

Details

The archive keeps relative paths and contains a versioned model_card.json (schema segmantR-model-card-v1, still carrying the fields written by segmantR 0.1.0), runtime.json, dataset_manifest.json when the model has one, license.json when a license is given, the weights under ⁠weights/⁠ (or a hashed relative reference when embed_weights = FALSE) and checksums.sha256 covering every file. Python environments are never copied into a bundle.

Value

The output file path, returned invisibly.

Examples

# a dedicated directory with a stand-in weight file
weights <- file.path(tempfile("model"), "cellpose_weights")
dir.create(dirname(weights))
writeBin(as.raw(1:16), weights)
mdl <- new_sg_trained_model(
  model_path = weights,
  backend = "cellpose",
  base_model = "cyto3",
  training_metrics = list(n_epochs = 50L)
)
out <- sg_package_model(mdl, tempfile(fileext = ".segmantR"))

Description

Shows two segmentation masks (and optionally the source image) next to each other using faceted panels.

Usage

sg_plot_comparison(
  mask_a,
  mask_b,
  image = NULL,
  labels = c("Method A", "Method B")
)

Arguments

Value

A ggplot2 object.

Examples

m1 <- new_sg_mask(matrix(c(0L, 1L, 1L, 0L), 2, 2))
m2 <- new_sg_mask(matrix(c(0L, 0L, 1L, 1L), 2, 2))
p <- sg_plot_comparison(m1, m2)
p

Description

Produces a scatter plot of two numeric cell features, with optional colour and faceting variables.

Usage

sg_plot_features(
  features,
  x = "area",
  y = "mean_intensity",
  color = NULL,
  facet = NULL
)

Arguments

Value

A ggplot2 object.

Examples

feat <- data.frame(
  cell_id = 1:10,
  area = rpois(10, 200),
  mean_intensity = runif(10)
)
p <- sg_plot_features(feat, x = "area", y = "mean_intensity")
p

Description

Assigns colours to cell regions based on cell ID, area, circularity, or cluster membership.

Usage

sg_plot_mask(
  mask,
  color_by = c("id", "area", "circularity", "cluster"),
  features = NULL,
  palette = "viridis"
)

Arguments

Value

A ggplot2 object.

Examples

labels <- matrix(c(0L, 1L, 1L, 2L, 2L, 0L, 3L, 3L, 0L), 3, 3)
mask <- new_sg_mask(labels)
p <- sg_plot_mask(mask)
p

Description

Displays a bar chart of segmentation evaluation metrics such as IoU, precision, recall, and F1.

Usage

sg_plot_metrics(eval_result)

Arguments

Value

A ggplot2 object.

Examples

res <- data.frame(
  metric = c("IoU", "Precision", "Recall", "F1"),
  value = c(0.82, 0.90, 0.85, 0.87)
)
p <- sg_plot_metrics(res)
p

Description

Renders a single image channel as a raster and overlays cell outlines from a segmentation mask.

Usage

sg_plot_overlay(
  image,
  mask = NULL,
  channel = 1L,
  outline_color = "#FF00FF",
  outline_width = 1,
  fill_alpha = 0,
  label_cells = FALSE,
  highlight = NULL
)

Arguments

Value

A ggplot2 object.

Examples

img <- new_sg_image(matrix(runif(400), 20, 20))
p <- sg_plot_overlay(img)
p

Description

Backend-agnostic prediction facade. The model's backend selects the protocol (stardist.2d.v1 or cellpose.2d.v1); the run goes through sg_protocol_run() so parameters are validated and recorded, the backend is checked at the point of use, and the resulting mask is staged with the model digest in its provenance. Predictions never overwrite reviewed masks; use sg_replace_mask() to adopt a reviewed result explicitly.

Usage

sg_predict_model(model, image, ..., protocol = NULL, output = c("mask", "run"))

Arguments

Value

A staged sg_mask or an sg_run.

Examples

mdl <- new_sg_trained_model(tempfile("model"), backend = "stardist",
                            base_model = "none", training_metrics = list())
img <- sg_example_image("fluorescence_nuclei")
run <- sg_predict_model(mdl, img, output = "run")
# "unavailable" unless a Python with 'stardist' has been selected
# (see sg_setup_python())
run$record$status

Description

Builds the dataset manifest with sg_dataset_manifest() and materialises the included tiles: image tiles as float64 TIFF (exact values, ⁠[y, x, channel]⁠ pages) and mask tiles as unsigned integer TIFF with labels renumbered 1..N per tile in raster order. Tile object lists map tile labels to source object ids. With a destination, a directory with dataset_manifest.json, ⁠tiles/<split>/images|masks/*.tif⁠ and integrity.json is written; otherwise tiles are returned in memory.

Usage

sg_prepare_training_data(pairs, destination = NULL, ..., overwrite = FALSE)

Arguments

Value

An sg_training_set with manifest, path (or NULL) and tiles (in-memory list when destination is NULL).

Examples

img <- sg_example_image("fluorescence_nuclei")
# The synthetic example mask contains overlapping ellipses; split them
# into separate instances first.
msk <- sg_cleanup_labels(sg_example_mask("fluorescence_nuclei"),
                         disconnected = "split")
ts <- sg_prepare_training_data(
  list(list(image = img, mask = msk, subject_id = "A")),
  tile_size = 32L, min_objects = 0L,
  split = c(train = 1, validation = 0, test = 0)
)
length(ts$tiles)

Description

Applies a chain of preprocessing steps to an sg_image object, including optional stain normalisation, denoising, and contrast enhancement.

Usage

sg_preprocess(
  image,
  stain_normalize = c("none", "macenko", "reinhard", "vahadane"),
  denoise = FALSE,
  contrast = c("none", "clahe", "stretch"),
  target_resolution = NULL
)

Arguments

Value

A new sg_image object with its history field updated to record the preprocessing steps applied.

Examples

pixels <- matrix(runif(400), nrow = 20, ncol = 20)
img <- new_sg_image(pixels)
img2 <- sg_preprocess(img)
img3 <- sg_preprocess(img, contrast = "stretch", denoise = TRUE)

Description

Get a registered protocol

Usage

sg_protocol_get(id, version = NULL)

Arguments

Value

An sg_protocol object (a validated named list).

Examples

p <- sg_protocol_get("threshold.otsu.v1")
p$version

Description

List registered segmentation protocols

Usage

sg_protocol_list(check_available = FALSE)

Arguments

Value

A tibble with one row per protocol: id, version, title, family, backend, delegate, requires_python, status ("core" or "optional"), available, qupath_mapping and digest.

Examples

sg_protocol_list()

Description

Validates the protocol, the parameters and the inputs, delegates to the corresponding direct function (sg_segment_threshold(), sg_segment_watershed(), sg_segment_propagate(), sg_cleanup_labels(), sg_segment_stardist(), sg_segment_cellpose(), sg_segment_mesmer()) with an explicit, recorded argument mapping, and returns the mask or a run envelope.

Usage

sg_protocol_run(image, protocol, ..., output = c("mask", "run"))

Arguments

Details

Core protocols run without Python. Optional DNN protocols check their backend first; when it is missing, output = "mask" signals an sg_capability_error and output = "run" returns a run with status = "unavailable". There is never a silent fallback to another method. DNN predictions are returned as staged masks.

Value

An sg_mask or an sg_run.

See Also

sg_protocol_list(), sg_protocol_schema(), sg_protocol_validate(), sg_export_interchange()

Examples

img <- sg_example_image("fluorescence_nuclei")
mask <- sg_protocol_run(img, "threshold.otsu.v1", min_area = 5L)
run <- sg_protocol_run(img, "threshold.otsu.v1", min_area = 5L,
                       output = "run")
run$record$delegate$arguments
identical(mask$labels, run$mask$labels)

Description

Protocol schema and parameter specifications

Usage

sg_protocol_schema(id = NULL)

Arguments

Value

For id = NULL, the parsed JSON Schema. Otherwise a tibble with name, type, default, nullable, minimum, maximum, enum, unit, requires_calibration, maps_to and description.

Examples

names(sg_protocol_schema()$properties)
sg_protocol_schema("threshold.otsu.v1")[, c("name", "default", "unit")]

Description

Checks the definition against segmantR-protocol-v1 (schema family and major version, JSON Schema, parameter mapping completeness, defaults), resolves parameters (unknown names and out-of-range values are errors), and, when an image is given, checks the input contract: array order and size, value semantics, channel/band selection and pixel calibration.

Usage

sg_protocol_validate(protocol, image = NULL, ..., error = TRUE)

Arguments

Value

An sg_protocol_validation list with ok, protocol, parameters, checks (tibble) and error (condition or NULL).

Examples

img <- sg_example_image("fluorescence_nuclei")
v <- sg_protocol_validate("threshold.otsu.v1", img, min_area = 5L)
v$ok
bad <- sg_protocol_validate("threshold.otsu.v1", img, min_area = -1L,
                            error = FALSE)
bad$error$code

Description

Reads only the requested bands and pixel window by seeking in the data file (BSQ, BIL or BIP; either byte order). Values are returned as stored: gain, offset and reflectance scale factors are recorded but never applied, and value_semantics is whatever the caller declares (default "unknown"), so raw counts, reflectance, radiance, intensity and absorbance are never mixed silently.

Usage

sg_read_envi(
  path,
  bands = NULL,
  window = NULL,
  value_semantics = "unknown",
  nodata_to_na = TRUE,
  source_digest = c("full", "header", "none"),
  data_file = NULL
)

Arguments

Value

An sg_image with pixels ⁠[y, x, band]⁠, a band table, origin set to the window offset, calibration_digest, and metadata$read_accounting (bytes_read, bands_read).

Examples

d <- tempfile("envi")
dir.create(d)
writeLines(c("ENVI", "samples = 3", "lines = 2", "bands = 2",
             "data type = 12", "interleave = bip", "byte order = 0",
             "wavelength = {500, 600}"), file.path(d, "cube.hdr"))
writeBin(1:12, file.path(d, "cube"), size = 2L, endian = "little")
img <- sg_read_envi(file.path(d, "cube.hdr"), bands = 2,
                    value_semantics = "raw")
img$pixels

Description

Converts a centre in physical units (for example micrometres) to pixels and reads a square window of round(size / pixel_size) pixels in each requested channel. The top-left pixel is round(centre / pixel_size) - n %/% 2, so a field is reproducible from its centre, size and pixel size alone.

Usage

sg_read_field(path, channels, centre, size, pixel_size = 1, fill = 0)

Arguments

Value

A list of class sg_field with channels (named list of n x n matrices), x0, y0, n, pixel_size, centre, size and extent (c(xmin, xmax, ymin, ymax) of the pixel edges in physical units).

See Also

sg_read_fields(), sg_read_window()

Examples

f <- tempfile(fileext = ".tif")
planes <- list(matrix(1:100, 10, 10), matrix(101:200, 10, 10))
invisible(tiff::writeTIFF(lapply(planes, function(p) p / 255), f,
                          bits.per.sample = 8L))
fld <- sg_read_field(f, c("ch1", "ch2"), centre = c(2.5, 2.5), size = 2,
                     pixel_size = 0.5)
fld$channels$ch2

Description

Reads one sg_read_field() per row of a table of centres. Each row names its image through source, looked up in paths.

Usage

sg_read_fields(
  centres,
  paths,
  channels = character(0),
  size,
  pixel_size = 1,
  fill = 0,
  x = "x",
  y = "y",
  source = NULL,
  id = NULL,
  channel_columns = NULL,
  key_prefix = ""
)

Arguments

Value

A named list of sg_field objects in row order; each carries the table row (as a one-row data frame) in row.

See Also

sg_read_field()

Examples

f <- tempfile(fileext = ".tif")
planes <- list(matrix(1:100, 10, 10), matrix(101:200, 10, 10))
invisible(tiff::writeTIFF(lapply(planes, function(p) p / 255), f,
                          bits.per.sample = 8L))
cells <- data.frame(id = c("a", "b"), x = c(2.5, 4), y = c(2.5, 3))
fields <- sg_read_fields(cells, f, channels = c("ch1", "ch2"), size = 2,
                         pixel_size = 0.5, id = "id")
fields$b$channels$ch2

Description

Reads TIFF, PNG, or JPEG image files and returns an sg_image object. Dispatches to EBImage::readImage() when available, otherwise uses imager::load.image(). The returned pixel array is always ordered ⁠[y, x, channel]⁠, and the object records the SHA-256 digest of the file in source_digest plus its base name (never the full path) in metadata$source_name.

Usage

sg_read_image(path, ...)

Arguments

Value

An sg_image object.

Examples

f <- tempfile(fileext = ".tif")
EBImage::writeImage(EBImage::Image(matrix(seq(0, 1, length.out = 200), 20, 10)),
                    f)
img <- sg_read_image(f)
dim(img$pixels)

Description

Reads height rows and width columns of one channel plane starting at the 0-based pixel offset (x0, y0). Only the image blocks that cover the window are decoded, so windows of very large whole-slide files are cheap. Parts of the window outside the image are filled with fill, which makes fields at the slide edge keep their nominal size.

Usage

sg_read_window(path, channel, x0, y0, width, height = width, fill = 0)

Arguments

Value

A numeric matrix with height rows and width columns (⁠[y, x]⁠), with attributes x0, y0 and channel (the name).

See Also

sg_read_field(), sg_image_channels()

Examples

f <- tempfile(fileext = ".tif")
plane <- matrix(0:11, nrow = 3, byrow = TRUE)
invisible(tiff::writeTIFF(plane / 255, f, bits.per.sample = 8L))
sg_read_window(f, 1, x0 = 1, y0 = 0, width = 2, height = 2)

Description

ROI geometries use null-CRS image coordinates: top-left origin, x right, y down. Layers preserve drawing order and projects retain edit provenance. These classes are distinct from segmantR's instance-mask classes.

See Also

sg_roi_rect(), sg_roi_frame(), sg_roi_layer(), sg_roi_project(), sg_roi_mask()

Description

Add a layer to a project

Usage

sg_roi_add_layer(project, layer, call = rlang::caller_env())

Arguments

Value

A new sg_roi_project with the layer added. The input is unchanged.

See Also

Other projects: sg_roi_add_roi(), sg_roi_layers(), sg_roi_project(), sg_roi_remove_layer(), sg_roi_remove_roi(), sg_roi_rois(), sg_roi_summary(), sg_roi_validate()

Examples

proj <- sg_roi_project(sg_roi_frame(c(20, 20)))
proj <- sg_roi_add_layer(proj, sg_roi_layer("tissue"))
names(proj$layers)

Description

Add an ROI to a project layer

Usage

sg_roi_add_roi(project, layer, roi, call = rlang::caller_env())

Arguments

Value

A new sg_roi_project with the ROI added to the layer. A colliding ROI identifier is re-minted to keep identifiers unique across the project. The input is unchanged.

See Also

Other projects: sg_roi_add_layer(), sg_roi_layers(), sg_roi_project(), sg_roi_remove_layer(), sg_roi_remove_roi(), sg_roi_rois(), sg_roi_summary(), sg_roi_validate()

Examples

proj <- sg_roi_project(sg_roi_frame(c(20, 20)), sg_roi_layer("tissue"))
proj <- sg_roi_add_roi(proj, "tissue", sg_roi_rect(2, 2, 8, 8, label = "tissue"))
sg_roi_rois(proj)$area_px

Description

ROI area

Usage

sg_roi_area(
  roi,
  level = 0L,
  units = c("px", "physical"),
  call = rlang::caller_env()
)

Arguments

Value

A numeric scalar area, or NA_real_ for non-areal geometry (points, lines).

See Also

Other rois: sg_roi_bbox(), sg_roi_centroid(), sg_roi_circle(), sg_roi_ellipse(), sg_roi_freehand(), sg_roi_from_geojson(), sg_roi_from_sf(), sg_roi_point(), sg_roi_polygon(), sg_roi_rect()

Examples

sg_roi_area(sg_roi_rect(0, 0, 10, 5, label = "a"))

Description

ROI bounding box

Usage

sg_roi_bbox(roi, call = rlang::caller_env())

Arguments

Value

A numeric vector c(xmin, ymin, xmax, ymax) in the ROI's stored coordinates.

See Also

Other rois: sg_roi_area(), sg_roi_centroid(), sg_roi_circle(), sg_roi_ellipse(), sg_roi_freehand(), sg_roi_from_geojson(), sg_roi_from_sf(), sg_roi_point(), sg_roi_polygon(), sg_roi_rect()

Examples

sg_roi_bbox(sg_roi_circle(50, 50, 10, label = "a"))

Description

Buffer an ROI

Usage

sg_roi_buffer(roi, dist, call = rlang::caller_env())

Arguments

Value

An sg_roi with the buffered geometry.

See Also

Other geometry: sg_roi_check_containment(), sg_roi_check_geometry(), sg_roi_clamp(), sg_roi_contains(), sg_roi_distance(), sg_roi_fix_geometry(), sg_roi_flip_y(), sg_roi_overlaps(), sg_roi_rescale(), sg_roi_ring(), sg_roi_rois_overlap(), sg_roi_setops, sg_roi_simplify(), sg_roi_snap(), sg_roi_transform()

Examples

sg_roi_buffer(sg_roi_point(10, 10, label = "a"), dist = 5)

Description

ROI centroid

Usage

sg_roi_centroid(roi, call = rlang::caller_env())

Arguments

Value

A numeric vector c(x, y) in the ROI's stored coordinates (at its own level).

See Also

Other rois: sg_roi_area(), sg_roi_bbox(), sg_roi_circle(), sg_roi_ellipse(), sg_roi_freehand(), sg_roi_from_geojson(), sg_roi_from_sf(), sg_roi_point(), sg_roi_polygon(), sg_roi_rect()

Examples

sg_roi_centroid(sg_roi_rect(0, 0, 10, 10, label = "a"))

Description

Report ROIs in a constrained layer that fall outside their container region. A layer declares the constraint through its metadata, e.g. sg_roi_layer("state", within = list(layer = "anatomy", label = "wound")); then every ROI in state must be spatially covered by the union of the anatomy layer's wound ROIs. This enforces the annotation rule that a class is painted only inside its region of interest. The report mirrors the shape of sg_roi_check_geometry().

Usage

sg_roi_check_containment(project, tol = 0, call = rlang::caller_env())

Arguments

Value

A tibble::tibble with columns roi_id, layer, issue, severity ("warning" for an ROI outside its container, "error" for a missing/empty container), and fixable (always FALSE). A 0-row tibble when every constrained ROI is contained, or when no layer declares a within constraint.

See Also

sg_roi_check_geometry(), sg_roi_validate()

Other geometry: sg_roi_buffer(), sg_roi_check_geometry(), sg_roi_clamp(), sg_roi_contains(), sg_roi_distance(), sg_roi_fix_geometry(), sg_roi_flip_y(), sg_roi_overlaps(), sg_roi_rescale(), sg_roi_ring(), sg_roi_rois_overlap(), sg_roi_setops, sg_roi_simplify(), sg_roi_snap(), sg_roi_transform()

Examples

anatomy <- sg_roi_layer_add(sg_roi_layer("anatomy", labels = "wound"),
                        sg_roi_rect(2, 2, 8, 8, label = "wound"))
state <- sg_roi_layer("state", labels = "injury",
                  within = list(layer = "anatomy", label = "wound"))
state <- sg_roi_layer_add(state, sg_roi_rect(0, 0, 4, 4, label = "injury"))
sg_roi_check_containment(sg_roi_project(sg_roi_frame(c(100, 100)), list(anatomy, state)))

Description

Check the geometry of every ROI in a project

Usage

sg_roi_check_geometry(project, call = rlang::caller_env())

Arguments

Value

A tibble::tibble with columns roi_id (character), issue (character), severity (character, "error"/"warning"), and fixable (logical). Detected issues: self-intersection, invalid geometry, zero area, degenerate rings, out-of-bounds vertices, duplicate consecutive vertices, ring orientation, and NA coordinates. A 0-row tibble when all geometry is valid.

See Also

sg_roi_fix_geometry(), sg_roi_validate()

Other geometry: sg_roi_buffer(), sg_roi_check_containment(), sg_roi_clamp(), sg_roi_contains(), sg_roi_distance(), sg_roi_fix_geometry(), sg_roi_flip_y(), sg_roi_overlaps(), sg_roi_rescale(), sg_roi_ring(), sg_roi_rois_overlap(), sg_roi_setops, sg_roi_simplify(), sg_roi_snap(), sg_roi_transform()

Examples

lyr <- sg_roi_layer_add(sg_roi_layer("tissue"),
                        sg_roi_rect(2, 2, 8, 8, label = "tissue"))
proj <- sg_roi_project(sg_roi_frame(c(20, 20)), lyr)
sg_roi_check_geometry(proj)

Description

The circle is approximated by a regular polygon of n_seg segments.

Usage

sg_roi_circle(
  x,
  y,
  r,
  label,
  level = 0L,
  n_seg = 64L,
  ...,
  call = rlang::caller_env()
)

Arguments

Value

An sg_roi with POLYGON geometry and attributes$shape = "circle", so exports can flag the polygon as an approximation.

See Also

Other rois: sg_roi_area(), sg_roi_bbox(), sg_roi_centroid(), sg_roi_ellipse(), sg_roi_freehand(), sg_roi_from_geojson(), sg_roi_from_sf(), sg_roi_point(), sg_roi_polygon(), sg_roi_rect()

Examples

r <- sg_roi_circle(50, 50, r = 10, label = "nucleus")

Description

Clip an ROI to image bounds

Usage

sg_roi_clamp(roi, dims, call = rlang::caller_env())

Arguments

Value

An sg_roi clipped to ⁠[0, width] x [0, height]⁠. Warns if the clip empties the geometry.

See Also

Other geometry: sg_roi_buffer(), sg_roi_check_containment(), sg_roi_check_geometry(), sg_roi_contains(), sg_roi_distance(), sg_roi_fix_geometry(), sg_roi_flip_y(), sg_roi_overlaps(), sg_roi_rescale(), sg_roi_ring(), sg_roi_rois_overlap(), sg_roi_setops, sg_roi_simplify(), sg_roi_snap(), sg_roi_transform()

Examples

sg_roi_clamp(sg_roi_rect(-5, -5, 20, 20, label = "a"), dims = c(10, 10))

Description

Test whether points fall inside an ROI

Usage

sg_roi_contains(roi, x, y, call = rlang::caller_env())

Arguments

Value

A logical vector of length length(x).

See Also

Other geometry: sg_roi_buffer(), sg_roi_check_containment(), sg_roi_check_geometry(), sg_roi_clamp(), sg_roi_distance(), sg_roi_fix_geometry(), sg_roi_flip_y(), sg_roi_overlaps(), sg_roi_rescale(), sg_roi_ring(), sg_roi_rois_overlap(), sg_roi_setops, sg_roi_simplify(), sg_roi_snap(), sg_roi_transform()

Examples

sg_roi_contains(sg_roi_rect(0, 0, 10, 10, label = "a"), c(5, 20), c(5, 20))