Stitching rasters into a mosaic with VRTs
Combine many raster tiles into a single mosaicked layer in Felt using a GDAL Virtual Raster (VRT).
When your imagery or elevation data is split across many separate raster files, you can present them to Felt as a single, seamless layer. A Virtual Raster (VRT) is a small XML file that references multiple source rasters and describes how they fit together. Felt reads the VRT and mosaics the sources on the fly, so you don't have to merge millions of pixels into one enormous file.
This feature is only available to customers on the Enterprise plan. To upgrade, contact sales.
When to use this: VRT mosaics work best for combining rasters that cover a contiguous area at similar or identical resolution — for example metatiled elevation DEMs, digital orthophoto quarter quads (DOQQs), and similar tiled imagery products. They are not a good fit for representing sparse datasets scattered across a large area.
Two ways to combine rasters
There are two approaches to turning a collection of raster files into one layer in Felt:
Merge locally, then upload. Use GDAL, QGIS, or rasterio to merge your tiles into a single large raster, then upload that file directly. This is straightforward for smaller datasets, but the merged file can become very large and slow to produce.
Build a VRT and upload it. Host your source rasters somewhere Felt can reach them (a cloud storage bucket or an HTTPS URL), build a small VRT that points at them, and upload just the VRT. Felt mosaics the sources on the fly.
For large collections of tiles or Cloud Optimized GeoTIFFs (COGs), the VRT approach is recommended — the VRT itself is only a few kilobytes, and your source pixels never have to move or be duplicated. The rest of this guide focuses on building and uploading a VRT.
We recommend storing the VRT in the same cloud source or bucket as the source rasters it references. When the VRT lives alongside its COGs, Felt streams the mosaic directly from those sources rather than normalizing everything into a single large COG at upload time.
How a VRT works
A VRT is a plain-text XML file (see the GDAL VRT driver documentation). Rather than containing pixel data, it lists each source raster, where to find it, and where it sits in the combined mosaic. Because it's just a reference file, you can rebuild or edit it at any time without reprocessing your imagery.
Building a VRT with gdalbuildvrt
The easiest way to create a VRT is with the gdalbuildvrt command from the GDAL command line tools.
List the paths to your source rasters in a text file, one per line:
Build the VRT, pointing at that list:
The -r flag sets the resampling method used to build overviews and read between resolutions — use bilinear for continuous data like elevation or temperature, and nearest for categorical or integer data.
Things to get right
A VRT will only mosaic correctly in Felt if a few details are set up properly. These are the most common reasons a VRT fails to display.
Use a single projection across all sources
Every source raster referenced by a VRT must be in the same projection (CRS) — this is a hard requirement. If your sources use different projections, reproject the mismatched ones to a common CRS before building the VRT, for example with gdalwarp:
Once every source shares the same projection, build the VRT from the aligned files.
Make sure your sources have overviews
Overviews (also called pyramids) are pre-computed, lower-resolution copies of a raster that let Felt stream the mosaic efficiently when you're zoomed out. gdalbuildvrt only writes the <OverviewList> tag into the VRT when the source rasters already have overviews. If your sources don't have them, the resulting VRT won't stream properly in Felt.
Before building your VRT, make sure each source raster has overviews — for example by storing them as Cloud Optimized GeoTIFFs, or by adding overviews with gdaladdo:
Use paths Felt can reach
This is the single most common mistake: building a VRT on your own machine and uploading it while its <SourceFilename> entries still point at local disk paths. Felt can't read files on your computer, so the mosaic will be empty.
When your sources are remote, the <SourceFilename> entries must use a GDAL virtual filesystem prefix so Felt knows how to fetch them:
/vsicurl/https://host/path/file.tiffor files behind an HTTP(S) URL/vsis3/bucket/key.tiffor files in Amazon S3
You can build the VRT directly against these paths by listing the virtual-filesystem paths in your files.txt, for example:
Also check the relativeToVRT attribute on each <SourceFilename>:
relativeToVRT="0"means the path is absolute (use this for/vsicurl/and/vsis3/paths).relativeToVRT="1"means the path is interpreted relative to the VRT file's own location.
Open the VRT in a text editor before uploading and confirm every <SourceFilename> points at a location Felt can reach, not a path from the machine where you built it.
Precompute statistics
By default, Felt recalculates summary statistics (min, max, mean, and standard deviation) across the entire mosaic when the VRT is uploaded, so it can pick appropriate color ramps and styling. For a large mosaic this can be slow and may surface errors.
You can avoid this by precomputing non-approximate statistics on each source raster ahead of time so the values are already stored in the files. Computing stats on the VRT itself also helps:
For more detail on optimizing large mosaics, see Raster streaming best practices.
Uploading the VRT to Felt
Once your VRT references reachable sources, upload the .vrt file to Felt the same way you would any other raster. Felt reads the VRT, fetches the source rasters, and presents them as a single mosaicked layer that you can style like any other raster.
Uploading a VRT via the API
Once the VRT is stored in your cloud bucket alongside its source rasters, you can add it to a map programmatically with Felt's upload endpoint by passing the VRT's URL as import_url. Felt resolves the source rasters referenced by the VRT and mosaics them, exactly like a UI upload.
The import_url can be a gs://, s3://, or public https:// URL. For a private bucket, connect the bucket as a source with credentials in Felt first; the upload then authenticates using that connected source. A fully public VRT (with /vsicurl/ source paths) needs no credentials.
For the full request and response reference, see the REST API upload documentation.
Because the VRT lives in your bucket alongside its source rasters, this approach is a good fit for API-driven and automated workflows — for example pipelines that drop new rasters into a bucket and add or refresh the mosaic on a map programmatically.
Need a hand getting a large mosaic set up? Contact our team at support@felt.com.
Last updated
Was this helpful?