-
Notifications
You must be signed in to change notification settings - Fork 39
/
developers-guide.html
106 lines (88 loc) · 6.49 KB
/
developers-guide.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
<!DOCTYPE HTML>
<!--
Stellar by HTML5 UP
html5up.net | @ajlkn
Free for personal and commercial use under the CCA 3.0 license (html5up.net/license)
-->
<html>
<head>
<title>Developer's Guide to COG</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<!--[if lte IE 8]><script src="assets/js/ie/html5shiv.js"></script><![endif]-->
<link rel="stylesheet" href="assets/css/main.css" />
<!--[if lte IE 9]><link rel="stylesheet" href="assets/css/ie9.css" /><![endif]-->
<!--[if lte IE 8]><link rel="stylesheet" href="assets/css/ie8.css" /><![endif]-->
</head>
<body>
<!-- Wrapper -->
<div id="wrapper">
<!-- Header -->
<header id="header">
<h1>Utilizing Cloud Optimized GeoTIFF</h1>
<p>A guide for developers</p>
</header>
<!-- Main -->
<div id="main">
<!-- Content -->
<section id="content" class="main">
<h3>Introduction</h3>
<p>This guide will eventually be a stand alone explanation for developers on using and producing Cloud Optimized GeoTIFF's. If you are interested in
contributing then please make pull requests on the <a href="https://github.com/cholmes/www.cogeo.org">Github Project</a>. In the meantime this document will just link to a few other resources</p>
<h3>Reading a Cloud Optimized GeoTIFF</h3>
<p>For C/C++ or Python developers, the easiest way to read a COG in a way that takes advantage of its unique properties is to use GDAL and its <a href="https://gdal.org/en/latest/user/virtual_file_systems.html#network-based-file-systems">VSI Curl</a> functionality. See the GDAL Wiki on Cloud Optimized GeoTIFF in its <a href="https://trac.osgeo.org/gdal/wiki/CloudOptimizedGeoTIFF#HowtoreaditwithGDAL">How to read it with GDAL</a> section. A majority of geospatial software in the world uses GDAL as a library, so incorporating it is likely the fastest way to incorporate COG reading in to your software.</p>
<p>Java developers may find more convenient to use pure Java readers that integrate well with the Java2D framework. Taking advantage of COG properties on file system, HTTP or S3 is possible for example with GeoTools and <a href="https://sis.apache.org/howto/rasters_bigger_than_memory.html">Apache SIS</a> libraries.</p>
<p><a href="http://planet.com">Planet</a> produces all its data as COG, and has a little tutorial on how to <a href="https://developers.planet.com/tutorials/download-a-subarea/">download part of an image</a> using VSI Curl. Most of the tutorial is specific to working with the Planet API, but it shows the use of GDAL Warp with a COG to extract a single farm field from a larger image.
<h3>How to generate a Cloud Optimized GeoTIFF</h3>
<p>As of version 3.1 of GDAL there is a built in <a href="https://gdal.org/drivers/raster/cog.html">COG provider</a> which by default provides tiling and creation of overviews, use it like this:
<pre><code> gdal_translate input.tif output_cog.tif -of COG -co COMPRESS=LZW</code></pre>
</p>
<h4>Older GDAL versions</h4>
<p>There is a GDAL wiki page about COG creation: <a href="https://trac.osgeo.org/gdal/wiki/CloudOptimizedGeoTIFF#HowtogenerateitwithGDAL">How to generate it with GDAL</a>. For quick reference the one liner is:
<pre><code>gdal_translate in.tif out.tif -co TILED=YES -co COPY_SRC_OVERVIEWS=YES -co COMPRESS=DEFLATE</code></pre>
</p>
<h4>Rio-cogeo</h4>
<p>or you can use <a href="https://github.com/cogeotiff/rio-cogeo">rio-cogeo</a> plugin:
<pre><code>$ rio cogeo create in.tif out.tif --cog-profile deflate</code></pre>
</p>
<p>Many other geospatial software should also be able to add the proper overviews and tiles. Please contribute examples!</p>
<h3>Testing your Cloud Optimized GeoTIFF's</h3>
<p>The <a class="ext-link" href="https://github.com/OSGeo/gdal/blob/master/swig/python/gdal-utils/osgeo_utils/samples/validate_cloud_optimized_geotiff.py"><span class="icon"></span>validate_cloud_optimized_geotiff.py</a> script can be used to check that a (GeoTIFF) file follows the above described file structure
</p><p>
<pre><code>$ python validate_cloud_optimized_geotiff.py test.tif
or
$ python
import validate_cloud_optimized_geotiff.py
validate_cloud_optimized_geotiff.validate("test.tif")</code></pre></p>
<p>or you can use <a href="https://github.com/cogeotiff/rio-cogeo">rio-cogeo</a> plugin:
<pre><code>$ rio cogeo validate test.tif</code></pre>
</p>
<p>Note: <a href="http://radiant.earth">Radiant.Earth</a> is also providing a <a href="http://cog-validate.radiant.earth/html">hosted version</a> of the <i>validate_cloud_optimized_geotiff.py<i> script. And if you want to run your own hosted version you can get the <a href="https://github.com/rouault/cog_validator">source code</a>.
<h3>Performance</h3>
<p>See <a href="https://trac.osgeo.org/gdal/wiki/CloudOptimizedGeoTIFF#Performancetesting">COG Performance Testing on GDAL wiki</a> for some of the initial
performance testing</p>
<p>Digital Globe has also done extensive performance testing with their IDAHO project, and found the format as performant as their previous custom scheme.</p>
</section>
</div>
<!-- Footer -->
<footer id="footer">
<section>
<h2>Pull Requests Accepted</h2>
<p>The Cloud Optimized GeoTIFF project and website is fully community driven. If something is not right on the website, or if you want to contribute a tutorial, add your software to the implementation list or tell the world about the awesome data you are making available as COG's then please contribute on GitHub.</p>
<ul class="actions">
<li><a href="https://github.com/cholmes/www.cogeo.org" class="button">Contribute</a></li>
</ul>
</section>
<p class="copyright">© COG Contributors Design: <a href="https://html5up.net">HTML5 UP</a>.</p>
</footer>
</div>
<!-- Scripts -->
<script src="assets/js/jquery.min.js"></script>
<script src="assets/js/jquery.scrollex.min.js"></script>
<script src="assets/js/jquery.scrolly.min.js"></script>
<script src="assets/js/skel.min.js"></script>
<script src="assets/js/util.js"></script>
<!--[if lte IE 8]><script src="assets/js/ie/respond.min.js"></script><![endif]-->
<script src="assets/js/main.js"></script>
</body>
</html>