Package 'hyperannotatR'

Description

Add a layer to a project

Usage

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

Arguments

Value

A new annot_project with the layer added. ROIs in layer whose identifiers are missing, already used in the project, or repeated within the layer are re-minted; the first occurrence of each valid id is kept. The input is unchanged.

See Also

Other projects: at_add_roi(), at_example_project(), at_layers(), at_project(), at_remove_layer(), at_remove_roi(), at_rois(), at_summary(), at_validate()

Description

Add an ROI to a project layer

Usage

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

Arguments

Value

A new annot_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: at_add_layer(), at_example_project(), at_layers(), at_project(), at_remove_layer(), at_remove_roi(), at_rois(), at_summary(), at_validate()

Description

A launcher around at_app(): it builds the app object from explicit arguments and runs it. Nothing is exchanged through global options.

Usage

at_annotate(
  x = NULL,
  labels = character(),
  layers = NULL,
  out_dir = NULL,
  launch.browser = TRUE,
  port = NULL,
  ...,
  call = rlang::caller_env()
)

Arguments

Value

Invisible NULL. Launches a Shiny application; called for side effects.

See Also

at_app()

Other shiny: atCanvasOutput(), at_app(), at_canvas(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Examples

if (interactive()) {
  at_annotate(at_example_session(5))
}

Description

A content revision for annotations: the SHA-256 of the canonical record of every layer (name, labels, colours, z-order, visibility, lock) and ROI (id, layer, label, level, geometry WKB, source, lock, review status, plane and attributes). It changes whenever annotation content changes and is independent of timestamps, authors, file paths and pixel data. Partners pass it back as expected_revision to detect stale patches.

Usage

at_annotation_revision(x, call = rlang::caller_env())

Arguments

Value

A single string "sha256:<64 hex>".

See Also

Other interop: at_commit_qupflowr(), at_export_qupflowr(), at_import_qupflowr(), at_interop_capabilities(), at_interop_manifest(), at_stage_qupflowr()

Examples

proj <- at_project(at_example_image("cube"))
at_annotation_revision(proj)

Description

Construct the batch annotation application from explicit inputs, without launching a browser or touching global options. The result can be run with shiny::runApp(), embedded in another Shiny application, or exercised in tests; at_annotate() is a launcher around it.

Usage

at_app(
  input = NULL,
  session = NULL,
  control = "off",
  labels = character(),
  layers = NULL,
  out_dir = NULL,
  read_only = FALSE,
  view = NULL,
  ...,
  call = rlang::caller_env()
)

Arguments

Details

All Shiny sessions of one app object share its in-memory queue: reloading the page or opening a second tab continues from the latest edits instead of the session the app was built with. Edits are stored per queue entry; two tabs editing the same image keep the last edit.

Annotations autosave to the session's out_dir (unless the session was created with autosave = FALSE); the app warns when that folder is inside R's temporary directory, which is deleted when R exits. Before it first replaces an existing ⁠_session.rds⁠ that holds another queue or more ROIs, the app keeps a timestamped ⁠_session-*.previous.rds⁠ copy.

The Data page reads folder and handoff paths on the machine running R. The app is meant for local use. Set options(hyperannotatR.app_root = "/allowed/folder") to restrict canonical image paths and known ENVI/TIVITA companions to that folder. This is not an operating-system sandbox: custom readers, external references and concurrent filesystem changes need separate controls in a shared deployment.

Value

A shiny.appobj.

See Also

at_annotate(), at_control_start()

Other shiny: atCanvasOutput(), at_annotate(), at_canvas(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Examples

app <- at_app(input = at_example_path("cube"))
class(app)
## Not run: 
shiny::runApp(app)

## End(Not run)

Description

Detect the backend for a file

Usage

at_backend_detect(path, call = rlang::caller_env())

Arguments

Value

The name of the first available backend (in priority order) that can read path. Errors informatively if none can.

See Also

Other backends: at_backend_get(), at_backend_list(), at_backend_register(), at_close_image(), at_cubert_export_envi(), at_image_capabilities(), at_read_image(), at_tile(), at_tivita_profile()

Description

Get a registered backend

Usage

at_backend_get(name, call = rlang::caller_env())

Arguments

Value

The annot_backend object.

See Also

Other backends: at_backend_detect(), at_backend_list(), at_backend_register(), at_close_image(), at_cubert_export_envi(), at_image_capabilities(), at_read_image(), at_tile(), at_tivita_profile()

Description

List registered image backends

Usage

at_backend_list(call = rlang::caller_env())

Arguments

Value

A tibble::tibble with columns name (character), description (character), extensions (character, comma-separated), and available (logical), plus metadata_only and window_read (logical; NA when unknown). A 0-row tibble with these columns when nothing is registered.

See Also

Other backends: at_backend_detect(), at_backend_get(), at_backend_register(), at_close_image(), at_cubert_export_envi(), at_image_capabilities(), at_read_image(), at_tile(), at_tivita_profile()

Examples

at_backend_list()

Description

Backends are how hyperannotatR reads image formats. Each supplies functions to read an image's metadata, fetch tiles, detect whether it can read a file, and report whether its optional dependencies are installed.

Usage

at_backend_register(
  name,
  read_fn,
  tile_fn,
  detect_fn,
  available_fn,
  description = "",
  extensions = character(),
  call = rlang::caller_env(),
  capabilities = list(metadata_only = NA, window_read = NA, samples = "unqualified", io =
    "unknown"),
  close_fn = NULL
)

Arguments

Value

The registered annot_backend, invisibly.

See Also

at_backend_list(), at_read_image()

Other backends: at_backend_detect(), at_backend_get(), at_backend_list(), at_close_image(), at_cubert_export_envi(), at_image_capabilities(), at_read_image(), at_tile(), at_tivita_profile()

Description

List the display band operations the app and the control service accept. Derived views are display products: they carry their parent digest, band list, operation and parameters, and are never written back as analysis input.

Usage

at_band_operations()

Value

A tibble::tibble with columns operation, n_bands (integer; NA means one or more), params (comma-separated parameter names) and description.

See Also

Other hsi: at_band_view(), at_convert_values(), at_cubert_export_envi(), at_hsi_meta(), at_read_stats(), at_tivita_profile()

Examples

at_band_operations()

Description

Evaluate one of at_band_operations() on a window of an image. The result is a display product: a ⁠[y, x, k]⁠ array (k = 3 for "rgb", otherwise 1) with provenance attributes, which hyperannotatR never uses as analysis input.

Usage

at_band_view(
  img,
  operation = "rgb",
  bands = NULL,
  params = list(),
  level = 0L,
  xrange = NULL,
  yrange = NULL,
  call = rlang::caller_env()
)

Arguments

Value

A numeric array with attributes operation, bands, wavelengths, params, parent_digest, transform_digest, level and display_product = TRUE.

See Also

Other hsi: at_band_operations(), at_convert_values(), at_cubert_export_envi(), at_hsi_meta(), at_read_stats(), at_tivita_profile()

Examples

cube <- at_example_image("cube")
v <- at_band_view(cube, "normalized_difference", bands = c(30, 10))
attr(v, "operation")

Description

Band (channel) table

Usage

at_bands(x, call = rlang::caller_env())

Arguments

Value

A tibble::tibble with one row per band and the columns:

index

Band index, 1-based (integer).

name

Band name (character); a default "Band k" when unnamed.

wavelength

Centre wavelength (double); NA when not spectral or unknown for that band. Never interpolated.

unit

Declared spectral coordinate unit (character); NA when not spectral or when the unit is unknown. Scalar metadata applies to all bands; per-band units are preserved without conversion.

fwhm

Full width at half maximum in the wavelength unit (double); NA when the source does not declare it.

order

Position of the band in file/manifest order (integer).

wavelength_status

"ok", "missing", "duplicate" or "non_numeric" (character).

Always has at_n_bands(x) rows. The first four columns are unchanged from hyperannotatR 0.1; the remaining columns were added in 0.2.0.

See Also

Other images: at_close_image(), at_dims(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Description

Apply a function to every project in a session

Usage

at_batch_apply(
  session,
  fn,
  ...,
  scope = "all",
  progress = TRUE,
  call = rlang::caller_env()
)

Arguments

Value

The annot_session with modified projects. An image whose project cannot be materialised, or for which fn errors or does not return an annot_project, keeps its previous project; the failures are reported in one warning and attached as the "batch_errors" attribute, a tibble::tibble with columns idx, image and message.

See Also

Other batch: at_batch_check_geometry(), at_export_all(), at_summary_table()

Description

Run at_check_geometry() on every materialised project in the session and stack the reports. Like at_check_geometry() (and unlike the assertion at_validate()), this returns a report rather than throwing.

Usage

at_batch_check_geometry(session, call = rlang::caller_env())

Arguments

Value

A tibble::tibble with columns image, roi_id, issue, and severity. A 0-row tibble when all geometry is valid.

See Also

at_check_geometry()

Other batch: at_batch_apply(), at_export_all(), at_summary_table()

Description

The canvas shows one embedded, downsampled image with the project's ROIs drawn in their label colours (hidden layers are left out; locked layers cannot be erased or moved on the canvas). It pans with a drag and zooms with the mouse wheel or a two-finger pinch. When no image can be shown, it says why instead of keeping a previous image.

Usage

at_canvas(
  img,
  project = NULL,
  tool = "pan",
  width = NULL,
  height = NULL,
  elementId = NULL,
  options = list(),
  view = NULL,
  call = rlang::caller_env()
)

Arguments

Value

An htmlwidget object.

Shiny inputs

In Shiny, the canvas with output id id sends these inputs. Each value is a list entry_id, revision, payload: the identity rendered when the gesture began (the project's meta$entry_id and meta$annotation_revision, or the element id and 0 for a project without them) and the event data. A render or at_canvas_set_annotations() with a different identity cancels unfinished gestures, and stale events are never sent.

⁠<id>_created⁠

A drawn GeoJSON feature in level-0 pixels; target holds options$creationTarget (layer, label) as it was when the drawing began. A click with the rectangle or circle tool is not a shape.

⁠<id>_edited⁠

roi_id, layer, label and the moved geometry (sent only after an actual drag).

⁠<id>_erased⁠

The erased ROI id.

⁠<id>_selected⁠

The ids of the selected ROIs (possibly none).

⁠<id>_probed⁠

x, y: the probed level-0 pixel position.

⁠<id>_reflection_seed⁠

x, y and target: a clicked pixel for a reflection proposal. It does not create an ROI.

⁠<id>_viewport⁠

zoom, center_x, center_y and bounds (xmin, ymin, xmax, ymax in level-0 pixels) after a pan or zoom.

⁠<id>_ready⁠

ready and error: whether the image is displayed.

A drawn or moved shape is shown dashed until new annotations arrive, and disappears after a few seconds if none do, so the canvas does not keep showing an ROI the app did not accept.

See Also

at_canvas_proxy(), at_tile_source()

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Examples

at_canvas(at_example_image("tissue"))

Description

Zoom the canvas to a bounding box

Usage

at_canvas_fit(proxy, bbox = NULL, call = rlang::caller_env())

Arguments

Value

The proxy, invisibly.

See Also

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Description

Mirrors the leafletProxy() pattern: update a live canvas without re-rendering the whole widget. Inside a Shiny module, pass the module's (un-namespaced) output id; it is namespaced with the module session, as leaflet::leafletProxy() does.

Usage

at_canvas_proxy(id, session = shiny::getDefaultReactiveDomain())

Arguments

Value

An atcanvas_proxy object.

See Also

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas(), at_canvas_fit(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Description

Replace the annotations on a canvas

Usage

at_canvas_set_annotations(
  proxy,
  project,
  layer = NULL,
  call = rlang::caller_env()
)

Arguments

Value

The proxy, invisibly.

See Also

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Description

Retained for API compatibility; it has no visible effect on the built-in canvas. The canvas shows one embedded image rendered in R, and cannot recompute bands in the browser. To change the displayed bands, re-render the widget with a view (see at_canvas() and at_band_view()), as the annotation app does.

Usage

at_canvas_set_band(proxy, band, call = rlang::caller_env())

Arguments

Value

The proxy, invisibly.

See Also

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_overlay(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Description

Overlay a mask on the canvas

Usage

at_canvas_set_overlay(proxy, mask, alpha = 0.5, call = rlang::caller_env())

Arguments

Value

The proxy, invisibly.

See Also

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_selection(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Description

Highlight selected ROIs on a canvas

Usage

at_canvas_set_selection(
  proxy,
  roi_ids = character(),
  call = rlang::caller_env()
)

Arguments

Value

The proxy, invisibly.

See Also

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_tool(), at_tile_source(), renderAtCanvas()

Description

Set the active drawing tool

Usage

at_canvas_set_tool(proxy, tool, call = rlang::caller_env())

Arguments

Value

The proxy, invisibly.

See Also

Other shiny: atCanvasOutput(), at_annotate(), at_app(), at_canvas(), at_canvas_fit(), at_canvas_proxy(), at_canvas_set_annotations(), at_canvas_set_band(), at_canvas_set_overlay(), at_canvas_set_selection(), at_tile_source(), renderAtCanvas()

Description

Report ROIs in a constrained layer that fall outside their container region. A layer declares the constraint through its metadata, e.g. at_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 at_check_geometry().

Usage

at_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

at_check_geometry(), at_validate()

Other geometry: at_check_geometry(), at_clamp(), at_fix_geometry(), at_flip_y(), at_roi_buffer(), at_roi_contains(), at_roi_distance(), at_roi_overlaps(), at_roi_rescale(), at_roi_ring(), at_roi_setops, at_roi_simplify(), at_rois_overlap(), at_snap(), at_transform()

Examples

anatomy <- at_layer_add(at_layer("anatomy", labels = "wound"),
                        at_roi_rect(2, 2, 8, 8, label = "wound"))
state <- at_layer("state", labels = "injury",
                  within = list(layer = "anatomy", label = "wound"))
state <- at_layer_add(state, at_roi_rect(0, 0, 4, 4, label = "injury"))
at_check_containment(at_project(at_example_image("cube"), list(anatomy, state)))

Description

Check the geometry of every ROI in a project

Usage

at_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, NA coordinates, empty geometry, and a pyramid level the image does not have (level_out_of_range). A 0-row tibble when all geometry is valid.

See Also

at_fix_geometry(), at_validate()

Other geometry: at_check_containment(), at_clamp(), at_fix_geometry(), at_flip_y(), at_roi_buffer(), at_roi_contains(), at_roi_distance(), at_roi_overlaps(), at_roi_rescale(), at_roi_ring(), at_roi_setops, at_roi_simplify(), at_rois_overlap(), at_snap(), at_transform()

Examples

at_check_geometry(at_example_project())

Description

Clip an ROI to image bounds

Usage

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

Arguments

Value

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

See Also

Other geometry: at_check_containment(), at_check_geometry(), at_fix_geometry(), at_flip_y(), at_roi_buffer(), at_roi_contains(), at_roi_distance(), at_roi_overlaps(), at_roi_rescale(), at_roi_ring(), at_roi_setops, at_roi_simplify(), at_rois_overlap(), at_snap(), at_transform()

Examples

at_clamp(at_roi_rect(-5, -5, 20, 20, label = "a"), dims = c(10, 10))

Description

Drop an image's runtime pixel handle, calling the backend's close_fn when it declares one.

Usage

at_close_image(x)

Arguments

Value

The image or project with its runtime handle released; assign the result. Later tile requests reopen the image from its source. Releasing a retained pixel snapshot loses those pixels when the source has changed or cannot be reopened. Built-in window readers open a connection per read and hold no persistent connection.

See Also

Other images: at_bands(), at_dims(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Other backends: at_backend_detect(), at_backend_get(), at_backend_list(), at_backend_register(), at_cubert_export_envi(), at_image_capabilities(), at_read_image(), at_tile(), at_tivita_profile()

Examples

cube <- at_close_image(at_example_image("cube"))
dim(at_tile(cube, xrange = c(1, 4), yrange = c(1, 4), bands = 1))

Description

Apply an at_stage_qupflowr() patch. Conflicting operations are never applied. The commit is idempotent: repeating it with the same idempotency_key and the same patch returns the original receipt without applying anything again, while the same key with a different patch aborts with IDEMPOTENCY_CONFLICT. When the patch targets a saved project file (or destination names one), the file is re-read and its revision re-checked immediately before writing; an existing file is only replaced with overwrite = TRUE. A ⁠<file>.commit.json⁠ receipt records the key across R sessions. The project and receipt are staged together; a failed publication restores both previous files, or reports retained recovery backups if restoration also fails. Writers to the same destination must be serialised; this is not a cross-file transaction against process or machine failure. A replay aborts with REVISION_CONFLICT if the saved project has changed since that receipt was written. Reusing a cached key for a different destination aborts with IDEMPOTENCY_CONFLICT.

Usage

at_commit_qupflowr(
  x,
  idempotency_key = NULL,
  destination = NULL,
  overwrite = FALSE,
  call = rlang::caller_env()
)

Arguments

Value

An at_commit_receipt: a list with state = "committed", patch_id, idempotency_key, previous_revision, new_revision, applied and conflicts (operation tibbles), project, written (path or NA), committed_at and replayed.

See Also

at_stage_qupflowr()

Other interop: at_annotation_revision(), at_export_qupflowr(), at_import_qupflowr(), at_interop_capabilities(), at_interop_manifest(), at_stage_qupflowr()

Examples

proj <- at_example_project()
partner <- at_layer_add(at_layer("regions"), at_roi_rect(10, 10, 40, 40, label = "tumour",
                                                         id = "partner-1"))
rc <- at_commit_qupflowr(at_stage_qupflowr(proj, partner))
rc$new_revision

Description

Describe the annotatr-control-v1 protocol this hyperannotatR version speaks, without starting anything: endpoints, typed operations, limits, security rules and the digests of the shipped JSON Schemas. A client compares this (or the ⁠/v1/handshake⁠ response) with its own expectations before sending commands.

Usage

at_control_capabilities()

Value

A list with protocol, protocol_version, annotatr_version, status (see at_interop_capabilities()), endpoints, operations, limits, security, schemas (file name -> SHA-256) and digest.

See Also

at_control_start(), at_control_command()

Other control: at_control_close(), at_control_command(), at_control_connect(), at_control_events(), at_control_request_status(), at_control_start(), at_control_state(), at_control_stop()

Examples

cc <- at_control_capabilities()
cc$operations

Description

Close the control service a handle refers to. For a local handle this is at_control_stop(); for a remote handle it sends POST /v1/close, after which that service stops accepting requests while its host process and any app keep running. Neither path terminates a process. A close is not revision-checked, so concurrent edits in an attached app never make it fail; unsaved app edits stay in the app.

Usage

at_control_close(handle, call = rlang::caller_env())

Arguments

Value

The close response (remote) or TRUE (local), invisibly.

See Also

Other control: at_control_capabilities(), at_control_command(), at_control_connect(), at_control_events(), at_control_request_status(), at_control_start(), at_control_state(), at_control_stop()

Description

Send one annotatr-control-v1 operation. The command is a list with operation (one of at_control_capabilities()⁠$operations⁠), payload (a list) and expected_revision (the state_revision the command is based on). request_id and idempotency_key are generated when absent and content_sha256 is always computed from the canonical payload. A stale revision raises an at_conflict_error (REVISION_CONFLICT); re-sending the same command with the same idempotency key returns the original result (replayed = TRUE in the response) instead of applying it twice. The service keeps the most recent 1000 request records; a replay of an older key raises IDEMPOTENCY_EXPIRED instead of executing again, and a large stored response (for example a mask preview PNG) is replayed in compact form with response_truncated = TRUE. close is the only operation that does not check expected_revision. Errors carry the same condition class as the corresponding local call.

Usage

at_control_command(handle, command, call = rlang::caller_env())

Arguments

Value

The response data (a list) with the response envelope in attr(, "response").

See Also

at_control_request_status()

Other control: at_control_capabilities(), at_control_close(), at_control_connect(), at_control_events(), at_control_request_status(), at_control_start(), at_control_state(), at_control_stop()

Examples

sess <- at_session(rep(at_example_path("cube"), 3))
h <- at_control_start(sess, serve = FALSE)
st <- at_control_state(h)
at_control_command(h, list(operation = "context.goto", payload = list(queue_index = 2),
                           expected_revision = st$state_revision))
at_control_stop(h)

Description

Build a remote handle for a control service started in another R process, from its lifecycle manifest and token file. The handshake is checked before the handle is returned: protocol, major version and instance id must match the manifest.

Usage

at_control_connect(manifest, token_file, call = rlang::caller_env())

Arguments

Value

An at_control_handle of kind "remote".

See Also

Other control: at_control_capabilities(), at_control_close(), at_control_command(), at_control_events(), at_control_request_status(), at_control_start(), at_control_state(), at_control_stop()

Description

Read control events after a cursor

Usage

at_control_events(
  handle,
  after = NULL,
  limit = 100L,
  call = rlang::caller_env()
)

Arguments

Value

A list with events, next_cursor, resync_required, has_more and state_revision.

See Also

Other control: at_control_capabilities(), at_control_close(), at_control_command(), at_control_connect(), at_control_request_status(), at_control_start(), at_control_state(), at_control_stop()

Description

After a lost response, ask the service what happened to a request id. An unknown id raises REQUEST_NOT_FOUND and has no side effect.

Usage

at_control_request_status(handle, request_id, call = rlang::caller_env())

Arguments

Value

The request record: request_id, operation, status ("completed" or "failed"), http_status, timestamps, extensions and the stored response.

See Also

Other control: at_control_capabilities(), at_control_close(), at_control_command(), at_control_connect(), at_control_events(), at_control_start(), at_control_state(), at_control_stop()

Description

Start an annotatr-control-v1 service for a session so that a partner process (for example qupflowR) can read state and events and send typed commands. Nothing is started unless this function is called with control = "loopback". The service binds only to ⁠127.0.0.1⁠, requires a random 256-bit bearer token that expires after ttl_seconds, rejects browser-origin requests, enforces JSON size and path limits, and resolves file references only below root. There is no endpoint that evaluates code.

Usage

at_control_start(
  session,
  control = "loopback",
  host = "127.0.0.1",
  port = 0L,
  ttl_seconds = 900L,
  root = NULL,
  token_file = NULL,
  read_only = FALSE,
  max_body_bytes = 1048576L,
  serve = TRUE,
  call = rlang::caller_env()
)

Arguments

Details

The token is never written into URLs, logs, downloads, manifests or RDS files. In-process calls use the returned handle; a separate client process reads the token from token_file, which is created exclusively with owner-only permissions (on Windows, file modes are not enforced; keep the file in a directory only the user can read). A sanitised lifecycle manifest ⁠annotatr-control-<instance_id>.json⁠ is written to root at start and rewritten when the service stops. If startup fails, its listener, expiry timer, registry entries and newly created token file are removed.

The service stops itself when the token expires: either when the expiry timer runs or, if a request arrives first (for example after the computer slept), on that request. Error messages sent to clients never contain absolute local paths. Request bodies whose declared Content-Length exceeds max_body_bytes, and requests that fail the Host, Origin or token checks, are refused before the body is read (a chunked body without Content-Length is buffered by httpuv and then refused).

Two options bound work done for clients: hyperannotatR.control_mask_max_pixels (default 4096^2) is the largest mask mask.preview builds (without a level it picks the finest pyramid level within the budget), and hyperannotatR.control_hash_max_bytes (default 256 MiB) is the largest queue entry whose content id GET /v1/state computes before the entry is visited (larger entries report image_id: null until then).

Value

An at_control_handle (a list with kind = "local", instance_id, session_id, host, port, pid, manifest, expires_at); its print method never shows the token.

See Also

at_control_stop(), at_control_command(), at_app()

Other control: at_control_capabilities(), at_control_close(), at_control_command(), at_control_connect(), at_control_events(), at_control_request_status(), at_control_state(), at_control_stop()

Examples

sess <- at_session(rep(at_example_path("cube"), 2))
h <- at_control_start(sess, serve = FALSE)
at_control_state(h)$state_revision
at_control_stop(h)

Description

Read the state of a control service

Usage

at_control_state(handle, call = rlang::caller_env())

Arguments

Value

The state snapshot (a list) with state_revision, event_cursor, queue, current (image, layers, ROI summaries, annotation revision), view, selection, staged, last_commit and status fields.

See Also

Other control: at_control_capabilities(), at_control_close(), at_control_command(), at_control_connect(), at_control_events(), at_control_request_status(), at_control_start(), at_control_stop()

Description

Stop a service started by at_control_start() in this R process: close the listener, invalidate its token and rewrite its lifecycle manifest as stopped. A handle from another process (or a remote handle from at_control_connect()) is refused with an at_auth_error (NOT_OWNER); no process is ever terminated.

Usage

at_control_stop(handle, call = rlang::caller_env())

Arguments

Value

TRUE invisibly when the service was stopped, FALSE if it had already stopped.

See Also

Other control: at_control_capabilities(), at_control_close(), at_control_command(), at_control_connect(), at_control_events(), at_control_request_status(), at_control_start(), at_control_state()

Description

The only supported ways to change value semantics. Raw counts become reflectance through an explicit dark/white calibration, and reflectance becomes (pseudo-)absorbance as -log10(reflectance). Anything else, or a conversion without the calibration it needs, is refused with a classified error instead of being approximated.

Usage

at_convert_values(
  x,
  from = NULL,
  to = c("reflectance", "absorbance"),
  calibration = NULL,
  call = rlang::caller_env()
)

Arguments

Value

x converted, with attribute value_unit set to to and conversion recording the operation. Reflectance values ⁠<= 0⁠ give NA absorbance; a zero white-minus-dark denominator gives NA.

See Also

Other hsi: at_band_operations(), at_band_view(), at_cubert_export_envi(), at_hsi_meta(), at_read_stats(), at_tivita_profile()

Examples

at_convert_values(c(0.5, 0.1), from = "reflectance", to = "absorbance")
at_convert_values(c(100, 550, 1000), from = "raw", to = "reflectance",
                  calibration = list(white = 1000, dark = 100))

Description

The portable fallback for Cubert data: the CUVIS SDK itself writes an ENVI export, which hyperannotatR (and tools without the SDK) can then read through the envi backend. Requires cuvis.r and a usable CUVIS SDK.

Usage

at_cubert_export_envi(path, dir, measurement = 1L, call = rlang::caller_env())

Arguments

Value

The files written into dir (character), invisibly.

See Also

Other backends: at_backend_detect(), at_backend_get(), at_backend_list(), at_backend_register(), at_close_image(), at_image_capabilities(), at_read_image(), at_tile(), at_tivita_profile()

Other hsi: at_band_operations(), at_band_view(), at_convert_values(), at_hsi_meta(), at_read_stats(), at_tivita_profile()

Examples

## Not run: 
at_cubert_export_envi("measurement.cu3s", tempfile("envi-"))

## End(Not run)

Description

Return the project for the image at the cursor, materialising it from the image (and applying the session's layer template) if it has not been visited. A stored project whose pixel handle was not saved is reopened from its recorded source (see at_inspect_source() when that is impossible).

Usage

at_current(session, call = rlang::caller_env())

Arguments

Value

An annot_project.

See Also

Other sessions: at_example_session(), at_goto(), at_manifest(), at_next(), at_prev(), at_resume(), at_session(), at_session_status(), at_set_status()

Description

Return the pixel dimensions c(width, height) of an annot_image at a given pyramid level.

Usage

at_dims(x, level = 0L, call = rlang::caller_env())

## S3 method for class 'annot_image'
dim(x)

Arguments

Details

dim() on an annot_image returns c(width, height, bands) at level 0. Note the order: width first, unlike the ⁠[y, x, band]⁠ arrays returned by at_tile(), so nrow() gives the width.

Value

An integer vector of length 2, c(width, height).

See Also

at_n_levels(), at_is_pyramidal()

Other images: at_bands(), at_close_image(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Examples

# Image handles come from at_read_image(); see the images vignette.

Description

Read a bundled example image

Usage

at_example_image(
  which = c("tissue", "multiplex", "cube"),
  call = rlang::caller_env()
)

Arguments

Details

The tissue example is a PNG and needs magick; the multiplex example needs tiff; the cube needs nothing beyond hyperannotatR.

Value

An annot_image.

See Also

Other example data: at_example_path(), at_example_project(), at_example_session()

Other images: at_bands(), at_close_image(), at_dims(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Examples

img <- at_example_image("cube")
at_dims(img)

Description

Path to a bundled example file

Usage

at_example_path(
  which = c("tissue", "multiplex", "cube"),
  call = rlang::caller_env()
)

Arguments

Value

A single string file path to the example asset.

See Also

Other example data: at_example_image(), at_example_project(), at_example_session()

Examples

at_example_path("tissue")

Description

A populated example project

Usage

at_example_project(call = rlang::caller_env())

Arguments

Value

An annot_project over the tissue example with one layer of three labelled regions.

See Also

Other example data: at_example_image(), at_example_path(), at_example_session()

Other projects: at_add_layer(), at_add_roi(), at_layers(), at_project(), at_remove_layer(), at_remove_roi(), at_rois(), at_summary(), at_validate()

Examples

proj <- at_example_project()
at_rois(proj)

Description

Copies the tissue example into a temporary directory n times so the queue has real files to iterate.

Usage

at_example_session(n = 5L, call = rlang::caller_env())

Arguments

Value

An annot_session.

See Also

Other example data: at_example_image(), at_example_path(), at_example_project()

Other sessions: at_current(), at_goto(), at_manifest(), at_next(), at_prev(), at_resume(), at_session(), at_session_status(), at_set_status()

Examples

sess <- at_example_session(3)
at_session_status(sess)

Description

Export every selected image's annotations in the requested formats, isolating per-image failures so one bad image never aborts the run.

Usage

at_export_all(
  session,
  dir,
  formats = c("mask_tiff", "geojson", "qupath", "rds", "csv"),
  scope = c("complete", "all", "current", "flagged"),
  mask_type = c("labelled", "binary", "multiclass"),
  level = 0L,
  overwrite = FALSE,
  progress = TRUE,
  call = rlang::caller_env()
)

Arguments

Details

Derived filenames use safe portable components; display names stay in the receipt and annotation metadata. Case-folded collisions are given deterministic suffixes, including cross-format and sidecar collisions. The complete plan (including manifests) rejects descendant symlinks before writing outputs. Existing mask/legend bundles are skipped as a whole unless overwrite=TRUE. Files are staged and publication failures roll back prior files. Callers must serialize concurrent exports and avoid changing the destination filesystem during a run: preflight and multiple renames are not a race-free filesystem transaction. Receipt files are replaced each run, independently of the item overwrite policy.

Value

An invisible export-receipt tibble::tibble with columns entry_id, image, format, path, bytes, n_rois, status, and message. Also written to ⁠_export_manifest.csv⁠ alongside the exports. Additive columns sidecar_path and sidecar_bytes describe mask legends. Byte counts are doubles. Status is "ok" for a complete published bundle, "error" for a failed item, or "skipped" when an existing bundle is protected. Every image-format request has a row, even if loading the image fails. Receipt publication or annotation-summary failures warn and are also retained in receipt_error / summary_error attributes; the item receipt is returned.

See Also

at_write_masks(), at_manifest()

Other batch: at_batch_apply(), at_batch_check_geometry(), at_summary_table()

Examples

sess <- at_example_session(2)
dir <- file.path(tempdir(), "hyperannotatR-export")
at_export_all(sess, dir, formats = "geojson", scope = "all", progress = FALSE)

Description

Write a new, self-contained handoff directory for a partner package such as qupflowR. It contains only neutral, relative files: image.json, annotations_qupath.geojson (QuPath 0.4+ dialect), optionally annotations.geojson, one integer mask per layer under ⁠masks/⁠ with a .legend.json sidecar, optional tables/rois.csv, an optional hyperannotatR-internal objects/project.rds, hsi_manifest.json for spectral images, manifest.json (at_interop_manifest()) and integrity.json, the SHA-256 inventory of every other file. The handoff digest is the SHA-256 of the canonical integrity.json. Absolute paths are never used as identity.

Usage

at_export_qupflowr(
  x,
  destination,
  formats = c("qupath_geojson", "mask_tiff", "manifest"),
  overwrite = FALSE,
  level = 0L,
  mask_type = c("labelled", "multiclass", "binary"),
  scope = c("all", "current", "complete"),
  call = rlang::caller_env()
)

Arguments

Details

Files are written into a hidden sibling staging directory and moved into place only when complete, so a failed export never leaves a directory that looks valid. An existing destination is replaced only with overwrite = TRUE, and only when it is itself a handoff directory; if the new directory cannot be moved into place the previous one is restored. The optional objects/project.rds holds no pixels, read identity or local path (the image source is reduced to its file name).

Value

An at_handoff_receipt (invisibly): a list with destination, handoff_digest, files (a tibble of path, size_bytes, sha256, format, role, entry_id), manifest, skipped entries and overwritten.

See Also

at_import_qupflowr(), at_interop_manifest()

Other interop: at_annotation_revision(), at_commit_qupflowr(), at_import_qupflowr(), at_interop_capabilities(), at_interop_manifest(), at_stage_qupflowr()

Examples

dest <- file.path(tempdir(), "handoff-example")
rc <- at_export_qupflowr(at_example_project(), dest, overwrite = TRUE)
rc$handoff_digest
rc$files[, c("path", "format")]

Description

Compute per-band summary statistics of image values inside each ROI. Reads one tile covering each ROI's clipped bounding box; an image-sized bounding box can allocate an image-sized tile. Polygon centre membership and point containing cells follow the pixel-coverage contract in at_mask(). For example, point ⁠(5, 5)⁠ selects matrix row 6, column 6.

Usage

at_extract(
  project,
  img = NULL,
  stat = "mean",
  layer = NULL,
  label = NULL,
  level = 0L,
  bands = NULL,
  call = rlang::caller_env(),
  nonfinite = c("propagate", "omit", "error")
)

Arguments

Value

A long tibble::tibble with columns roi_id, layer, label, band (integer), band_name, wavelength (NA when not spectral), unit (declared wavelength unit, NA if unknown), stat, value, n_px (selected support), n_valid (finite samples), and n_invalid. Empty selections produce zero rows. Band order follows requested indices; wavelength values and units are preserved, without implicit conversion. The analysis attribute records policy, level, source, bands and limitations. Values come directly from tiles, independently of display contrast. The raster backend itself uses display conversion and cannot preserve original high-bit-depth samples; raw TIFF/OME/ENVI readers have separate contracts.

See Also

at_extract_spectrum(), at_extract_pixels()

Other extraction: at_extract_pixels(), at_extract_spectrum()

Examples

proj <- at_example_project()
at_extract(proj, stat = "mean")

Description

Extract per-pixel values under ROIs

Usage

at_extract_pixels(
  project,
  img = NULL,
  layer = NULL,
  level = 0L,
  bands = NULL,
  max_px = 1e+06,
  call = rlang::caller_env()
)

Arguments

Value

A long tibble::tibble with columns roi_id, layer, label, x, y, band, and value. A 0-row tibble with these columns when nothing matches.

See Also

Other extraction: at_extract(), at_extract_spectrum()

Description

Extract mean/median spectra for a spectral cube

Usage

at_extract_spectrum(
  project,
  img = NULL,
  stat = "mean",
  layer = NULL,
  label = NULL,
  level = 0L,
  call = rlang::caller_env(),
  nonfinite = c("propagate", "omit", "error")
)

Arguments

Value

The long tibble of at_extract(), restricted to spectral bands and sorted by ROI, declared unit, wavelength, then band index. Values are not converted between units; equal wavelengths retain band order.

See Also

Other extraction: at_extract(), at_extract_pixels()

Examples

cube <- at_example_image("cube")
proj <- at_project(cube, at_layer_add(at_layer("roi"),
                                      at_roi_circle(16, 16, 5, label = "roi")))
at_extract_spectrum(proj)

Description

Apply sf::st_make_valid() to invalid ROIs, drop duplicate consecutive vertices, re-orient holes that wind like their exterior ring, and clip out-of-bounds geometry to the image bounds (an intersection, so a polygon stays a polygon), reporting what changed.

Usage

at_fix_geometry(project, verbose = TRUE, call = rlang::caller_env())

Arguments

Value

The annot_project with repaired geometry. Repairs are reported via cli::cli_inform() when verbose is TRUE. Issues that cannot be repaired (zero area, degenerate, empty, NA coordinates, or a clip that would leave nothing inside the image) are left in place and reported.

See Also

at_check_geometry()

Other geometry: at_check_containment(), at_check_geometry(), at_clamp(), at_flip_y(), at_roi_buffer(), at_roi_contains(), at_roi_distance(), at_roi_overlaps(), at_roi_rescale(), at_roi_ring(), at_roi_setops, at_roi_simplify(), at_rois_overlap(), at_snap(), at_transform()

Description

Convert between image orientation (top-left origin, y down) and GIS orientation (bottom-left origin, y up). Self-inverse.

Usage

at_flip_y(roi, height, call = rlang::caller_env())

Arguments

Value

An annot_roi with the y-axis flipped.

See Also

Other geometry: at_check_containment(), at_check_geometry(), at_clamp(), at_fix_geometry(), at_roi_buffer(), at_roi_contains(), at_roi_distance(), at_roi_overlaps(), at_roi_rescale(), at_roi_ring(), at_roi_setops, at_roi_simplify(), at_rois_overlap(), at_snap(), at_transform()

Examples

at_flip_y(at_roi_rect(0, 0, 10, 5, label = "a"), height = 100)

Description

Jump to a specific image

Usage

at_goto(session, i, call = rlang::caller_env())

Arguments

Value

A new annot_session with the cursor at i.

See Also

Other sessions: at_current(), at_example_session(), at_manifest(), at_next(), at_prev(), at_resume(), at_session(), at_session_status(), at_set_status()

Description

Return the backend-agnostic metadata record hyperannotatR keeps for an image: acquisition identity, storage layout, value semantics, geometry convention, plane selection, and calibration/transform digests. Fields a backend cannot establish are NA (never guessed), and wavelength_status in at_bands() flags missing or duplicated wavelengths instead of interpolating them.

Usage

at_hsi_meta(x, call = rlang::caller_env())

Arguments

Value

A named list with the elements vendor, instrument, acquisition_id, format, backend, image_kind ("spectral", "multichannel", "rgb" or "grayscale"), width, height, n_bands, n_levels, dtype, value_unit (one of "raw", "reflectance", "radiance", "intensity", "absorbance", "unknown"), scale_factor, offset, nodata, valid_range, interleave, byte_order, header_bytes, axis_order, pixel_size, pixel_unit, origin, y_direction, series_id, plane (list of zero-based c, z, t), wavelength_unit, calibration, calibration_digest, transform_digest, profile, window_read and pan_sharpened.

See Also

at_bands(), at_read_stats()

Other images: at_bands(), at_close_image(), at_dims(), at_example_image(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Other hsi: at_band_operations(), at_band_view(), at_convert_values(), at_cubert_export_envi(), at_read_stats(), at_tivita_profile()

Examples

at_hsi_meta(at_example_image("cube"))[c("image_kind", "value_unit", "interleave")]

Description

Report how an image's pixels are read: whether opening it reads metadata only, whether tiles are read as windows from the file, what the samples mean, and where they come from.

Usage

at_image_capabilities(x)

Arguments

Value

A list with metadata_only and window_read (logical; NA when a third-party backend does not declare them), samples ("raw-scalar-v1" for stored values, "display-converted-0-255" for display conversions, "unqualified" when undeclared) and io ("binary", "native", "eager", "memory" or "unknown"), plus an optional lifecycle. An image whose handle holds decoded pixels reports memory access even for a backend that normally reads windows.

See Also

Other images: at_bands(), at_close_image(), at_dims(), at_example_image(), at_hsi_meta(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Other backends: at_backend_detect(), at_backend_get(), at_backend_list(), at_backend_register(), at_close_image(), at_cubert_export_envi(), at_read_image(), at_tile(), at_tivita_profile()

Examples

at_image_capabilities(at_example_image("cube"))$window_read

Description

Read only the neutral contract, validate it, and return a namespaced hyperannotatR result together with a conversion report. For a handoff directory the SHA-256 inventory (missing, extra, duplicate, resized, altered or symlinked files), the manifest schema and major version, ROI id uniqueness and the id join between manifest and GeoJSON, layers, planes, mask dimensions, integer values and legend completeness are all checked. Every file the manifest references must be a clean relative path listed in the verified inventory; unlisted operating-system metadata files (.DS_Store, ⁠._*⁠, Thumbs.db, desktop.ini) are ignored with a warning. Any failure aborts with a classified at_error: at_validation_error for integrity, schema and join failures, at_protocol_error for an unsupported major version, at_limit_error for oversized inventories and at_io_error for missing files. Nothing is written, no analysis is started, and foreign objects are never returned as if they were hyperannotatR objects: imported ROIs carry source = "imported" and partner fields under attributes$qupflowr. Features of a single GeoJSON file that carry no id get a minted one and are flagged (attributes$qupflowr$id_minted), so at_stage_qupflowr() creates them instead of joining them to an existing ROI; two features with the same id are refused (DUPLICATE_ID). Handoff coordinates are read at the export level recorded in the manifest. An RDS file is refused, because deserialising it is not a neutral read.

Usage

at_import_qupflowr(
  file,
  format = c("auto", "handoff", "qupath_geojson", "geojson", "mask", "npy"),
  expected_revision = NULL,
  call = rlang::caller_env()
)

Arguments

Value

An at_import_report: a list with status, format, source_name, handoff_digest, manifest, checks (tibble of check, status, detail), objects (layers: named list of annot_layer; masks: named list of annot_mask; images: image records), conversion (tibble with one row per ROI: roi_id, layer, label, source_object_id, object_type, geometry_fidelity, geometry_match ("exact" bytes, "equivalent" within 1e-9 after level normalisation, "changed", or NA without a manifest record), notes) and annotation_revision of the imported layers.

See Also

at_export_qupflowr(), at_stage_qupflowr()

Other interop: at_annotation_revision(), at_commit_qupflowr(), at_export_qupflowr(), at_interop_capabilities(), at_interop_manifest(), at_stage_qupflowr()

Examples

dest <- file.path(tempdir(), "handoff-import-example")
at_export_qupflowr(at_example_project(), dest, overwrite = TRUE)
rep <- at_import_qupflowr(dest)
rep$checks

Description

Validate a saved project or session file and report the state of its image sources, without repairing anything or reading pixels.

Usage

at_inspect_saved(path)

Arguments

Value

A list with valid (logical), class (the saved object's class), issues (character; why the file is invalid or ambiguous) and sources (one at_inspect_source() report per stored project). Invalid or ambiguous structures are reported without guessing repairs.

See Also

at_inspect_source(), at_load_session()

Other io: at_inspect_source(), at_load_project(), at_load_session(), at_read_geojson(), at_read_qupath(), at_read_rois_csv(), at_relink_source(), at_roi_from_geojson(), at_save_project(), at_save_session(), at_write_geojson(), at_write_qupath(), at_write_rois_csv()

Description

Report whether the file an image (or project) was read from is still available and unchanged, so a saved project can be reopened or relinked deliberately.

Usage

at_inspect_source(x)

Arguments

Value

A list with status, path, backend, options (the recorded reader options) and options_inferred (TRUE for a legacy image whose options were not recorded). status is "available", "missing", "changed", "in_memory" (pixels held in memory, no source file) or "unresolved". Size and modification time detect many source replacements, but are not a content checksum. Composite sources also validate every declared companion input, such as an ENVI header and payload.

See Also

at_relink_source(), at_inspect_saved()

Other io: at_inspect_saved(), at_load_project(), at_load_session(), at_read_geojson(), at_read_qupath(), at_read_rois_csv(), at_relink_source(), at_roi_from_geojson(), at_save_project(), at_save_session(), at_write_geojson(), at_write_qupath(), at_write_rois_csv()

Description

Report what this hyperannotatR installation can exchange with a partner package such as qupflowR, and how far each capability has been qualified. Profiles follow the partner contract: I0 file interchange, I1 public R API, I2 the local control service (annotatr-control-v1) and I3 the embeddable app object from at_app(). A profile is "supported" only with implementation, runtime dependencies and qualification evidence; implemented profiles that have not passed their tests against a real partner client are "planned"; profiles whose optional runtime is missing are "unavailable". Every entry carries a reason when it is not supported.

Usage

at_interop_capabilities(
  target = c("package", "hsi", "app", "control"),
  call = rlang::caller_env()
)

Arguments

Value

A list of class at_capabilities with schema, schema_version, annotatr_version, r_version, source_revision, consumer, profiles (I0-I3), limits, and the requested sections package, hsi, app, control, plus digest: the SHA-256 of the canonical JSON of the report without digest itself.

See Also

at_interop_manifest(), at_control_capabilities()

Other interop: at_annotation_revision(), at_commit_qupflowr(), at_export_qupflowr(), at_import_qupflowr(), at_interop_manifest(), at_stage_qupflowr()

Examples

caps <- at_interop_capabilities()
caps$profiles$I0$status
caps$digest

Description

Describe hyperannotatR objects for a partner such as qupflowR without exposing local paths: images are identified by content hash (image_id) and file basename; annotations by string ROI ids and an at_annotation_revision(); masks by type, integer dtype, background, dimensions, level and legend. The coordinate convention, band/wavelength table, HSI value semantics, plane, calibration and transform digests are recorded explicitly. QuPath hierarchy and native ROI shapes, which hyperannotatR does not model, are reported as "unknown" or "approximated", never invented.

Usage

at_interop_manifest(
  x,
  destination = NULL,
  hash_sources = TRUE,
  call = rlang::caller_env()
)

Arguments

Value

The manifest (a list of class at_interop_manifest); invisibly when destination is given.

See Also

at_export_qupflowr(), at_interop_capabilities()

Other interop: at_annotation_revision(), at_commit_qupflowr(), at_export_qupflowr(), at_import_qupflowr(), at_interop_capabilities(), at_stage_qupflowr()

Examples

m <- at_interop_manifest(at_example_project())
m$annotations$annotation_revision
m$images[[1]]$image_id

Description

Is the image pyramidal?

Usage

at_is_pyramidal(x, call = rlang::caller_env())

Arguments

Value

A logical scalar. TRUE when more than one pyramid level exists.

See Also

Other images: at_bands(), at_close_image(), at_dims(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_spectral(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Description

Is the image a spectral cube?

Usage

at_is_spectral(x, call = rlang::caller_env())

Arguments

Value

A logical scalar. TRUE when the image carries per-band wavelengths.

See Also

Other images: at_bands(), at_close_image(), at_dims(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_meta(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Description

Create a layer

Usage

at_layer(
  name,
  labels = character(),
  style = at_style(),
  ...,
  call = rlang::caller_env()
)

Arguments

Value

An annot_layer with no ROIs and a resolved colour mapping.

See Also

at_style(), at_layer_add()

Other layers: at_layer_add(), at_layer_n(), at_layer_remove(), at_layer_rois(), at_style()

Examples

lyr <- at_layer("tumour", labels = c("tumour", "stroma"))
at_layer_n(lyr)

Description

Add an ROI to a layer

Usage

at_layer_add(layer, roi, call = rlang::caller_env())

Arguments

Value

A new annot_layer with the ROI appended. The label vocabulary and colour mapping are extended if the ROI introduces a new label (following the colour specification given to at_layer()). A missing, empty or colliding ROI identifier is re-minted to one unused in the layer. The input is unchanged.

See Also

Other layers: at_layer(), at_layer_n(), at_layer_remove(), at_layer_rois(), at_style()

Examples

lyr <- at_layer("tumour", labels = "tumour")
lyr <- at_layer_add(lyr, at_roi_rect(0, 0, 10, 10, label = "tumour"))
at_layer_n(lyr)

Description

Number of ROIs in a layer

Usage

at_layer_n(layer, call = rlang::caller_env())

Arguments

Value

An integer scalar.

See Also

Other layers: at_layer(), at_layer_add(), at_layer_remove(), at_layer_rois(), at_style()

Description

Remove an ROI from a layer

Usage

at_layer_remove(layer, id, call = rlang::caller_env())

Arguments

Value

A new annot_layer without the identified ROI. Warns if the ROI is not present and returns the layer unchanged.

See Also

Other layers: at_layer(), at_layer_add(), at_layer_n(), at_layer_rois(), at_style()

Description

Layer ROI table

Usage

at_layer_rois(layer, image = NULL, call = rlang::caller_env())

Arguments

Value

An ROI table (see at_rois() for the column contract). A 0-row table with the same columns when the layer has no ROIs.

See Also

Other layers: at_layer(), at_layer_add(), at_layer_n(), at_layer_remove(), at_style()

Description

Layer summary table

Usage

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

Arguments

Value

A tibble::tibble with one row per layer and the columns name (character), n_rois (integer), labels (list of character), visible (logical), locked (logical), and z (integer). A 0-row tibble with these columns when the project has no layers.

See Also

Other projects: at_add_layer(), at_add_roi(), at_example_project(), at_project(), at_remove_layer(), at_remove_roi(), at_rois(), at_summary(), at_validate()

Description

Load a project

Usage

at_load_project(path, call = rlang::caller_env())

Arguments

Value

The annot_project. Its image is reopened from the saved source descriptor; when the source is missing, changed or ambiguous the annotations still load, pixel access fails with a pointer to at_relink_source(), and at_inspect_source() reports why. Warns if the file was written by a newer hyperannotatR.

See Also

Other io: at_inspect_saved(), at_inspect_source(), at_load_session(), at_read_geojson(), at_read_qupath(), at_read_rois_csv(), at_relink_source(), at_roi_from_geojson(), at_save_project(), at_save_session(), at_write_geojson(), at_write_qupath(), at_write_rois_csv()

Description

Load a session

Usage

at_load_session(path, call = rlang::caller_env())

Arguments

Value

The annot_session. A file written before sessions recorded queue entry identities gets one per queue row. Stored projects are reopened lazily by at_current(). Warns if written by a newer hyperannotatR.

See Also

at_save_session(), at_resume()

Other io: at_inspect_saved(), at_inspect_source(), at_load_project(), at_read_geojson(), at_read_qupath(), at_read_rois_csv(), at_relink_source(), at_roi_from_geojson(), at_save_project(), at_save_session(), at_write_geojson(), at_write_qupath(), at_write_rois_csv()

Description

Session progress manifest with per-label counts

Usage

at_manifest(session, call = rlang::caller_env())

Arguments

Value

A tibble::tibble with idx, entry_id, export_stem, name, path, status, n_layers, n_rois, and one integer column per label in the session vocabulary giving its ROI count per image. n_rois counts the ROIs of materialised projects (otherwise the manifest's stored count). A label that clashes with one of the fixed column names gets a label_ prefix.

See Also

Other sessions: at_current(), at_example_session(), at_goto(), at_next(), at_prev(), at_resume(), at_session(), at_session_status(), at_set_status()

Description

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(),
  image = NULL
)

Arguments

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. Boundary ties use the symbolic sample ⁠(x + epsilon, y + epsilon^2)⁠ as epsilon tends to zero from above, without a finite coordinate shift. Equivalently, scanline edges are active on ⁠[minY, maxY)⁠ and crossing pairs fill ⁠[left, right)⁠. Hole rings exclude pixels by parity regardless of winding; MULTIPOLYGON components combine by union. Thin polygons containing no selected centres have empty masks. This rule is shared by both engines and all overlap paths.

POINT and MULTIPOINT geometries select their half-open containing cells: ⁠(5, 5)⁠ selects row 6, column 6. Extraction uses the same membership and bounds. With touches = TRUE, polygon coverage uses the selected engine's all-touched rasterisation; lines and other geometry types also retain the selected engine's rasterisation behavior. Engine equality is guaranteed for centre-based polygons and points. ROI coordinates use the image convention (top-left origin, y down).

Full-grid allocation is checked against getOption("hyperannotatR.max_read_bytes", 1024^3) before rasterisation, using a conservative estimate of 32 bytes per pixel for arrays and working copies. The default allows 33,554,432 pixels. This is not a bound on total process memory or geometry/native-library overhead. Trusted larger masks require raising that option; over-budget requests fail with READ_BUDGET_EXCEEDED, and unsupported array sizes with MASK_TOO_LARGE.

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, mask_type, source_project, mask_metadata and created. An all-background mask of the correct dimensions is returned when there are no ROIs. The mask_metadata attribute has schema version 1 and records encoding (binary, instance, categorical, or bitfield), background, overlap policy, grid (dimensions, level, origin, stride), source descriptor and entry provenance, and the complete label codebook. Supplied values retain mapped-but-absent classes with zero counts. Bitfields require unique positive single-bit codes and zero background; category 3 is exclusive unless bitfield encoding is explicitly declared.

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))

Description

Per-class Dice and Jaccard (IoU) plus an overall accuracy and Cohen's kappa, comparing a reference mask a against a second mask b (e.g. a hyperannotatR mask against a .npy ground truth, or two annotators). Versioned metadata, grids, source provenance, encodings and semantic codebooks are validated. Plain matrices are explicit-code legacy categorical inputs and require finite representable integer values; missing values are rejected.

Usage

at_mask_agreement(
  a,
  b,
  background = 0L,
  labels = NULL,
  call = rlang::caller_env(),
  alignment = c("check", "assert"),
  code_alignment = c("strict", "by-label", "by-id")
)

Arguments

Details

Categorical/binary classes use equality; bitfields use class memberships, with overall accuracy measuring exact membership-set agreement and kappa NA. Instance maps use stable unique ROI IDs, never display class names. No spatial instance matching is inferred. Absent classes retain rows with NA Dice/IoU; background-only accuracy is 1 and kappa is NA (zero Cohen denominator). Mean Dice/IoU exclude absent classes and are NA if none are defined.

Value

A tibble::tibble with one row per class: value, label, n_true, n_pred, tp, fp, fn, dice, iou. The overall attribute is a list of accuracy, kappa, mean_dice, mean_iou, and n_px, encoding, alignment, code_alignment, background and nonfinite (always "error"). A comparison attribute retains validated input metadata and legends for interpretation.

See Also

at_mask(), at_read_npy()

Other masks: at_mask(), 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

m <- at_mask(at_example_project(), "multiclass")
ag <- at_mask_agreement(m, m)
attr(ag, "overall")$kappa

Description

Object boundaries of a mask

Usage

at_mask_boundary(mask, width = 1L, call = rlang::caller_env())

Arguments

Value

A logical matrix marking boundary pixels (where a 4-neighbour has a different value).

See Also

Other masks: at_mask(), at_mask_agreement(), 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()

Description

Keep foreground state codes inside the requested anatomy class and outside artefacts, using each mask's declared background and class membership. An anatomy bitfield includes composite samples containing the requested bit.

Usage

at_mask_derive(
  state,
  anatomy,
  artefact = NULL,
  keep_label = "wound",
  background = NULL,
  call = rlang::caller_env(),
  alignment = c("legacy", "assert")
)

Arguments

Value

An annot_mask retaining state encoding and the full state codebook, with counts recomputed, zero counts for absent classes, and alignment provenance recorded in mask_metadata$derivation.

See Also

at_mask(), at_mask_stack()

Other masks: at_mask(), at_mask_agreement(), at_mask_boundary(), 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()
# A single-layer project derives trivially; the four-layer HSI workflow passes
# separate anatomy/state/artefact masks. See the masks vignette.
m <- at_mask(proj, "multiclass")
at_mask_derive(m, m, keep_label = at_mask_legend(m)$label[1])

Description

Legend of a mask

Usage

at_mask_legend(mask, call = rlang::caller_env())

Arguments

Value

The mask's legend tibble::tibble (value, label, layer, roi_id, n_px, colour).

See Also

Other masks: at_mask(), at_mask_agreement(), at_mask_boundary(), at_mask_derive(), 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

at_mask_legend(at_mask(at_example_project(), "labelled"))

Description

Nearest-neighbour downsample only (interpolating a label mask would invent labels that do not exist).

Usage

at_mask_preview(mask, max_dim = 1024L, call = rlang::caller_env())

Arguments

Value

A downsampled annot_mask with membership-aware counts recomputed. Metadata records the preview dimensions and sampling stride, its parent grid, and the original source provenance. No full-resolution counts are copied onto the sampled matrix.

See Also

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

Description

Stack per-layer masks into a 3D array

Usage

at_mask_stack(project, layers = NULL, level = 0L, call = rlang::caller_env())

Arguments

Value

A 3D integer array ⁠[y, x, layer]⁠, one multi-class plane per layer; the third dimension is named by layer. Codes are local to each layer; the legends attribute is a named list of the per-layer legends (see at_mask_legend()) that maps them back to labels.

See Also

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

Description

Per-value statistics of a mask

Usage

at_mask_stats(mask, pixel_size = NULL, call = rlang::caller_env())

Arguments

Value

A tibble::tibble with one row per mask value: value, label, n_px, area_px, area_physical, frac_total, bounding box (bbox_xmin, bbox_ymin, bbox_xmax, bbox_ymax), and centroid (centroid_x, centroid_y). Every bitfield membership contributes to its class count, including composite samples; categorical counts are exclusive. Mapped-but-absent classes have zero counts. A 0-row tibble is returned only when the codebook is empty.

See Also

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

Examples

at_mask_stats(at_mask(at_example_project(), "labelled"))

Description

Image metadata

Usage

at_meta(x, key = NULL, call = rlang::caller_env())

Arguments

Value

When key is NULL, a list of all metadata (including source, backend, dtype, pixel_unit, and any backend-specific entries). When key is supplied, the single element (or NULL if absent).

See Also

Other images: at_bands(), at_close_image(), at_dims(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_n_bands(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Description

Number of bands (channels)

Usage

at_n_bands(x, call = rlang::caller_env())

Arguments

Value

An integer scalar.

See Also

Other images: at_bands(), at_close_image(), at_dims(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_levels(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes

Description

Number of pyramid levels

Usage

at_n_levels(x, call = rlang::caller_env())

Arguments

Value

An integer scalar; 1 when the image has no pyramid.

See Also

Other images: at_bands(), at_close_image(), at_dims(), at_example_image(), at_hsi_meta(), at_image_capabilities(), at_is_pyramidal(), at_is_spectral(), at_meta(), at_n_bands(), at_pixel_size(), at_read_image(), at_tile(), at_wavelengths(), hyperannotatR-classes