pkgdown site

ConnorB · ConnorB · commit a52ac2867523 · 2026-05-05T22:46:36.000-05:00
diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -2,3 +2,14 @@ url: https://connorb.github.io/flowcam/
 template:
   bootstrap: 5
 
+navbar:
+  structure:
+    left:  [intro, articles, reference]
+    right: [search, github]
+
+articles:
+  - title: "Vignettes"
+    navbar: ~
+    contents:
+      - getting-started
+      - pecos-river
diff --git a/index.md b/index.md
@@ -0,0 +1,69 @@
+# flowcam
+
+**flowcam** provides a tidy interface to the USGS [National Imagery Management System (NIMS)](https://api.waterdata.usgs.gov/nims/v0), the API that stores and serves images collected by stream-gage cameras across the United States. Discover cameras, list and download images, and assemble them into animated GIFs or MP4 videos — all from R.
+
+## Installation
+
+```r
+# install.packages("pak")
+pak::pak("ConnorB/flowcam")
+```
+
+## Quick start
+
+```r
+library(flowcam)
+
+# Store your free USGS API key (one-time setup)
+set_nims_key("your_api_key_here")
+
+# Find the camera at a USGS monitoring location
+cam <- find_cameras(site_id = "08385630")
+
+# List the 20 most recent images with timestamps
+list_images(cam$camId, limit = 20, raw_item = TRUE)
+
+# Download a three-day window to disk
+dest <- file.path(tempdir(), "pecos")
+dir.create(dest)
+
+download_images(
+  cam_id   = cam$camId,
+  dest_dir = dest,
+  size     = "small",
+  time     = c("2025-06-10", "2025-06-12")
+)
+
+# Assemble into an animated GIF
+make_gif(dir = dest, fps = 3, output = "pecos.gif")
+
+# Or an MP4 video
+make_video(dir = dest, fps = 3, output = "pecos.mp4")
+```
+
+## Core functions
+
+| Function | Description |
+|---|---|
+| `find_cameras()` | Retrieve camera metadata; filter by NWIS site number or camera ID |
+| `find_gage_cameras()` | Like `find_cameras()`, plus NWIS site attributes (drainage area, HUC, state) via **dataRetrieval** |
+| `list_images()` | List image filenames for a camera; filter by time window |
+| `download_images()` | Download images to a local directory; resumes safely if interrupted |
+| `make_gif()` | Assemble images into an animated GIF |
+| `make_video()` | Assemble images into an MP4 video |
+
+## Authentication
+
+Register for a free key at <https://api.waterdata.usgs.gov/signup/>. Unauthenticated requests work but share a rate-limit pool. Store the key once and it persists across sessions:
+
+```r
+set_nims_key("your_api_key_here")
+```
+
+`flowcam` uses the same `API_USGS_PAT` environment variable as **dataRetrieval**, so one key covers both packages.
+
+## Learn more
+
+- [Getting started](articles/getting-started.html) — authentication, discovering cameras, listing images, downloading, and creating GIFs and videos in one walkthrough.
+- [Comparing two Pecos River gages](articles/pecos-river.html) — use `find_gage_cameras()` to enrich camera records with watershed metadata, download images from two sites on the same river reach, and produce a GIF and video to track a flow event moving downstream.
+- [Function reference](reference/index.html) — complete documentation for all exported functions.
diff --git a/vignettes/getting-started.qmd b/vignettes/getting-started.qmd
@@ -17,32 +17,47 @@ knitr::opts_chunk$set(
 )
 ```
 
-**flowcam** provides a tidy interface to the USGS [National Imagery Management System (NIMS)](https://api.waterdata.usgs.gov/nims/v0) API, which serves stream-gage camera images collected across the United States.
+**flowcam** gives you a tidy interface to the USGS [National Imagery Management System (NIMS)](https://api.waterdata.usgs.gov/nims/v0) API—the service that stores and serves images collected by stream-gage cameras across the United States. With a few function calls you can discover cameras, list available images, download them to disk, and stitch them into an animated GIF or MP4 video.
+
+Full function reference: <https://connorb.github.io/flowcam/reference/>
+
+```{r library}
+library(flowcam)
+```
 
 ## Authentication
 
-NIMS requests can be made without an API key, but unauthenticated calls are rate-limited. Register for a free key at <https://api.waterdata.usgs.gov/signup/> and store it with `set_nims_key()`:
+NIMS requests work without a key, but unauthenticated traffic shares a rate-limit pool across all users. Register for a free key at <https://api.waterdata.usgs.gov/signup/> and store it once with `set_nims_key()`:
 
 ```{r auth}
-library(flowcam)
-
 set_nims_key("your_api_key_here")
 ```
 
-`set_nims_key()` writes `API_USGS_PAT` to `~/.Renviron` and applies it to the current session immediately. All subsequent API calls in the session—and in future R sessions—use that key automatically. The same environment variable is read by the `dataRetrieval` package, so one key covers both.
+This writes `API_USGS_PAT` to `~/.Renviron` and applies it to the current session immediately. Every subsequent call—in this session and in future R sessions—picks up the key automatically. The `dataRetrieval` package reads the same environment variable, so one key covers both.
+
+## Finding cameras
 
-## Discovering cameras
+`find_cameras()` returns a tibble of camera metadata. Called with no arguments it fetches every camera currently registered in NIMS:
 
-`find_cameras()` returns a tibble of camera metadata. With no arguments it fetches all available cameras; pass `site_id` to narrow results to a specific NWIS site.
+```{r find-all}
+all_cameras <- find_cameras()
+nrow(all_cameras)
+```
 
-The Pecos Web Camera near Roswell, NM (NWIS site 08385630) is a well-known site on the Pecos River:
+Narrow to a specific USGS monitoring location by passing its NWIS site number:
 
-```{r find-cameras}
+```{r find-by-site}
 cam <- find_cameras(site_id = "08385630")
 cam
 ```
 
-Key columns returned:
+This returns the Pecos Web Camera near Roswell, NM. The same record is reachable by its camera identifier:
+
+```{r find-by-cam-id}
+find_cameras(cam_id = "NM_Pecos_Web_Camera_near_Roswell")
+```
+
+Key columns in the result:
 
 | Column | Description |
 |---|---|
@@ -53,97 +68,174 @@ Key columns returned:
 | `TL_enabled` | Whether daily timelapse videos are generated |
 | `smallDir`, `overlayDir`, `thumbDir` | S3 base directories for each image size |
 
-If you already know a camera ID, look it up directly:
-
-```{r find-by-cam-id}
-find_cameras(cam_id = cam$camId[[1]])
-```
-
-To limit network traffic when you only need a few fields, use `return_fields`:
+When you only need a couple of fields—for example when scanning hundreds of cameras—use `return_fields` to keep the response small:
 
 ```{r return-fields}
 find_cameras(
   site_id       = "08385630",
-  return_fields = c("camName", "newestImageDT", "smallDir")
+  return_fields = c("camName", "newestImageDT", "TL_enabled")
 )
 ```
 
-## Listing available images
+`camId` is always returned regardless of what you pass to `return_fields`.
 
-`list_images()` returns the filenames stored for a camera. Filenames alone are enough to build download URLs via `build_image_url()`.
+## Listing available images
 
-```{r list-images}
-cam_id <- cam$camId[[1]]
+`list_images()` returns the filenames stored for a camera. Pass either `cam_id` or `site_id`:
 
-# 10 most recent images
-imgs <- list_images(cam_id, limit = 10)
+```{r list-default}
+imgs <- list_images("NM_Pecos_Web_Camera_near_Roswell", limit = 10)
 imgs
 ```
 
-By default the result is a single-column tibble of filenames. Set `raw_item = TRUE` to also retrieve timestamps and file sizes:
+The default is a single-column tibble of filenames ordered newest-first. Set `raw_item = TRUE` to also retrieve the capture timestamp and file size:
 
 ```{r list-raw}
-list_images(cam_id, limit = 10, raw_item = TRUE)
+list_images("NM_Pecos_Web_Camera_near_Roswell", limit = 10, raw_item = TRUE)
 ```
 
-### Filtering by date and time
+### Filtering by time
+
+The `time` argument accepts a Date, POSIXct, or ISO 8601 character value. A single value means "on or after":
+
+```{r time-single}
+list_images(
+  "NM_Pecos_Web_Camera_near_Roswell",
+  time = "2025-06-15"
+)
+```
 
-Pass POSIXct values (in UTC) to `after` and `before` to fetch images from a specific window:
+A two-element vector sets a closed window. Use `NA` for an open bound:
 
-```{r date-filter}
+```{r time-window}
 list_images(
-  cam_id,
-  after  = as.POSIXct("2025-06-01 00:00:00", tz = "UTC"),
-  before = as.POSIXct("2025-06-02 00:00:00", tz = "UTC")
+  "NM_Pecos_Web_Camera_near_Roswell",
+  time = c("2025-06-01", "2025-06-03")
 )
 ```
 
-## Building image URLs
+### Chronological order
 
-`build_image_url()` combines the camera's base S3 directory with the filenames returned by `list_images()`:
+By default results are newest-first. Pass `recent = FALSE` to flip the order—useful when you want frames in chronological order before building an animation:
 
-```{r build-urls}
-urls <- build_image_url(cam, imgs$filename, size = "small")
-head(urls)
+```{r oldest-first}
+list_images("NM_Pecos_Web_Camera_near_Roswell", limit = 20, recent = FALSE)
 ```
 
-The `size` argument controls image dimensions:
+### Pagination
 
-- `"small"` (default) — ~720 px wide, suitable for monitoring dashboards
-- `"overlay"` — full-size overlay image with gage-reading annotation
-- `"thumb"` — thumbnail ~200 px tall
+The `limit` argument controls the API page size (1–50,000). When the camera has more images than `limit`, `list_images()` paginates automatically using a timestamp cursor and returns all matching records in a single tibble.
 
 ## Downloading images
 
-`download_images()` wraps the steps above into a single call: it finds the camera, lists images, builds URLs, and saves the files to a local directory.
+`download_images()` lists the images for a camera and saves them to a local directory in one call. You must create the destination directory beforehand:
 
-```{r download}
-dest <- tempdir()
+```{r download-basic}
+dest <- file.path(tempdir(), "roswell")
+dir.create(dest, showWarnings = FALSE)
 
 paths <- download_images(
-  cam_id   = cam_id,
+  cam_id   = "NM_Pecos_Web_Camera_near_Roswell",
   dest_dir = dest,
   size     = "small",
-  limit    = 5
+  limit    = 10
 )
+```
+
+`paths` is a character vector of local file paths returned invisibly. Failed downloads are represented as `NA`.
+
+### Image sizes
+
+| `size` | Approximate dimensions | Best for |
+|---|---|---|
+| `"small"` (default) | ~720 px wide | Monitoring, animation |
+| `"overlay"` | Full resolution | Gage-reading annotation visible |
+| `"thumb"` | ~200 px tall | Quick visual overview |
+
+### Time filtering
 
-paths
+Pass the same `time` argument as `list_images()` to restrict which images are downloaded:
+
+```{r download-window}
+paths <- download_images(
+  cam_id   = "NM_Pecos_Web_Camera_near_Roswell",
+  dest_dir = dest,
+  size     = "small",
+  time     = c("2025-06-10", "2025-06-12")
+)
 ```
 
-Already-downloaded files are skipped by default (`overwrite = FALSE`), making it easy to resume a partially completed download. Pass `overwrite = TRUE` to force re-download.
+### Resuming partial downloads
+
+`download_images()` skips files that already exist in `dest_dir` when `overwrite = FALSE` (the default). If a download is interrupted, simply re-run the same call and only the missing files will be fetched.
+
+## Making a GIF
 
-## Timelapse videos
+`make_gif()` fetches images and encodes them into an animated GIF. It requires the `gifski` package.
 
-Many USGS cameras produce a daily timelapse MP4 stitched from images collected throughout the day. `get_timelapse_url()` returns the URL to that file:
+The simplest call streams images directly from NIMS—no separate download step needed:
+
+```{r gif-direct}
+make_gif(
+  cam_id = "NM_Pecos_Web_Camera_near_Roswell",
+  time   = c("2025-06-10", "2025-06-12"),
+  fps    = 2,
+  output = "roswell.gif"
+)
+```
+
+If you already downloaded images with `download_images()`, point to that directory with `dir` to skip re-downloading:
+
+```{r gif-from-dir}
+make_gif(
+  dir    = dest,
+  fps    = 2,
+  output = "roswell.gif"
+)
+```
 
-```{r timelapse}
-url <- get_timelapse_url(cam_id)
-url
+### One frame per day
+
+For a range spanning many days the result can be hundreds of frames. Pass `one_per_day = TRUE` to reduce the animation to a single frame per calendar day, selecting the image whose capture time is closest to local noon:
+
+```{r gif-one-per-day}
+make_gif(
+  cam_id      = "NM_Pecos_Web_Camera_near_Roswell",
+  time        = c("2025-05-01", "2025-06-30"),
+  fps         = 4,
+  one_per_day = TRUE,
+  output      = "roswell_monthly.gif"
+)
+```
+
+When `output` is not specified the file is written to `"<cam_id>.gif"` in the working directory.
+
+## Making a video
+
+`make_video()` produces an MP4 instead of a GIF. It requires the `av` package and accepts the same arguments as `make_gif()`:
+
+```{r video-direct}
+make_video(
+  cam_id = "NM_Pecos_Web_Camera_near_Roswell",
+  time   = c("2025-06-10", "2025-06-12"),
+  fps    = 4,
+  output = "roswell.mp4"
+)
+```
+
+Build from an already-downloaded directory:
+
+```{r video-from-dir}
+make_video(
+  dir    = dest,
+  fps    = 4,
+  output = "roswell.mp4"
+)
 ```
 
-You can open the URL directly in a browser or pass it to a video tool. A warning is emitted when `TL_enabled` is `FALSE` for the camera.
+MP4 files are substantially smaller than equivalent GIFs at the same resolution and frame count, making them preferable for longer time ranges or larger image sizes. GIFs are more portable for sharing in contexts that don't support video embedding.
 
 ## Next steps
 
-- See `vignette("pecos-river")` for a full monitoring workflow combining **flowcam** with streamflow data from **dataRetrieval**.
-- Use `find_gage_cameras()` to retrieve camera metadata enriched with NWIS site attributes (drainage area, elevation, hydrologic unit, etc.).
+- `vignette("pecos-river")` shows how to use `find_gage_cameras()` to enrich camera records with NWIS site metadata and compare two cameras on the same river reach.
+- The full function reference is at <https://connorb.github.io/flowcam/reference/>.
diff --git a/vignettes/pecos-river.qmd b/vignettes/pecos-river.qmd
