| | 1 | = Cloud optimized GeoTIFF = |
| | 2 | |
| | 3 | == Definition == |
| | 4 | |
| | 5 | A cloud optimized GeoTIFF is a regular GeoTIFF file, aimed at being hosted on a HTTP file server, whose internal organization is friendly for consumption by clients issuing [https://tools.ietf.org/html/rfc7233 HTTP GET range request] ("bytes: start_offset-end_offset" HTTP header). |
| | 6 | |
| | 7 | It contains at its beginning the metadata of the full resolution imagery, followed by the optional presence of overview metadata, and finally the imagery itself. To make it friendly with streaming and progressive rendering, we recommand starting with the imagery of the smallest overview and finishing with the imagery of the full resolution level. |
| | 8 | |
| | 9 | More formally, the structure of such a file is: |
| | 10 | * TIFF / BigTIFF signature |
| | 11 | * IFD ([http://www.awaresystems.be/imaging/tiff/faq.html#q3 Image File Directory]) of full resolution image |
| | 12 | * Values of TIFF tags that don't fit inline in the IFD directory, such as TileOffsets, TileByteCounts and GeoTIFF keys |
| | 13 | * Optional: IFD (Image File Directory) of first overview (typically subsampled by a factor of 2), followed by the values of its tags that don't fit inline |
| | 14 | * Optional: IFD (Image File Directory) of second overview (typically subsampled by a factor of 4), followed by the values of its tags that don't fit inline |
| | 15 | * ... |
| | 16 | * Optional: IFD (Image File Directory) of last overview (typically subsampled by a factor of 2^N^), followed by the values of its tags that don't fit inline |
| | 17 | * Optional: tile content of last overview level |
| | 18 | * ... |
| | 19 | * Optional: tile content of first overview level |
| | 20 | * Tile content of full resolution image. |
| | 21 | |
| | 22 | == How to generate it with GDAL == |
| | 23 | |
| | 24 | Given an input dataset in.tif with already generated internal or external overviews, a cloud optimized GeoTIFF can be generated with: |
| | 25 | |
| | 26 | gdal_translate in.tif out.tif -co TILED=YES -co COPY_SRC_OVERVIEWS=YES -co COMPRESS=DEFLATE |
| | 27 | |
| | 28 | This will result in a images with tiles of dimension 256x256 pixel for main resolution, and 128x128 tiles for overviews. |
| | 29 | |
| | 30 | For an image of 4096x4096 with 4 overview levels, the 5 IFDs and their TileOffsets and TileByteCounts tag data fit into the first 6KB of the file. |
| | 31 | |
| | 32 | == How to read it with GDAL == |
| | 33 | |
| | 34 | GDAL includes special filesystems that can read a file hosted on a HTTP/FTP server by chunks. |
| | 35 | |
| | 36 | The base filesystem is [http://gdal.org/cpl__vsi_8h.html#a4f791960f2d86713d16e99e9c0c36258 /vsicurl/] (Virtual System Interface for Curl) and the filename it accepts are of the form "/vsicurl/http://example.com/path/to/some.tif". They can be used whereever GDAL expects a dataset / filename to be passed: gdalinfo, gdal_translate, GDALOpen() API, etc... |
| | 37 | |
| | 38 | Currently /vsicurl/ uses 16 KB as the minimum unit for downloading with HTTP range requests, and a in-memory cache of up to 1000 16KB blocks, with a least recently used eviction strategy. |
| | 39 | |
| | 40 | To minimize the total number of HTTP requests outside of the target GeoTIFF file, setting the GDAL_DISABLE_READDIR_ON_OPEN=YES and CPL_VSIL_CURL_ALLOWED_EXTENSIONS=tif environment variables/configuration options is recommended so as to avoid any side-car files (such a .ovr, .aux.xml, .aux, etc.) to be probed. |
| | 41 | |
| | 42 | Running gdalinfo or GDALOpen() on such a cloud optimized GeoTIFF will retrieve all the metadata with a single HTTP request of 16 KB. When reading pixels in a tile, only the blocks of 16 KB intersecting the range of the tile will be downloaded. |
| | 43 | |
| | 44 | For files hosted on Amazon S3 storage, with non-public sharing rights, [http://www.gdal.org/cpl__vsi_8h.html#a5b4754999acd06444bfda172ff2aaa16 /vsis3/] can be used. |
