forked from cogeotiff/www.cogeo.org
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdevelopers-guide.html
105 lines (87 loc) · 6.11 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
<!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>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/user/virtual_file_systems#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><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>