| Title: | Geospatial Image Segmentation with SAM3 |
|---|---|
| Description: | Native R API for geospatial image segmentation using Meta's Segment Anything Model 3 (SAM3). Provides tidyverse-friendly interfaces for detecting objects in satellite imagery using text prompts, point prompts, and exemplar-based detection. Features open-vocabulary object detection powered by SAM3's text prompting. Built-in support for downloading satellite imagery from Mapbox, Esri, and MapTiler. |
| Authors: | Kyle Walker [aut, cre] |
| Maintainer: | Kyle Walker <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.2.9000 |
| Built: | 2026-05-20 22:01:29 UTC |
| Source: | https://github.com/walkerke/geosam |
Clears cached satellite imagery tiles.
geosam_clear_cache()geosam_clear_cache()
Invisibly returns TRUE.
Set package-wide configuration options for model selection and device.
geosam_configure(model = NULL, device = NULL, mapbox_token = NULL)geosam_configure(model = NULL, device = NULL, mapbox_token = NULL)
model |
Model to use: "sam2" (default, latest) or "sam" (original). |
device |
Computing device: "auto" (default), "mps", "cuda", or "cpu". "auto" selects the best available device. |
mapbox_token |
Mapbox access token for satellite imagery. Can also be set via the MAPBOX_ACCESS_TOKEN environment variable. |
Invisibly returns the previous configuration.
## Not run: # Use SAM 2 on CPU geosam_configure(model = "sam2", device = "cpu") # Set Mapbox token geosam_configure(mapbox_token = "pk.xxx") ## End(Not run)## Not run: # Use SAM 2 on CPU geosam_configure(model = "sam2", device = "cpu") # Set Mapbox token geosam_configure(mapbox_token = "pk.xxx") ## End(Not run)
Scans the system for conda installations and geosam environments to help troubleshoot installation problems. Useful when you have multiple conda distributions installed (miniconda, miniforge, anaconda, etc.).
geosam_diagnose()geosam_diagnose()
A list with diagnostic information, invisibly.
## Not run: geosam_diagnose() ## End(Not run)## Not run: geosam_diagnose() ## End(Not run)
Creates a Python virtual environment and installs required packages for SAM3 inference. This only needs to be run once.
geosam_install( envname = "geosam", method = c("uv", "virtualenv", "conda"), gpu = NULL, hf_token = NULL, python_version = "3.12", conda = "auto" )geosam_install( envname = "geosam", method = c("uv", "virtualenv", "conda"), gpu = NULL, hf_token = NULL, python_version = "3.12", conda = "auto" )
envname |
Name of the virtual environment to create (default: "geosam") |
method |
Installation method: "uv" (recommended, fast), "virtualenv", or "conda". uv is the default and recommended approach. |
gpu |
Logical. If TRUE, installs GPU-enabled PyTorch. If NULL (default), auto-detects based on available hardware. |
hf_token |
Optional HuggingFace token for accessing SAM3 model weights. Can also be set via the HF_TOKEN environment variable. Required for SAM3. |
python_version |
Python version to use (default: "3.12"). SAM3 requires 3.12+. |
conda |
Path to conda executable. Only used when |
This function installs:
PyTorch 2.7+ (with MPS support on Apple Silicon, CUDA 12.6+ on NVIDIA GPUs)
SAM3 from Meta (https://github.com/facebookresearch/sam3)
rasterio, geopandas, shapely, pyproj (geospatial processing)
uv (recommended): Fast, modern Python package manager. Install uv first:
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Or via pip (any platform) pip install uv
virtualenv: Uses Python's built-in venv via reticulate. Requires Python 3.12+ to be installed on your system.
conda: Uses conda/miniconda. Slower but handles complex dependencies well.
If you have multiple conda installations, use the conda parameter to specify
which one to use.
You must log in to HuggingFace and accept the gated model terms for SAM3 model weights at: https://huggingface.co/facebook/sam3
Invisibly returns TRUE on success.
## Not run: # Standard installation with uv (recommended) geosam_install() # With HuggingFace token geosam_install(hf_token = "hf_xxxxx") # Use virtualenv instead of uv geosam_install(method = "virtualenv") # Use conda geosam_install(method = "conda") # Use a specific conda installation (e.g., miniforge instead of miniconda) geosam_install(method = "conda", conda = "~/miniforge3/bin/conda") ## End(Not run)## Not run: # Standard installation with uv (recommended) geosam_install() # With HuggingFace token geosam_install(hf_token = "hf_xxxxx") # Use virtualenv instead of uv geosam_install(method = "virtualenv") # Use conda geosam_install(method = "conda") # Use a specific conda installation (e.g., miniforge instead of miniconda) geosam_install(method = "conda", conda = "~/miniforge3/bin/conda") ## End(Not run)
Checks the Python environment and reports which features are available.
geosam_status(check_access = TRUE)geosam_status(check_access = TRUE)
check_access |
Logical. If TRUE, checks whether the configured
HuggingFace token can access the gated |
A list with installation status information, invisibly.
## Not run: geosam_status() ## End(Not run)## Not run: geosam_status() ## End(Not run)
Downloads satellite imagery tiles for a bounding box and saves as a GeoTIFF. Uses R-native tools (httr2, terra) for reliable tile fetching and georeferencing.
get_imagery( bbox, output = NULL, source = c("mapbox", "esri", "maptiler"), zoom = 17, api_key = NULL )get_imagery( bbox, output = NULL, source = c("mapbox", "esri", "maptiler"), zoom = 17, api_key = NULL )
bbox |
Bounding box for the area. Can be a numeric vector
|
output |
Path for output GeoTIFF. If NULL, creates a temp file. |
source |
Imagery source: "mapbox", "esri", or "maptiler".
|
zoom |
Tile zoom level (15-19). Higher values = more detail. Recommended: 17-18 for objects like buildings, swimming pools. |
api_key |
API key for the imagery source. For Mapbox, uses MAPBOX_PUBLIC_TOKEN environment variable by default. For MapTiler, uses MAPTILER_API_KEY environment variable by default. |
Path to the downloaded GeoTIFF file.
## Not run: # Download imagery for an area img <- get_imagery( bbox = c(-102.5, 31.8, -102.4, 31.9), source = "mapbox", zoom = 17 ) # Use with detection pads <- sam_detect(image = img, text = "swimming pool") ## End(Not run)## Not run: # Download imagery for an area img <- get_imagery( bbox = c(-102.5, 31.8, -102.4, 31.9), source = "mapbox", zoom = 17 ) # Use with detection pads <- sam_detect(image = img, text = "swimming pool") ## End(Not run)
Check if Object is a geosam
is_geosam(x)is_geosam(x)
x |
Object to test. |
Logical indicating if x is a geosam object.
Check if Object is a geosam_image
is_geosam_image(x)is_geosam_image(x)
x |
Object to test. |
Logical indicating if x is a geosam_image object.
Displays satellite imagery with detection polygons overlaid using terra.
## S3 method for class 'geosam' plot( x, fill = "#FACC15", border = NULL, palette = NULL, opacity = 0.5, lwd = 1, main = NULL, add = FALSE, ... )## S3 method for class 'geosam' plot( x, fill = "#FACC15", border = NULL, palette = NULL, opacity = 0.5, lwd = 1, main = NULL, add = FALSE, ... )
x |
A geosam object from |
fill |
Fill color for detection polygons. Default is semi-transparent yellow.
Ignored if |
border |
Border color for polygon outlines. If NULL (default), automatically darkens the fill color. Set to NA to disable borders. |
palette |
Optional color palette for distinct colors per detection. Can be:
|
opacity |
Opacity for fill colors (0-1). Default is 0.5. Applied to all fills. |
lwd |
Line width for polygon borders. Default is 1. |
main |
Plot title. Default is NULL (no title). |
add |
If TRUE, add to existing plot instead of creating new one. Default is FALSE. |
... |
Additional arguments passed to |
Invisibly returns the sf polygons that were plotted.
## Not run: result <- sam_detect( bbox = c(-102.63, 31.81, -102.62, 31.83), text = "swimming pool" ) plot(result) # Distinct colors per detection plot(result, palette = "Set1") # Custom colors plot(result, fill = "red") # border auto-darkens # Layer multiple results plot(result1) plot(result2, add = TRUE, fill = "blue") ## End(Not run)## Not run: result <- sam_detect( bbox = c(-102.63, 31.81, -102.62, 31.83), text = "swimming pool" ) plot(result) # Distinct colors per detection plot(result, palette = "Set1") # Custom colors plot(result, fill = "red") # border auto-darkens # Layer multiple results plot(result1) plot(result2, add = TRUE, fill = "blue") ## End(Not run)
Displays an image with detection masks overlaid using magick.
## S3 method for class 'geosam_image' plot( x, fill = "#FACC15", border = NULL, palette = NULL, opacity = 0.4, border_width = 2, add = FALSE, base_img = NULL, ... )## S3 method for class 'geosam_image' plot( x, fill = "#FACC15", border = NULL, palette = NULL, opacity = 0.4, border_width = 2, add = FALSE, base_img = NULL, ... )
x |
A geosam_image object from |
fill |
Fill color for detection masks. Default is yellow.
Ignored if |
border |
Border color for detection outlines. If NULL (default), automatically darkens the fill color. Set to NA to disable borders. |
palette |
Optional color palette for distinct colors per detection. Can be:
|
opacity |
Opacity of the mask overlay (0-1). Default is 0.4. |
border_width |
Width of border lines in pixels. Default is 2. |
add |
If TRUE, add to an existing magick image instead of loading from file.
Pass the image as the |
base_img |
A magick image to add overlays to. Required when |
... |
Additional arguments (currently ignored). |
Invisibly returns the composite magick image, which can be saved
with magick::image_write() or further manipulated.
## Not run: result <- sam_image("photo.jpg", text = "dog") plot(result) # Distinct colors per detection plot(result, palette = "Set2") # Custom color (border auto-matches) plot(result, fill = "red") # Layer multiple detections img <- plot(result1) img <- plot(result2, add = TRUE, base_img = img, fill = "blue") img <- plot(result3, add = TRUE, base_img = img, fill = "red") # Save the result magick::image_write(img, "annotated.png") ## End(Not run)## Not run: result <- sam_image("photo.jpg", text = "dog") plot(result) # Distinct colors per detection plot(result, palette = "Set2") # Custom color (border auto-matches) plot(result, fill = "red") # Layer multiple detections img <- plot(result1) img <- plot(result2, add = TRUE, base_img = img, fill = "blue") img <- plot(result3, add = TRUE, base_img = img, fill = "red") # Save the result magick::image_write(img, "annotated.png") ## End(Not run)
Print Method for geosam Objects
## S3 method for class 'geosam' print(x, ...)## S3 method for class 'geosam' print(x, ...)
x |
A geosam object. |
... |
Additional arguments (ignored). |
Invisibly returns x.
Print Method for geosam_image Objects
## S3 method for class 'geosam_image' print(x, ...)## S3 method for class 'geosam_image' print(x, ...)
x |
A geosam_image object. |
... |
Additional arguments (ignored). |
Invisibly returns x.
Returns detection masks as a list of R matrices.
sam_as_matrix(x)sam_as_matrix(x)
x |
A geosam or geosam_image object. |
A list of binary matrices (1 = detected, 0 = background).
## Not run: result <- sam_image("photo.jpg", text = "dog") masks <- sam_as_matrix(result) image(masks[[1]]) # Display first mask ## End(Not run)## Not run: result <- sam_image("photo.jpg", text = "dog") masks <- sam_as_matrix(result) image(masks[[1]]) # Display first mask ## End(Not run)
Converts detection masks from a geosam object to a terra SpatRaster.
sam_as_raster(x, combined = FALSE)sam_as_raster(x, combined = FALSE)
x |
A geosam object from |
combined |
If TRUE, combine all masks into a single layer (union). If FALSE (default), return a multi-layer raster with one layer per detection. |
A terra SpatRaster with mask values (1 = detected, 0 = background). Returns NULL if no masks.
## Not run: result <- sam_detect(image = "satellite.tif", text = "building") mask_raster <- sam_as_raster(result, combined = TRUE) terra::plot(mask_raster) ## End(Not run)## Not run: result <- sam_detect(image = "satellite.tif", text = "building") mask_raster <- sam_as_raster(result, combined = TRUE) terra::plot(mask_raster) ## End(Not run)
Converts detection masks to sf polygon geometries.
sam_as_sf(x, min_area = NULL, max_area = NULL)sam_as_sf(x, min_area = NULL, max_area = NULL)
x |
A geosam or geosam_image object. |
min_area |
Minimum object area. For geosam, in square meters. For geosam_image, in square pixels. Objects smaller are filtered out. |
max_area |
Maximum object area. For geosam, in square meters. For geosam_image, in square pixels. Objects larger are filtered out. |
For geosam objects (georeferenced imagery), returns polygons in WGS84
coordinates with area in square meters.
For geosam_image objects (non-georeferenced images), returns polygons
in pixel coordinates where x = column (from left) and y = row (from top).
An sf data frame with polygon geometries, scores, and area. Returns NULL if no polygons remain after filtering.
## Not run: # Georeferenced imagery result <- sam_detect(image = "satellite.tif", text = "building") buildings <- sam_as_sf(result, min_area = 100) # Non-georeferenced image result <- sam_image("photo.jpg", text = "dog") dogs <- sam_as_sf(result) # coordinates in pixels ## End(Not run)## Not run: # Georeferenced imagery result <- sam_detect(image = "satellite.tif", text = "building") buildings <- sam_as_sf(result, min_area = 100) # Non-georeferenced image result <- sam_image("photo.jpg", text = "dog") dogs <- sam_as_sf(result) # coordinates in pixels ## End(Not run)
Runs SAM3 detection on multiple areas (polygons) and returns combined results.
sam_batch( areas, text, source = "mapbox", zoom = 17, threshold = 0.5, min_area = NULL, max_area = NULL, .progress = TRUE )sam_batch( areas, text, source = "mapbox", zoom = 17, threshold = 0.5, min_area = NULL, max_area = NULL, .progress = TRUE )
areas |
An sf object with polygon geometries defining areas to process. |
text |
Text prompt for detection. |
source |
Imagery source: "mapbox", "esri", or "maptiler". |
zoom |
Tile zoom level for imagery download. |
threshold |
Detection confidence threshold. |
min_area |
Minimum object area in square meters. |
max_area |
Maximum object area in square meters. |
.progress |
Logical. If TRUE, shows a progress bar. |
An sf data frame with detection results. Includes an area_id column
linking detections to input areas.
## Not run: library(tigris) # Process multiple counties counties <- counties("TX") |> filter(NAME %in% c("Midland", "Ector")) pads <- sam_batch( areas = counties, text = "swimming pool", min_area = 500 ) ## End(Not run)## Not run: library(tigris) # Process multiple counties counties <- counties("TX") |> filter(NAME %in% c("Midland", "Ector")) pads <- sam_batch( areas = counties, text = "swimming pool", min_area = 500 ) ## End(Not run)
Returns the bounding box encompassing all detected objects.
sam_bbox(x)sam_bbox(x)
x |
A geosam object from |
An sf bbox object, or NULL if no detections.
## Not run: result <- sam_detect(image = "satellite.tif", text = "building") bbox <- sam_bbox(result) ## End(Not run)## Not run: result <- sam_detect(image = "satellite.tif", text = "building") bbox <- sam_bbox(result) ## End(Not run)
Returns the number of detected objects.
sam_count(x)sam_count(x)
x |
A geosam or geosam_image object. |
Integer count of detections.
Main function for object detection using Meta's SAM3 model. Supports text prompts, point prompts, box prompts, and exemplar-based detection.
sam_detect( image = NULL, bbox = NULL, text = NULL, boxes = NULL, points = NULL, labels = NULL, exemplar = NULL, source = "mapbox", zoom = 17, threshold = 0.5, chunked = NULL, chunk_size = NULL, chunk_overlap = NULL, min_area = NULL, max_area = NULL )sam_detect( image = NULL, bbox = NULL, text = NULL, boxes = NULL, points = NULL, labels = NULL, exemplar = NULL, source = "mapbox", zoom = 17, threshold = 0.5, chunked = NULL, chunk_size = NULL, chunk_overlap = NULL, min_area = NULL, max_area = NULL )
image |
Path to a GeoTIFF image, or NULL to download imagery for bbox. Large images (>2000 pixels on longest dimension) are automatically processed in chunks when using text prompts. |
bbox |
Bounding box for the area of interest. Can be a numeric vector
|
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 "maptiler". |
zoom |
Tile zoom level for imagery download (17-19 recommended). |
threshold |
Detection confidence threshold (0-1). Lower values return more detections. |
chunked |
Control chunking for large areas/images:
|
chunk_size |
Target chunk size in pixels when chunking. Defaults to an internal value tuned for SAM3. |
chunk_overlap |
Overlap in pixels when chunking. Defaults to an internal value that reduces tile-boundary artifacts. |
min_area |
Minimum object area in square meters. Objects smaller than this are filtered out. For chunked detection, filtering happens during processing (better performance). Default NULL (no minimum). |
max_area |
Maximum object area in square meters. Objects larger than this are filtered out. Default NULL (no maximum). |
For large areas or images, detection is automatically chunked to maintain accuracy and avoid memory issues. This means you can pass a large bounding box (e.g., a census tract) or a large GeoTIFF file (e.g., an orthoimage) and get reliable detection without running out of memory.
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.
## Not run: # 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 ) # Large user-provided image - automatically chunked result <- sam_detect( image = "large_orthoimage.tif", text = "trees", threshold = 0.3 ) # 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 ) ## End(Not run)## Not run: # 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 ) # Large user-provided image - automatically chunked result <- sam_detect( image = "large_orthoimage.tif", text = "trees", threshold = 0.3 ) # 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 ) ## End(Not run)
Opens an interactive map to explore satellite imagery, draw prompts, and run SAM detection.
sam_explore( source = c("mapbox", "esri", "maptiler"), center = NULL, bbox = NULL, zoom = 15, units = c("metric", "imperial"), quality = c("balanced", "fast", "accurate"), ... )sam_explore( source = c("mapbox", "esri", "maptiler"), center = NULL, bbox = NULL, zoom = 15, units = c("metric", "imperial"), quality = c("balanced", "fast", "accurate"), ... )
source |
Imagery source: "mapbox", "esri", or "maptiler".
|
center |
Initial map center as c(lng, lat). If NULL, defaults to US center. |
bbox |
Initial bounding box as c(xmin, ymin, xmax, ymax) or sf object. If provided, map will zoom to this extent. |
zoom |
Initial zoom level (default 15). |
units |
Unit system for the scale bar and area display: |
quality |
Initial detection quality preset: |
... |
Additional arguments passed to |
The explorer provides a complete workflow:
Navigate the map to find an area of interest
Select a prompt type (text, box, points, or exemplar)
Enter text or draw prompts on the map
Click "Detect" to run SAM on the current viewport
View results and optionally refine with +/- points
Click "Done" to return the geosam object
A geosam object when the user clicks "Done", or NULL if cancelled.
## Not run: # Start exploring with Mapbox satellite result <- sam_explore(source = "mapbox", center = c(-102.5, 31.8), zoom = 15) # Extract results if (!is.null(result)) { polygons <- sam_as_sf(result) } ## End(Not run)## Not run: # Start exploring with Mapbox satellite result <- sam_explore(source = "mapbox", center = c(-102.5, 31.8), zoom = 15) # Extract results if (!is.null(result)) { polygons <- sam_as_sf(result) } ## End(Not run)
Opens an interactive viewer to explore an image and run SAM detection using text prompts, point clicks, or drawn boxes.
sam_explore_image(image)sam_explore_image(image)
image |
Path to image file (PNG, JPG, etc.). Required. |
The explorer provides a complete workflow:
View and pan/zoom the image
Select a prompt type (text, box, or points)
Enter text or draw/click prompts on the image
Click "Detect" to run SAM
View results
Click "Done" to return the geosam_image object
The viewer uses MapLibre with a blank background and the image displayed as a raster layer, enabling all standard map interactions.
A geosam_image object when the user clicks "Done", or NULL if cancelled.
## Not run: # Explore a photo result <- sam_explore_image("photo.jpg") # Extract detected regions if (!is.null(result)) { polygons <- sam_as_sf(result) } ## End(Not run)## Not run: # Explore a photo result <- sam_explore_image("photo.jpg") # Extract detected regions if (!is.null(result)) { polygons <- sam_as_sf(result) } ## End(Not run)
Filters detections in a geosam object based on area and/or confidence score.
sam_filter(x, min_area = NULL, max_area = NULL, min_score = NULL)sam_filter(x, min_area = NULL, max_area = NULL, min_score = NULL)
x |
A geosam object. |
min_area |
Minimum area in square meters. |
max_area |
Maximum area in square meters. |
min_score |
Minimum confidence score (0-1). |
A new geosam object with filtered detections.
## Not run: result <- sam_detect(image = "satellite.tif", text = "building") filtered <- result |> sam_filter(min_area = 100, min_score = 0.7) ## End(Not run)## Not run: result <- sam_detect(image = "satellite.tif", text = "building") filtered <- result |> sam_filter(min_area = 100, min_score = 0.7) ## End(Not run)
Uses a single selected detection as an exemplar to find all similar objects in the image.
sam_find_similar(x)sam_find_similar(x)
x |
A geosam object with exactly one detection (use |
A new geosam object with all detected similar objects.
## Not run: result <- sam_detect(image = "satellite.tif", text = "swimming pool") # View results, pick the best one, find all similar similar <- result |> sam_select(3) |> sam_find_similar() ## End(Not run)## Not run: result <- sam_detect(image = "satellite.tif", text = "swimming pool") # View results, pick the best one, find all similar similar <- result |> sam_select(3) |> sam_find_similar() ## End(Not run)
Run SAM3 object detection on a non-georeferenced image (PNG, JPG, etc.).
For georeferenced satellite imagery, use sam_detect() instead.
sam_image( image, text = NULL, points = NULL, labels = NULL, boxes = NULL, exemplar = NULL, threshold = 0.5 )sam_image( image, text = NULL, points = NULL, labels = NULL, boxes = NULL, exemplar = NULL, threshold = 0.5 )
image |
Path to image file (PNG, JPG, TIFF, etc.). |
text |
Text prompt describing objects to detect (e.g., "car", "person"). |
points |
Matrix or data.frame of point coordinates in pixels (x, y). Column 1 is x (horizontal), column 2 is y (vertical, from top). |
labels |
Integer vector of labels for point prompts (1 = foreground, 0 = background). If NULL, all points are treated as foreground. |
boxes |
Matrix or data.frame of box coordinates in pixels. Each row: (xmin, ymin, xmax, ymax). |
exemplar |
Vector of box coordinates for an exemplar (xmin, ymin, xmax, ymax). |
threshold |
Detection confidence threshold (0-1). |
A geosam_image object containing detection masks and metadata.
Use sam_as_sf() to extract polygons (in pixel coordinates).
Returns NULL if no objects are detected.
## Not run: # Text-based detection on a photo result <- sam_image("photo.jpg", text = "dog") # Point prompts (click locations in pixels) result <- sam_image("photo.jpg", points = matrix(c(100, 200, 150, 250), ncol = 2, byrow = TRUE)) # Extract polygons polys <- sam_as_sf(result) ## End(Not run)## Not run: # Text-based detection on a photo result <- sam_image("photo.jpg", text = "dog") # Point prompts (click locations in pixels) result <- sam_image("photo.jpg", points = matrix(c(100, 200, 150, 250), ncol = 2, byrow = TRUE)) # Extract polygons polys <- sam_as_sf(result) ## End(Not run)
Checks whether the SAM3 model is currently loaded in memory.
sam_is_loaded()sam_is_loaded()
Logical indicating whether the model is loaded.
Loads the SAM3 model into memory. Useful for interactive use or Shiny apps where you want to keep the model warm between calls.
sam_load(device = "auto")sam_load(device = "auto")
device |
Device to load model on: "auto", "mps", "cuda", or "cpu". |
Invisibly returns TRUE on success.
## Not run: # Load model before making multiple detections sam_load() # Now detections are faster result1 <- sam_detect(image = "img1.tif", text = "building") result2 <- sam_detect(image = "img2.tif", text = "building") # Unload when done sam_unload() ## End(Not run)## Not run: # Load model before making multiple detections sam_load() # Now detections are faster result1 <- sam_detect(image = "img1.tif", text = "building") result2 <- sam_detect(image = "img2.tif", text = "building") # Unload when done sam_unload() ## End(Not run)
When detecting objects over large areas, geosam uses tiled processing which can split objects that span tile boundaries into multiple polygons. This function merges polygons that are close together, healing those splits.
sam_merge_edges(x, buffer = 2, by_prompt = TRUE)sam_merge_edges(x, buffer = 2, by_prompt = TRUE)
x |
A geosam object or sf object with detection results. |
buffer |
Distance in meters to buffer polygons before checking for overlap. Larger values merge polygons that are further apart. Default is 2. |
by_prompt |
If TRUE and a |
This function is useful when you notice objects being split at regular intervals (tile boundaries). The default buffer of 2 meters catches most boundary splits without merging truly separate objects.
For aggressive merging of nearby objects (not just boundary splits), use a larger buffer value, but be aware this may merge objects that should remain separate.
An sf object with merged polygons. Scores are aggregated by taking the maximum score from merged polygons.
## Not run: # Detect buildings over a large area (uses tiling internally) buildings <- sam_detect( bbox = c(-118.5, 34.0, -118.4, 34.1), text = "building", zoom = 18 ) # Merge any buildings split at tile boundaries merged <- sam_merge_edges(buildings) # More aggressive merging (5m buffer) merged <- sam_merge_edges(buildings, buffer = 5) ## End(Not run)## Not run: # Detect buildings over a large area (uses tiling internally) buildings <- sam_detect( bbox = c(-118.5, 34.0, -118.4, 34.1), text = "building", zoom = 18 ) # Merge any buildings split at tile boundaries merged <- sam_merge_edges(buildings) # More aggressive merging (5m buffer) merged <- sam_merge_edges(buildings, buffer = 5) ## End(Not run)
Returns confidence scores for all detections.
sam_scores(x)sam_scores(x)
x |
A geosam or geosam_image object. |
Numeric vector of scores.
Subsets a geosam object to include only specific detections.
sam_select(x, index)sam_select(x, index)
x |
A geosam object. |
index |
Integer vector of indices to keep. |
A new geosam object with only the selected detections.
## Not run: result <- sam_detect(image = "satellite.tif", text = "building") # Keep only the top 3 scoring detections top3 <- sam_select(result, order(sam_scores(result), decreasing = TRUE)[1:3]) ## End(Not run)## Not run: result <- sam_detect(image = "satellite.tif", text = "building") # Keep only the top 3 scoring detections top3 <- sam_select(result, order(sam_scores(result), decreasing = TRUE)[1:3]) ## End(Not run)
Unloads the SAM3 model from memory to free GPU/CPU resources.
sam_unload()sam_unload()
Invisibly returns TRUE.
Opens an interactive map viewer to view SAM detections.
sam_view( x, fill = "#FACC15", border = "#EAB308", fill_opacity = 0.5, source = NULL )sam_view( x, fill = "#FACC15", border = "#EAB308", fill_opacity = 0.5, source = NULL )
x |
A geosam object from |
fill |
Fill color for detection polygons. Default is "#FACC15" (yellow). |
border |
Border/outline color for polygons. Default is "#EAB308". |
fill_opacity |
Fill opacity for detection polygons (0-1). Default is 0.5. |
source |
Imagery source for basemap: "mapbox", "esri", or "maptiler". If NULL (default), uses the source from the geosam object if available, otherwise falls back to "mapbox" or "esri" if no API key is set. |
The viewer shows the satellite imagery with current detections overlaid.
Note: Point-based refinement is not yet fully implemented. The current version is view-only.
The geosam object when the user clicks "Done".
## Not run: result <- sam_detect(image = "satellite.tif", text = "building") refined <- sam_view(result) # Custom colors sam_view(result, fill = "#3B82F6", border = "#1D4ED8") ## End(Not run)## Not run: result <- sam_detect(image = "satellite.tif", text = "building") refined <- sam_view(result) # Custom colors sam_view(result, fill = "#3B82F6", border = "#1D4ED8") ## End(Not run)
Opens an interactive viewer to display detection results overlaid on the source image.
sam_view_image(x)sam_view_image(x)
x |
A |
The geosam_image object when the user clicks "Done".
## Not run: result <- sam_image("photo.jpg", text = "dog") sam_view_image(result) ## End(Not run)## Not run: result <- sam_image("photo.jpg", text = "dog") sam_view_image(result) ## End(Not run)