Skip to contents

Detect Objects in Geospatial Imagery Using SAM3

Source: R/detect.R
sam_detect.Rd

Main function for object detection using Meta's SAM3 model. Supports text prompts, point prompts, box prompts, and exemplar-based detection.

Usage

sam_detect(
  image = NULL,
  bbox = NULL,
  text = NULL,
  boxes = NULL,
  points = NULL,
  labels = NULL,
  exemplar = NULL,
  source = "mapbox",
  zoom = 17,
  threshold = 0.5,
  chunked = "auto"
)

Arguments

image

Path to a GeoTIFF image, or NULL to download imagery for bbox.

bbox

Bounding box for the area of interest. Can be a numeric vector c(xmin, ymin, xmax, ymax) in WGS84, or an sf/sfc object.

text

Text prompt describing objects to detect (e.g., "swimming pool", "swimming pool", "solar panel"). Uses SAM3's open-vocabulary detection.

boxes

sf object with polygons/boxes to use as box prompts.

points

sf object with points to use as point prompts.

labels

Integer vector of labels for point prompts (1 = foreground, 0 = background). If NULL, all points are treated as foreground.

exemplar

sf polygon representing an example object. SAM3 will find all similar objects in the image.

source

Imagery source if downloading: "mapbox", "esri", or "google".

zoom

Tile zoom level for imagery download (17-19 recommended).

threshold

Detection confidence threshold (0-1). Lower values return more detections.

chunked

Control automatic chunking for large areas. One of:

  • "auto" (default): Automatically chunk if bbox is large

  • TRUE: Force chunked detection

  • FALSE: Disable chunking (may reduce accuracy for very large areas)

Value

A geosam object containing detection masks and metadata. Use sam_as_sf() to extract polygons, sam_filter() to filter by area/score. Returns NULL if no objects are detected.

Details

For large areas, detection is automatically chunked to maintain accuracy. This means you can pass a large bounding box (e.g., a census tract) and get the same detection quality as if you manually checked each viewport.

Examples

if (FALSE) { # \dontrun{
# Text-based detection
result <- sam_detect(
  bbox = c(-102.5, 31.8, -102.4, 31.9),
  text = "swimming pool"
)
pads <- result |> sam_filter(min_area = 500) |> sam_as_sf()

# Large area - automatically chunked
result <- sam_detect(
  bbox = c(-118.45, 34.08, -118.40, 34.12),  # ~5km area
  text = "swimming pool",
  zoom = 18
)

# Point prompts on existing image
result <- sam_detect(
  image = "satellite.tif",
  points = my_points_sf
)

# Box prompts
result <- sam_detect(
  image = "satellite.tif",
  boxes = my_boxes_sf
)

# Exemplar-based detection
result <- sam_detect(
  image = "satellite.tif",
  exemplar = my_example_polygon
)
} # }