Export annotations as a qupflowR handoff directory

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

x

An annot_project or annot_session (materialised entries are exported under entries/<entry_id>/, where entry_id is the session's stable entry id, or entry-NNNN by queue position for sessions without stable ids).

destination

Path of the handoff directory to create.

formats

Any of "qupath_geojson", "geojson", "mask_tiff", "mask_npy", "csv", "rds", "manifest". manifest.json and integrity.json are always written.

overwrite

Logical; replace an existing handoff directory.

level

Integer pyramid level for coordinates and masks. Default 0.

mask_type

Mask type for mask files: "labelled" (default; one value per ROI, joinable by roi_id through the legend), "multiclass" or "binary".

scope

For sessions: "all" materialised entries (default), "current" or "complete".

call

The calling environment, for error reporting.

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.

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

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
#> [1] "3174b1617d8b96f519ad021867980099b654bec5569e69e50103c29fdb80ee98"
rc$files[, c("path", "format")]
#> # A tibble: 5 × 2
#>   path                                   format        
#>   <chr>                                  <chr>         
#> 1 annotations_qupath.geojson             qupath_geojson
#> 2 image.json                             image_json    
#> 3 manifest.json                          manifest      
#> 4 masks/regions_labelled.tif             mask_tiff     
#> 5 masks/regions_labelled.tif.legend.json legend_json