Improve STAC generator: add JSON input format

cboettig · cboettig · commit da2ace420322 · 2026-02-06T19:19:57.000-08:00
diff --git a/scripts/README.md b/scripts/README.md
@@ -2,20 +2,71 @@
 
 This directory contains a helper script to generate `layers-config.json` from STAC catalog entries.
 
-## Usage
+## Quick Start
+
+**Recommended: Use a JSON input file** (clearer what you need to specify vs what comes from STAC):
 
 ```bash
-python scripts/stac-to-layers-config.py \
-    --catalog https://s3-west.nrp-nautilus.io/public-data/stac/catalog.json \
-    --output app/layers-config.json \
-    --layer COLLECTION_ID:ASSET_ID:LAYER_KEY:DISPLAY_NAME
+python3 scripts/stac-to-layers-config.py \
+    --input scripts/layers-input-example.json \
+    --output app/layers-config.json
 ```
 
-### Examples
+## Input JSON Format
+
+Create a JSON file specifying which layers to generate:
+
+```json
+{
+    "catalog": "https://s3-west.nrp-nautilus.io/public-data/stac/catalog.json",
+    "titiler_url": "https://titiler.nrp-nautilus.io",
+    "layers": [
+        {
+            "collection_id": "cpad-2025b",
+            "asset_id": "cpad-units-pmtiles",
+            "layer_key": "cpad",
+            "display_name": "California Protected Areas (CPAD)",
+            "comment": "PMTiles vector - filterable properties auto-extracted from STAC"
+        },
+        {
+            "collection_id": "irrecoverable-carbon",
+            "asset_id": "vulnerable-total-2018-cog",
+            "layer_key": "carbon",
+            "display_name": "Vulnerable Carbon",
+            "options": {
+                "colormap": "reds",
+                "rescale": "0,100"
+            },
+            "comment": "COG raster - served via TiTiler"
+        }
+    ]
+}
+```
+
+### What You Specify vs What Comes from STAC
+
+**User-specified (required):**
+- `collection_id`: STAC collection ID
+- `asset_id`: Asset ID from the collection
+- `layer_key`: Key to use in layers-config.json
+
+**User-specified (optional):**
+- `display_name`: Layer display name (falls back to STAC asset title)
+- `options.colormap`: Colormap for raster layers (default: "reds")
+- `options.rescale`: Rescale range for rasters (e.g., "0,100")
+
+**Auto-extracted from STAC:**
+- Attribution (from collection providers/links)
+- Filterable properties (from `table:columns` for vector layers)
+- Asset URLs and types
+- Layer metadata
+
+## Legacy CLI Usage
+
+The script also supports command-line arguments for backward compatibility:
 
