# Serving NAIP aerial imagery from S3 with a tile index
The [National Agriculture Imagery Program]() (NAIP) publishes aerial imagery of the United States as COGs in the `naip-visualization` S3 bucket: one file per USGS quarter-quadrangle, each in its own UTM zone, overlapping its neighbors. This guide serves all of California 2020 as one Martin source with a [tile index](), and shows the Bay Area on a MapLibre map with [OpenFreeMap]() roads on top.
## Prerequisites
- [Martin](), built with the `cog` feature (on by default)
- The [AWS CLI]() and the [GDAL]() command line tools, for `ogr2ogr`
- AWS credentials allowed to read `s3://naip-visualization`. The bucket is **requester pays**: every request is billed to your AWS account, so a request without `--request-payer requester` (or Martin's `aws_request_payer: true`) is denied.
Check your access with a 4 KB range read:
```bash
aws s3api get-object --bucket naip-visualization \
--key ca/2020/60cm/rgb/37122/m_3712213_nw_10_060_20200524.tif \
--request-payer requester --range bytes=0-4095 header.tif
```
## Build the tile index
Each state and year comes with an index of its own: a shapefile with the footprint of every quarter-quadrangle, e.g. `ca/2020/60cm/index/NAIP_20_CA.shp`. Its `FileName` is not quite the file's key, though: it lacks the folder, and ends in an extra date, the version date. For a few files, its image date is also a day off from the key's. So the index is joined to a listing of the files by their names up to the date, which gives every footprint its real key:
```bash
export AWS_REGION=us-west-2 AWS_REQUEST_PAYER=requester
# Every file the bucket has, with its name up to the date, e.g. `m_3712213_nw_10_060`.
aws s3api list-objects-v2 --bucket naip-visualization --request-payer requester \
--prefix ca/2020/60cm/rgb/ --query 'Contents[].Key' --output text | tr '\t' '\n' \
| awk -F/ 'BEGIN { print "key,qq" } /\.tif$/ { print $0 "," substr($NF, 1, 19) }' > files.csv
# The bucket's footprints and the listing, side by side.
ogr2ogr -f GPKG -nln footprints work.gpkg /vsis3/naip-visualization/ca/2020/60cm/index/NAIP_20_CA.shp
ogr2ogr -update -nln files work.gpkg files.csv
# One row per file: its footprint, and where to read it.
ogr2ogr -f GPKG -nln naip naip.gpkg work.gpkg -dialect SQLite -sql \
"SELECT '/vsis3/naip-visualization/' || f.key AS location, p.geom
FROM footprints p JOIN files f ON f.qq = substr(p.FileName, 1, 19)"
```
This takes about 20 seconds for the 11,076 files of California 2020, and reads no file but the index. For another state or year, list its `index/` folder for the shapefile's name.
> [!TIP]
>
> Imagery without an index of its own can be indexed with `gdaltindex -f GPKG -t_srs EPSG:4326`, which reads the header of every file.
## Configure Martin
config.yaml
```yaml
cog:
# An AWS SDK profile with read access to the bucket; any other way of passing credentials works too.
profile: naip
aws_region: us-west-2
# The bucket is requester pays.
aws_request_payer: true
tile_index:
naip:
path: naip.gpkg
minzoom: 14
maxzoom: 19
```
```bash
martin --config config.yaml
curl -o tile.png http://localhost:3000/naip/18/41886/101282
```
The first tile of an area takes a few seconds while Martin opens the files; later tiles reuse them. Zooms outside `minzoom` to `maxzoom` are answered with `404` without reading from S3.
## Show it on a map
This page shows the Golden Gate Bridge at zoom 18 with the roads and labels of OpenFreeMap on top, motorways to secondary roads in pink. `hash: true` keeps the map position in the URL, e.g. `#14/37.93/-122.69`.
Save it as `index.html` and serve it over HTTP, e.g. with `python3 -m http.server 8000`, then open [http://localhost:8000]().
index.html
```html
NAIP z18 demo
NAIP CA 2020 / martin tile_index
source localhost:3000/naip
z naip tile