Add getArgusPixelIntensity wrapper for extracting pixel values from Argus imagery

.github/ci-retrigger.txt

@@ -0,0 +1 @@
+Triggering CI for PR #42 by SBFRF on 2026-02-02T00:00:00Z

docs/getArgusPixelIntensity.md

@@ -0,0 +1,101 @@
+# getArgusPixelIntensity
+
+## Overview
+
+The `getArgusPixelIntensity` function is a wrapper around `getArgusImagery` that extracts pixel intensity values from Argus imagery at specified locations. It provides flexible coordinate system support and handles gaps in imagery data.
+
+## Key Features
+
+- **Multiple coordinate systems**: pixel (i,j), FRF (xFRF, yFRF), geographic (lon, lat), NC State Plane
+- **Multiple image types**: timex, var, snap, bright, dark
+- **Channel selection**: individual RGB channels or grayscale
+- **Batch processing**: process multiple times in one call
+- **Gap handling**: returns timestamps with pixel values to identify missing data
+- **Automatic rounding**: times rounded to nearest 30-minute interval
+
+## Function Signature
+
+```python
+def getArgusPixelIntensity(times, location, coordType='FRF', imageType='timex',
+                           channel=None, verbose=True, **kwargs)
+```
+
+## Parameters
+
+- **times** (datetime or list): Single or multiple datetime objects for image retrieval
+- **location** (tuple or dict): Location specification (format depends on coordType)
+- **coordType** (str): Coordinate system type
+  - `'pixel'`: Direct pixel indices (i, j)
+  - `'FRF'`: FRF local coordinates (xFRF, yFRF) in meters
+  - `'LL'`, `'geographic'`, `'LatLon'`: Geographic coordinates (lon, lat)
+  - `'spnc'`, `'ncsp'`: NC State Plane coordinates
+- **imageType** (str): Type of Argus image product
+  - `'timex'`: Time exposure average (default)
+  - `'var'`: Variance
+  - `'snap'`: Snapshot
+  - `'bright'`: Brightest pixels
+  - `'dark'`: Darkest pixels
+- **channel** (str, int, or None): Color channel to extract
+  - `'red'`, `'r'`, `0`: Red channel
+  - `'green'`, `'g'`, `1`: Green channel
+  - `'blue'`, `'b'`, `2`: Blue channel
+  - `'gray'`, `'grey'`, `'bw'`: Grayscale (weighted average)
+  - `None`: Return all RGB channels (default)
+- **verbose** (bool): Enable logging output (default: True)
+- **kwargs**: Additional arguments passed to `findArgusImagery` (e.g., `search_window_hours`, `method`)
+
+## Returns
+
+Dictionary containing:
+- **time**: list of datetime objects for successfully retrieved images
+- **epochtime**: list of epoch times (seconds since 1970-01-01)
+- **intensity**: numpy array of intensity values
+  - Shape: [time] if channel specified
+  - Shape: [time, 3] if channel is None (RGB)
+- **location**: dict with coordinate information (includes xFRF, yFRF, pixel_i, pixel_j)
+- **imageType**: str, image type used
+- **missing_times**: list of datetime objects where no image was found
+
+Returns `None` if no valid images could be retrieved.
+
+## Examples
+
+See `examples/argus_pixel_intensity_example.py` for complete working examples.
+
+### Example 1: Extract red channel using pixel coordinates
+
+```python
+import datetime as DT
+from murgtools.getdata import getArgusPixelIntensity
+
+times = [DT.datetime(2024, 6, 15, 12, 0, 0)]
+location = (500, 300)  # pixel (i, j)
+
+result = getArgusPixelIntensity(
+    times=times,
+    location=location,
+    coordType='pixel',
+    imageType='timex',
+    channel='red'
+)
+```
+
+### Example 2: Extract RGB values using FRF coordinates
+
+```python
+location = (500, 100)  # xFRF, yFRF in meters
+
+result = getArgusPixelIntensity(
+    times=DT.datetime(2024, 6, 15, 12, 0, 0),
+    location=location,
+    coordType='FRF',
+    imageType='timex',
+    channel=None  # All RGB channels
+)
+```
+
+## See Also
+
+- `getArgusImagery`: Retrieve full Argus imagery
+- `findArgusImagery`: Search for available Argus imagery
+- Example script: `examples/argus_pixel_intensity_example.py`

examples/argus_pixel_intensity_example.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+"""Example script demonstrating the use of getArgusPixelIntensity.
+
+This script shows how to extract pixel intensity values from Argus imagery
+at specified locations using different coordinate systems.
+"""
+import datetime as DT
+from murgtools.getdata import getArgusPixelIntensity
+
+
+def example_frf_coordinates():
+    """Example 2: Extract pixel intensity using FRF coordinates."""
+    print("\n" + "=" * 70)
+    print("Example 2: Using FRF coordinates (xFRF, yFRF)")
+    print("=" * 70)
+
+    # FRF coordinates (meters)
+    location = (500, 100)  # xFRF, yFRF
+
+    # Single time
+    time = DT.datetime(2024, 6, 15, 12, 0, 0)
+
+    # Extract RGB values (all channels)
+    result = getArgusPixelIntensity(
+        times=time,
+        location=location,
+        coordType='FRF',
+        imageType='timex',
+        channel=None,  # Return all RGB channels
+        verbose=True,
+        search_window_hours=48,  # Search within 48 hours if exact time not available
+        method=0  # Nearest in time (bidirectional search)
+    )
+
+    if result:
+        print(f"\nSuccessfully retrieved {len(result['time'])} images")
+        print(f"Location: xFRF={result['location']['xFRF']}, yFRF={result['location']['yFRF']}")
+        print(f"Pixel coordinates: i={result['location']['pixel_i']}, j={result['location']['pixel_j']}")
+        print(f"RGB values: {result['intensity']}")
+    else:
+        print("\nNo valid images found")
+
+
+if __name__ == '__main__':
+    print("\n" + "=" * 70)
+    print("Argus Pixel Intensity Extraction Examples")
+    print("=" * 70)
+    print("\nNote: This example will attempt to download real Argus imagery")
+    print("from the FRF server. It may fail if imagery is not available")
+    print("for the specified times.")
+
+    # Run only the FRF coordinates example
+    try:
+        example_frf_coordinates()
+    except Exception as e:
+        print(f"\nExample failed: {e}")
+
+    print("\n" + "=" * 70)
+    print("Example complete")
+    print("=" * 70)

murgtools/getdata/__init__.py

@@ -6,7 +6,8 @@
 """
 
 from .getDataFRF import (getObs, getDataTestBed, gettime, getnc, removeDuplicatesFromDictionary,
-                         get_geotiff_extent, getArgusImagery, threadGetArgusImagery, findArgusImagery)
+                         get_geotiff_extent, getArgusImagery, threadGetArgusImagery, findArgusImagery,
+                         getArgusPixelIntensity)
 from .getOutsideData import forecastData, getSatelliteImagery
 from .getPlotData import alt_PlotData
 
@@ -26,5 +27,6 @@
     "getArgusImagery",
     "threadGetArgusImagery",
     "findArgusImagery",
+    "getArgusPixelIntensity",
     "alt_PlotData",
 ]