-**Generate CPAD layer config:**
 ```bash
-python scripts/stac-to-layers-config.py \
+python3 scripts/stac-to-layers-config.py \
     --catalog https://s3-west.nrp-nautilus.io/public-data/stac/catalog.json \
     --output test-config.json \
     --layer cpad-2025b:cpad-units-pmtiles:cpad:"California Protected Areas (CPAD)"
diff --git a/scripts/layers-input-example.json b/scripts/layers-input-example.json
@@ -0,0 +1,24 @@
+{
+    "catalog": "https://s3-west.nrp-nautilus.io/public-data/stac/catalog.json",
+    "titiler_url": "https://titiler.nrp-nautilus.io",
+    "layers": [
+        {
+            "collection_id": "cpad-2025b",
+            "asset_id": "cpad-units-pmtiles",
+            "layer_key": "cpad",
+            "display_name": "California Protected Areas (CPAD)",
+            "comment": "PMTiles vector layer - filterable properties will be auto-extracted from STAC"
+        },
+        {
+            "collection_id": "irrecoverable-carbon",
+            "asset_id": "vulnerable-total-2018-cog",
+            "layer_key": "carbon",
+            "display_name": "Vulnerable Carbon",
+            "options": {
+                "colormap": "reds",
+                "rescale": "0,100"
+            },
+            "comment": "COG raster layer - will be served via TiTiler"
+        }
+    ]
+}
diff --git a/scripts/stac-to-layers-config.py b/scripts/stac-to-layers-config.py
@@ -202,10 +202,17 @@ def main():
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=__doc__
     )
+    
+    # Input method 1: JSON file
+    parser.add_argument(
+        "--input",
+        help="Path to input JSON file specifying layers (recommended)"
+    )
+    
+    # Input method 2: Command line arguments (legacy)
     parser.add_argument(
         "--catalog",
-        required=True,
-        help="URL to STAC catalog.json"
+        help="URL to STAC catalog.json (required if not using --input)"
     )
     parser.add_argument(
         "--output",
@@ -215,7 +222,6 @@ def main():
     parser.add_argument(
         "--layer",
         action="append",
-        required=True,
         metavar="COLLECTION:ASSET:KEY:NAME",
         help="Layer specification: collection_id:asset_id:layer_key:display_name (can be specified multiple times)"
     )
@@ -232,49 +238,92 @@ def main():
     
     args = parser.parse_args()
     
-    # Parse layer specifications
+    # Determine input method
+    if args.input:
+        # Load from JSON file
+        input_path = Path(args.input)
+        if not input_path.exists():
+            print(f"Error: Input file '{args.input}' not found", file=sys.stderr)
+            sys.exit(1)
+        
+        with open(input_path) as f:
+            input_config = json.load(f)
+        
+        catalog_url = input_config.get("catalog")
+        if not catalog_url:
+            print("Error: 'catalog' field required in input JSON", file=sys.stderr)
+            sys.exit(1)
+        
+        titiler_url = input_config.get("titiler_url", args.titiler)
+        layer_specs = input_config.get("layers", [])
+        
+        if not layer_specs:
+            print("Error: 'layers' array is empty in input JSON", file=sys.stderr)
+            sys.exit(1)
+    
+    elif args.catalog and args.layer:
+        # Use command-line arguments (legacy mode)
+        catalog_url = args.catalog
+        titiler_url = args.titiler
+        layer_specs = []
+        
+        for layer_spec in args.layer:
+            parts = layer_spec.split(":", 3)
+            if len(parts) < 3:
+                print(f"Error: Invalid layer specification '{layer_spec}'", file=sys.stderr)
+                print("Format: collection_id:asset_id:layer_key[:display_name]", file=sys.stderr)
+                sys.exit(1)
+            
+            layer_specs.append({
+                "collection_id": parts[0],
+                "asset_id": parts[1],
+                "layer_key": parts[2],
+                "display_name": parts[3] if len(parts) > 3 else None,
+                "options": {}
+            })
+    
+    else:
+        print("Error: Must specify either --input or both --catalog and --layer", file=sys.stderr)
+        parser.print_help()
+        sys.exit(1)
+    
+    # Generate layers configuration
     layers_config = {
         "version": "1.0",
         "description": "Map layer configuration for California Protected Lands application",
         "layers": {}
     }
     
-    for layer_spec in args.layer:
-        parts = layer_spec.split(":", 3)
-        if len(parts) < 3:
-            print(f"Error: Invalid layer specification '{layer_spec}'", file=sys.stderr)
-            print("Format: collection_id:asset_id:layer_key[:display_name]", file=sys.stderr)
-            sys.exit(1)
-        
-        collection_id = parts[0]
-        asset_id = parts[1]
-        layer_key = parts[2]
-        display_name = parts[3] if len(parts) > 3 else None
+    for spec in layer_specs:
+        collection_id = spec.get("collection_id")
+        asset_id = spec.get("asset_id")
+        layer_key = spec.get("layer_key")
+        display_name = spec.get("display_name")
+        options = spec.get("options", {})
         
         print(f"Processing {collection_id}:{asset_id} -> {layer_key}...", file=sys.stderr)
         
         # Find collection URL
-        collection_url = find_collection_url(args.catalog, collection_id)
+        collection_url = find_collection_url(catalog_url, collection_id)
         if not collection_url:
             print(f"Error: Collection '{collection_id}' not found in catalog", file=sys.stderr)
             sys.exit(1)
         
         # Fetch collection
         collection = fetch_json(collection_url)
         
-        # Generate layer config
-        # For COG layers, try to infer rescale from asset title or use default
-        rescale = None
-        if "carbon" in asset_id.lower():
-            rescale = "0,100"  # Reasonable default for carbon data
+        # Get options with defaults
+        colormap = options.get("colormap", args.colormap)
+        rescale = options.get("rescale")
         
+        # Generate layer config
         layer_config = generate_layer_config(
             collection,
             asset_id,
             layer_key,
             display_name,
-            args.titiler,
-            args.colormap,
+            titiler_url,
+            colormap,
             rescale
         )
         
