USGS3DEP_data

{
  "kind": "static",
  "source": {
    "url_template": "https://elevation.nationalmap.gov/arcgis/rest/services/3DEPElevation/ImageServer/exportImage?bbox={bbox_west},{bbox_south},{bbox_east},{bbox_north}&size={width},{height}&format=tiff&bboxSR=4326&imageSR=4326&pixelType=F32&interpolation=+RSP_BilinearInterpolation&f=image"
  },
  "reference": {
    "citation": "U.S. Geological Survey. 3D Elevation Program (3DEP). National Map Elevation Imagery Service. https://elevation.nationalmap.gov/",
    "url": "https://elevation.nationalmap.gov/"
  },
  "metadata": {
    "tags": [
      "elevation",
      "terrain",
      "slope",
      "static",
      "derived",
      "usgs3dep",
      "longlat"
    ],
    "earthscidata_source": "src/usgs3dep.jl::USGS3DEPFileSet, src/usgs3dep.jl::USGS3DEPSlopeFileSet",
    "native_crs_epsg": "EPSG:4326 (geographic longlat / WGS84). At esm 0.8.0 the crs is documentation only — the loader no longer carries a `grid`/crs descriptor; reprojection (longlat identity) is applied at the coupling edge via reprojection/longlat.esm.",
    "native_resolution_deg": {
      "lon": 9.259e-05,
      "lat": 9.259e-05
    },
    "native_staggering": "Cell-centered (lon 'center', lat 'center') — 3DEP is a regular non-staggered raster. At esm 0.8.0 conservative regridding onto a consuming grid is expressed as a coupling expression (regridding/conservative_overlap.esm), not a model `regrid` block; see usgs3dep.esm and the wildlandfire.esm coupling.",
    "native_extent": {
      "lon": [
        -180.0,
        -60.0
      ],
      "lat": [
        17.0,
        72.0
      ]
    },
    "resolution_arc_seconds": 0.333,
    "coverage": "US only (CONUS + Alaska + Hawaii + US territories). Cells outside US territory return NaN.",
    "url_substitutions": "bbox_{west,south,east,north} are the model-domain bounding box in decimal degrees (WGS84); {width} and {height} are pixel dimensions capped at 1000 (= min(1000, round((E-W)/resolution)) and min(1000, round((N-S)/resolution))). These substitution tokens are resolved from the simulation domain at load/fetch time (the native lon/lat cell counts are the resulting raster width/height).",
    "url_defaults": {
      "size_cap": 1000
    },
    "max_request_pixels": "1000x1000",
    "file_format": "GeoTIFF (F32 pixel type)",
    "slope_derivation": "Slope components dzdx/dzdy are derived declaratively in the regridding model usgs3dep.esm as grad(elevation, x|y) — they are NOT loaded here. This loader exposes only the single-band elevation GeoTIFF (GDAL band 'Band1').",
    "static_note": "No temporal block: kind='static' and the absence of `temporal` seed CONST cadence (ess-v9a.5). The runtime fetches the GeoTIFF once per simulation domain. Upstream DataFrequencyInfo uses two bracketing time points solely to satisfy the interp_unsafe interface; no time interpolation occurs.",
    "migration_note": "esm 0.7.0 -> 0.8.0: removed the DataLoader `grid` block (family/crs/dimensions/extents + n_lon/n_lat parameters), which the 0.8.0 schema no longer permits (clean-break removal of the native-grid descriptor, esm-spec §8.4). Native grid geometry is now documented here and materialized downstream via aggregate/coupling; no other field changed.",
    "merged_from": "components/earthsci_data/usgs3dep_loader.esm",
    "merge_note": "Merged from the standalone pure-I/O file components/earthsci_data/usgs3dep_loader.esm, which is deleted by the same commit. The 0.x `X.esm` + `X_loader.esm` split existed only because a loader was a COMPONENT and a {\"ref\"} target had to contain exactly one component. At esm 1.0.0 a data source is NOT a component, not a coupling endpoint and not a scoped-name path root, and `data_sources` no longer counts toward a file's top-level system count — so one file may hold a model AND the data_sources that model consumes and still be mountable by {\"ref\"}. This registry entry is byte-identical to the one the deleted file declared (it was already mirrored here so this document would validate), and the deleted file's own top-level metadata — name, description, tags, created, authors, references — is preserved verbatim in `merged_file_metadata` so no provenance, citation or migration note is lost.",
    "merged_file_metadata": {
      "name": "USGS3DEP_loader",
      "description": "Pure-I/O data loader for USGS 3D Elevation Program (3DEP) terrain elevation at ~1/3 arc-second (~10 m) resolution. Provides static (time-invariant) terrain elevation on a geographic (longlat/WGS84, EPSG:4326) lattice, sourced from the USGS National Map ImageServer REST API as a GeoTIFF cropped to the model domain.\n\nThis is the loader half of the usgs3dep loader+regridding-model split (RFC pure-io-data-loaders §4.1/§7; bead esm-3nc.4). It is PURE I/O: it declares its source (url_template) and the file variable it reads (elevation, with units). It performs NO reprojection and NO regridding.\n\nMigration esm 0.7.0 -> 0.8.0 (this file): v0.8.0 is a clean break that REMOVED the DataLoader `grid`/`mesh` descriptor (esm-spec §8.4: 'the former native-grid descriptor was removed in v0.8.0'; esm-schema.json DataLoader is now additionalProperties:false over {kind, source, temporal, determinism, variables, reference, metadata} with no `grid` key). Accordingly the former GDD `grid` block (family/crs/dimensions/extents + the n_lon/n_lat grid parameters) has been REMOVED. Grid geometry is now ordinary data: the native geographic lattice (its lon/lat origin = the fetched bbox, its ~0.00009259° spacing, and its runtime-resolved cell counts) is documented in metadata below and is materialized downstream by `aggregate` FAQs / coupling expressions (esm-spec §8.6 — regridding is a coupling expression between two variables, not a loader/model block). The native cell counts are domain-derived: the GeoTIFF is requested at the WGS84 envelope of the model domain, so the raster width/height are resolved from the source response at load time and capped at 1000x1000 pixels per request. Reprojection (longlat identity) and conservative regridding onto a consuming grid are performed at the coupling edge via the reprojection/ and regridding/ template libraries in earthscidiscretizations, NOT here (the model half usgs3dep.esm references this file as a subsystem via {\"ref\": \"./usgs3dep_loader.esm\"}).\n\nThis is a STATIC (time-invariant) dataset: there is NO `temporal` block, so the loader seeds CONST cadence (ess-v9a.5) — the runtime fetches the GeoTIFF once per simulation domain and never refreshes it (kind: static). Cadence derives from the absence of `temporal`, orthogonal to the `kind` enum.\n\nSlope components (dzdx, dzdy) are NOT loaded here — they are derived declaratively in the regridding model usgs3dep.esm as grad(elevation, x|y).\n\nMigrated from EarthSciData.jl@830435a065f27e99f10bba91107ca1730322cc6b:src/usgs3dep.jl:326 (USGS3DEPFileSet, USGS3DEPSlopeFileSet, USGS3DEP constructor). Split out of the pre-migration components/earthsci_data/usgs3dep.esm (esm-tibb); grid block removed in the 0.7.0 -> 0.8.0 migration.",
      "tags": [
        "earthsci_data",
        "elevation",
        "terrain",
        "slope",
        "static",
        "data_loader",
        "pure-io",
        "usgs3dep",
        "dem",
        "longlat"
      ],
      "created": "2026-06-25T00:00:00Z",
      "authors": [
        "EarthSciData.jl contributors",
        "EarthSciModels migration (esm-3nc.4)"
      ],
      "references": [
        {
          "citation": "U.S. Geological Survey. 3D Elevation Program (3DEP). National Map Elevation Imagery Service. https://elevation.nationalmap.gov/",
          "url": "https://elevation.nationalmap.gov/"
        },
        {
          "citation": "Source: EarthSciData.jl@830435a065f27e99f10bba91107ca1730322cc6b:src/usgs3dep.jl:1-410 (USGS3DEPFileSet, USGS3DEPSlopeFileSet, USGS3DEP constructor). Test: test/usgs3dep_test.jl."
        }
      ]
    }
  }
}