Session and Discovery

This chapter covers session lifecycle and tool discovery patterns.

Session and discovery APIs establish runtime certainty before execution. By creating a session explicitly and checking tool visibility up front, you avoid late failures in long pipelines and make script behavior easier to reason about across different environments and deployment targets.

Create Session

This is the standard session bootstrap for scripts. Keep it explicit so runtime state is obvious to future readers.

library(whiteboxworkflows)

s <- wbw_session()
print(s)

Visibility Checks

Use hard visibility checks before long jobs so missing-tool failures happen immediately.

library(whiteboxworkflows)

s <- wbw_session()
ids <- wbw_tool_ids(session = s)
cat('Visible tools:', length(ids), '\n')

if (!wbw_has_tool('slope', session = s)) {
	stop('slope is not available in this runtime session')
}

Search and Describe

Use this when you know the task objective but need to confirm exact tool IDs and parameter contracts.

library(whiteboxworkflows)

matches <- wbw_search_tools('lidar')
print(matches[1:min(5, length(matches))])

desc <- wbw_describe_tool('slope')
print(desc)

Category-Based Discovery

Category discovery is useful for UI generation, guided workflows, and policy checks in larger automation systems.

library(whiteboxworkflows)

summary <- wbw_category_summary()
print(summary)

cats <- wbw_get_all_categories()
print(cats)

raster_tools <- wbw_tools_in_category('Raster')
print(head(raster_tools, 20))

proj_tools <- wbw_tools_in_category('projection_georeferencing')
print(head(proj_tools, 20))

Session API Reference

WbW-R is function-first, but the wbw_session() object still exposes a useful set of callable methods for execution, projection utilities, topology checks, and typed I/O helpers.

Session Construction and Execution

MethodDescription
run_toolExecute a tool with a named argument list.
run_tool_with_progressExecute a tool and return structured progress/result output.
list_toolsReturn visible tool IDs for the session/license context.

Typed I/O Helpers

MethodDescription
read_vectorRead vector data with optional read options.
write_rasterWrite one raster with optional format options.
write_rastersWrite multiple rasters in one call.
write_vectorWrite one vector with optional format options.

Projection Utility Methods

MethodDescription
projection_to_ogc_wktConvert EPSG code to OGC WKT text.
projection_identify_epsgIdentify EPSG from CRS text where possible.
projection_reproject_pointsReproject point collections between EPSG systems.
projection_reproject_pointReproject a single point between EPSG systems.

Topology Utility Methods

MethodDescription
topology_intersects_wkt, topology_contains_wkt, topology_within_wktCore spatial predicate checks on WKT geometries.
topology_touches_wkt, topology_disjoint_wkt, topology_crosses_wkt, topology_overlaps_wktAdditional topological predicates for rule-based QA.
topology_covers_wkt, topology_covered_by_wktBoundary-aware containment checks.
topology_relate_wktReturn DE-9IM relation text for exact topology logic.
topology_distance_wktReturn shortest distance between WKT geometries.
topology_vector_feature_relationEvaluate topology relation between indexed features in two vector objects.
topology_is_valid_polygon_wkt, topology_make_valid_polygon_wktValidate and repair polygon WKT geometries.
topology_buffer_wktBuild buffered geometry from WKT and distance.
  1. Build session explicitly.
  2. Check required tools with wbw_has_tool(...).
  3. Use wbw_describe_tool(...) for parameter verification.
  4. Use category functions to drive guided UX or script validation.