DOC: Adding documentation derived datasets

jmichel-otb · Jul 12, 2016 · bf03eed · bf03eed
1 parent 1a9a5fa
commit bf03eed
Show file tree

Hide file tree

Showing 3 changed files with 245 additions and 1 deletion.
diff --git a/gdal/frmts/derived/deriveddataset.cpp b/gdal/frmts/derived/deriveddataset.cpp
@@ -187,7 +187,7 @@ void GDALRegister_Derived()
 #endif
     poDriver->SetMetadataItem( GDAL_DCAP_VIRTUALIO, "YES" );
     poDriver->SetMetadataItem( GDAL_DMD_LONGNAME, "Derived datasets using VRT pixel functions" );
-    poDriver->SetMetadataItem( GDAL_DMD_HELPTOPIC, "TODO" );
+    poDriver->SetMetadataItem( GDAL_DMD_HELPTOPIC, "frmt_derived.html" );
     poDriver->SetMetadataItem( GDAL_DMD_SUBDATASETS, "NO" );
 
     poDriver->pfnOpen = DerivedDataset::Open;

diff --git a/gdal/frmts/derived/frmt_devided.html b/gdal/frmts/derived/frmt_devided.html
@@ -0,0 +1,236 @@
+<html>
+<head>
+<title>DERIVED -- Derived subdatasets driver</title>
+</head>
+
+<body bgcolor="#ffffff">
+
+<h1>DERIVED -- Derived subdatasets driver</h1>
+
+<p> This driver allows to access to subdatasets derived from a given
+dataset. Those derived datasets have the same projection reference,
+geo-transform and metadata than the original dataset, but derives new
+pixel values using gdal pixel functions.</p>
+
+<h2> Available functions</h2>
+
+<p>Avaiable derived datasets are:
+  <ul>
+    <li>AMPLITUDE: Amplitude of pixels from input bands</li>
+    <li>PHASE: Phase of pixels from input bands</li>
+    <li>REAL: Real part of pixels from input bands</li>
+    <li>IMAG: Imaginary part of pixels from input bands</li>
+    <li>CONJ: Conjugate of pixels from input bands<li>
+    <li>INTENSITY: Intensity (squared amplitude) of pixels from input bands</li>
+    <li>LOGAMPLITUDE: Log10 of amplitude of pixels from input bands</li>
+  </ul>
+  </p>
+
+<p> A typical use is to directly access amplitude, phase or log-amplitude of any complex dataset.</p>
+
+<h2> Accessing derived subdatasets </h2>
+
+<p> Derived subdatasets are stored in the DERIVED_SUBDATASETS metadata domain, and can be accessed using the following syntax:
+</p>
+
+<pre>
+  DERIVED_SUBDATASET:FUNCTION:dataset_name
+</pre>
+
+<p> where function is one of AMPLITUDE, PHASE, REAL, IMAG, CONJ, INTENSITY, LOGAMPLITUDE. So as to ensure numerical precision, all derived subdatasets bands will have Float64 or CFloat64 precision (depending on the function used).</p>
+
+<p> For instance: <p>
+<pre>
+  $ gdalinfo cint_sar.tif
+</pre>
+
+<pre>  
+Driver: GTiff/GeoTIFF
+Files: cint_sar.tif
+Size is 5, 6
+Coordinate System is `'
+GCP Projection = 
+GEOGCS["WGS 84",
+    DATUM["WGS_1984",
+        SPHEROID["WGS 84",6378137,298.257223563,
+            AUTHORITY["EPSG","7030"]],
+        AUTHORITY["EPSG","6326"]],
+    PRIMEM["Greenwich",0],
+    UNIT["degree",0.0174532925199433],
+    AUTHORITY["EPSG","4326"]]
+GCP[  0]: Id=1, Info=
+          (-1910.5,-7430.5) -> (297.507,16.368,0)
+GCP[  1]: Id=2, Info=
+          (588.5,-7430.5) -> (297.938,16.455,0)
+GCP[  2]: Id=3, Info=
+          (588.5,7363.5) -> (297.824,16.977,0)
+GCP[  3]: Id=4, Info=
+          (-1910.5,7363.5) -> (297.393,16.89,0)
+Metadata:
+  AREA_OR_POINT=Area
+  CEOS_ACQUISITION_TIME=19970718024119087               
+  CEOS_ELLIPSOID=GEM6            
+  CEOS_INC_ANGLE=24.824
+  CEOS_LINE_SPACING_METERS=3.9900000
+  CEOS_LOGICAL_VOLUME_ID=0001667400297672
+  CEOS_PIXEL_SPACING_METERS=7.9040000
+  CEOS_PIXEL_TIME_DIR=INCREASE
+  CEOS_PLATFORM_HEADING=347.339
+  CEOS_PLATFORM_LATITUDE=16.213
+  CEOS_PLATFORM_LONGITUDE=-65.311
+  CEOS_PROCESSING_AGENCY=ESA     
+  CEOS_PROCESSING_COUNTRY=ITALY       
+  CEOS_PROCESSING_FACILITY=ES          
+  CEOS_SEMI_MAJOR=6378.1440000
+  CEOS_SEMI_MINOR=6356.7590000
+  CEOS_SENSOR_CLOCK_ANGLE=90.000
+  CEOS_SOFTWARE_ID=ERS2-SLC-6.1
+  CEOS_TRUE_HEADING=345.5885834
+Image Structure Metadata:
+  INTERLEAVE=BAND
+Corner Coordinates:
+Upper Left  (    0.0,    0.0)
+Lower Left  (    0.0,    6.0)
+Upper Right (    5.0,    0.0)
+Lower Right (    5.0,    6.0)
+Center      (    2.5,    3.0)
+Band 1 Block=5x6 Type=CInt16, ColorInterp=Gray
+</pre>
+
+<pre>
+  $ gdalinfo DERIVED_SUBDATASET:LOGAMPLITUDE:cint_sar.tif</pre>
+<pre>
+Driver: DERIVED/Derived datasets using VRT pixel functions
+Files: cint_sar.tif
+Size is 5, 6
+Coordinate System is `'
+GCP Projection = 
+GEOGCS["WGS 84",
+    DATUM["WGS_1984",
+        SPHEROID["WGS 84",6378137,298.257223563,
+            AUTHORITY["EPSG","7030"]],
+        AUTHORITY["EPSG","6326"]],
+    PRIMEM["Greenwich",0],
+    UNIT["degree",0.0174532925199433],
+    AUTHORITY["EPSG","4326"]]
+GCP[  0]: Id=1, Info=
+          (-1910.5,-7430.5) -> (297.507,16.368,0)
+GCP[  1]: Id=2, Info=
+          (588.5,-7430.5) -> (297.938,16.455,0)
+GCP[  2]: Id=3, Info=
+          (588.5,7363.5) -> (297.824,16.977,0)
+GCP[  3]: Id=4, Info=
+          (-1910.5,7363.5) -> (297.393,16.89,0)
+Metadata:
+  AREA_OR_POINT=Area
+  CEOS_ACQUISITION_TIME=19970718024119087               
+  CEOS_ELLIPSOID=GEM6            
+  CEOS_INC_ANGLE=24.824
+  CEOS_LINE_SPACING_METERS=3.9900000
+  CEOS_LOGICAL_VOLUME_ID=0001667400297672
+  CEOS_PIXEL_SPACING_METERS=7.9040000
+  CEOS_PIXEL_TIME_DIR=INCREASE
+  CEOS_PLATFORM_HEADING=347.339
+  CEOS_PLATFORM_LATITUDE=16.213
+  CEOS_PLATFORM_LONGITUDE=-65.311
+  CEOS_PROCESSING_AGENCY=ESA     
+  CEOS_PROCESSING_COUNTRY=ITALY       
+  CEOS_PROCESSING_FACILITY=ES          
+  CEOS_SEMI_MAJOR=6378.1440000
+  CEOS_SEMI_MINOR=6356.7590000
+  CEOS_SENSOR_CLOCK_ANGLE=90.000
+  CEOS_SOFTWARE_ID=ERS2-SLC-6.1
+  CEOS_TRUE_HEADING=345.5885834
+Corner Coordinates:
+Upper Left  (    0.0,    0.0)
+Lower Left  (    0.0,    6.0)
+Upper Right (    5.0,    0.0)
+Lower Right (    5.0,    6.0)
+Center      (    2.5,    3.0)
+Band 1 Block=5x6 Type=Float64, ColorInterp=Undefined
+</pre>
+
+<h2> Listing available subdatasets </h2>
+
+<p> Available subdatasets are reported in the DERIVED_SUBDATASETS metadata domain. Only functions that make sense will be reported for a given dataset, which means that AMPLITUDE, PHASE, REAL, IMAG, CONJ and INTENSITY will only be reported if the dataset has at least one complex band. Nevertheless, even if not reported, those derived datasets are still reachable with the syntax presented above.
+
+  <pre>
+    $ gdalinfo -mdd DERIVED_SUBDATASETS cint_sar.tif
+  </pre>
+
+<pre>Driver: GTiff/GeoTIFF
+Files: cint_sar.tif
+Size is 5, 6
+Coordinate System is `'
+GCP Projection = 
+GEOGCS["WGS 84",
+    DATUM["WGS_1984",
+        SPHEROID["WGS 84",6378137,298.257223563,
+            AUTHORITY["EPSG","7030"]],
+        AUTHORITY["EPSG","6326"]],
+    PRIMEM["Greenwich",0],
+    UNIT["degree",0.0174532925199433],
+    AUTHORITY["EPSG","4326"]]
+GCP[  0]: Id=1, Info=
+          (-1910.5,-7430.5) -> (297.507,16.368,0)
+GCP[  1]: Id=2, Info=
+          (588.5,-7430.5) -> (297.938,16.455,0)
+GCP[  2]: Id=3, Info=
+          (588.5,7363.5) -> (297.824,16.977,0)
+GCP[  3]: Id=4, Info=
+          (-1910.5,7363.5) -> (297.393,16.89,0)
+Metadata:
+  AREA_OR_POINT=Area
+  CEOS_ACQUISITION_TIME=19970718024119087               
+  CEOS_ELLIPSOID=GEM6            
+  CEOS_INC_ANGLE=24.824
+  CEOS_LINE_SPACING_METERS=3.9900000
+  CEOS_LOGICAL_VOLUME_ID=0001667400297672
+  CEOS_PIXEL_SPACING_METERS=7.9040000
+  CEOS_PIXEL_TIME_DIR=INCREASE
+  CEOS_PLATFORM_HEADING=347.339
+  CEOS_PLATFORM_LATITUDE=16.213
+  CEOS_PLATFORM_LONGITUDE=-65.311
+  CEOS_PROCESSING_AGENCY=ESA     
+  CEOS_PROCESSING_COUNTRY=ITALY       
+  CEOS_PROCESSING_FACILITY=ES          
+  CEOS_SEMI_MAJOR=6378.1440000
+  CEOS_SEMI_MINOR=6356.7590000
+  CEOS_SENSOR_CLOCK_ANGLE=90.000
+  CEOS_SOFTWARE_ID=ERS2-SLC-6.1
+  CEOS_TRUE_HEADING=345.5885834
+Metadata (DERIVED_SUBDATASETS):
+  DERIVED_SUBDATASET_0_NAME=DERIVED_SUBDATASET:AMPLITUDE:cint_sar.tif
+  DERIVED_SUBDATASET_0_DESC=Amplitude of input bands from cint_sar.tif
+  DERIVED_SUBDATASET_1_NAME=DERIVED_SUBDATASET:PHASE:cint_sar.tif
+  DERIVED_SUBDATASET_1_DESC=Phase of input bands from cint_sar.tif
+  DERIVED_SUBDATASET_2_NAME=DERIVED_SUBDATASET:REAL:cint_sar.tif
+  DERIVED_SUBDATASET_2_DESC=Real part of input bands from cint_sar.tif
+  DERIVED_SUBDATASET_3_NAME=DERIVED_SUBDATASET:IMAG:cint_sar.tif
+  DERIVED_SUBDATASET_3_DESC=Imaginary part of input bands from cint_sar.tif
+  DERIVED_SUBDATASET_4_NAME=DERIVED_SUBDATASET:CONJ:cint_sar.tif
+  DERIVED_SUBDATASET_4_DESC=Conjugate of input bands from cint_sar.tif
+  DERIVED_SUBDATASET_5_NAME=DERIVED_SUBDATASET:INTENSITY:cint_sar.tif
+  DERIVED_SUBDATASET_5_DESC=Intensity (squared amplitude) of input bands from cint_sar.tif
+  DERIVED_SUBDATASET_6_NAME=DERIVED_SUBDATASET:LOGAMPLITUDE:cint_sar.tif
+  DERIVED_SUBDATASET_6_DESC=log10 of amplitude of input bands from cint_sar.tif
+Image Structure Metadata:
+  INTERLEAVE=BAND
+Corner Coordinates:
+Upper Left  (    0.0,    0.0)
+Lower Left  (    0.0,    6.0)
+Upper Right (    5.0,    0.0)
+Lower Right (    5.0,    6.0)
+Center      (    2.5,    3.0)
+Band 1 Block=5x6 Type=CInt16, ColorInterp=Gray
+</pre>
+
+<h2>See Also:</h2>
+
+<ul>
+    <li><a href="http://gdal.org/gdal_vrttut.html#gdal_vrttut_creation">Using Derived Bands part of the GDAL VRT tutorial</a></li>
+</ul>
+
+
+</body>
+</html>
diff --git a/gdal/frmts/formats_list.html b/gdal/frmts/formats_list.html
@@ -1139,6 +1139,14 @@ <h1>GDAL Raster Formats</h1>
 </td><td> Yes
 </td></tr>
 
+<tr><td> <a href="frmt_derived.html">Derived</a>
+</td><td> DERIVED
+</td><td> No
+</td><td> Yes
+</td><td> --
+</td><td> Yes
+</td></tr>
+
 <tr><td> <a href="frmt_wcs.html">OGC Web Coverage Service</a>
 </td><td> WCS
 </td><td> No