sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1814385 - in /sis/site/trunk/content/book: en/developer-guide.html fr/developer-guide.html
Date Sun, 05 Nov 2017 23:27:02 GMT
Author: desruisseaux
Date: Sun Nov  5 23:27:02 2017
New Revision: 1814385

URL: http://svn.apache.org/viewvc?rev=1814385&view=rev
Log:
Regenerate developer guides.

Modified:
    sis/site/trunk/content/book/en/developer-guide.html
    sis/site/trunk/content/book/fr/developer-guide.html

Modified: sis/site/trunk/content/book/en/developer-guide.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/en/developer-guide.html?rev=1814385&r1=1814384&r2=1814385&view=diff
==============================================================================
--- sis/site/trunk/content/book/en/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/en/developer-guide.html [UTF-8] Sun Nov  5 23:27:02 2017
@@ -736,11 +736,81 @@ Text in gray boxes are for information p
 </header>
 <nav>In this chapter:<ul class="toc"/></nav>
 <p>
-<span style="color: red">TODO</span>
+It is possible to instantiate data structures programmatically in memory.
+But more often, data are read from files or other kinds of data stores.
+There is different ways to access those data, but an easy way is to use
+the <code class="sis">DataStores​.open(Object)</code> convenience method.
+The method argument can be a path to a data file
+(<code>File</code>, <code>Path</code>, <code>URL</code>,
<code>URI</code>), a stream
+(<code>Channel</code>, <code>DataInput</code>, <code>InputStream</code>,
<code>Reader</code>),
+a connection to a data base (<code>DataSource</code>, <code>Connection</code>)
+or other kinds of object specific to the data source.
+The <code class="sis">DataStores​.open(Object)</code> method detects data formats
+and returns a <code class="SIS">DataStore</code> instance for that format.
 </p>
+<p>
+<code class="SIS">DataStore</code> functionalities depend on the kind of data
(coverage, feature set, time series, <i>etc.</i>).
+But in any cases, there is always some metadata that can be obtained.
+Metadata allows to identify the phenomenon or features described by the data
+(temperature, land occupation, <i>etc.</i>),
+the geographic area or temporal period covered by the data, together with their resolution.
+Some rich data source provides also a data quality estimation,
+contact information for the responsible person or organization,
+legal or technical constraints on data usage,
+the history of processing apply on the data,
+expected updates schedule, <i>etc.</i>
+</p>
+<p>
+Various data formats have their own metadata model, but Apache <abbr title="Spatial Information
System">SIS</abbr> translates all of them
+in a unique metadata model in order to hide this heterogeneity.
+This approach — to select a single metadata model as the <em>pivot model</em> —
is often used by other libraries.
+For example Apache Tika uses <cite>Dublin Core</cite> as the pivot metadata model,
+while Java Image I/O defines its own standard metadata model in its <code>javax.imageio.metadata</code>
package.
+For Apache <abbr>SIS</abbr>, the chosen pivot model is the <cite><abbr
title="International Organization for Standardization">ISO</abbr> 19115-1:2014 —
Fundamentals</cite>
+international standard, completed by <cite><abbr>ISO</abbr> 19115-2 —
Extensions for imagery and gridded data</cite>.
+This model organizes metadata in a tree structure where each information is accessible by
a well-defined path,
+regardless the origin of that information.
+For example if a data format can provides a geographic bounding box encompassing all data,
+then that information will always be accessible (regardless the data format) from the root
<code class="GeoAPI">Metadata</code> object
+under the <code class="OGC">identificationInfo</code> node, <code class="OGC">extent</code>
sub-node,
+<code class="OGC">geographicElement</code> sub-node.
+</p>
+<div class="example"><p><b>Example:</b>
+following code read a metadata file from a Landsat-8 image and prints the declared geographic
bounding box:
+</p>
+
+<pre><code><b>try</b> (<code class="SIS">DataStore</code>
ds = DataStores.open(<b>new</b> File(<i>"LC81230522014071LGN00_MTL.txt"</i>)))
{
+    <code class="GeoAPI">Metadata</code> md = ds.getMetadata();
+
+    <code class="comment">// In order to make this example simpler, null values and
empty collection checks are omited.
+</code>    <code class="GeoAPI">Identification</code>   idInfo = md   
.getIdentificationInfo().iterator().next();
+    <code class="GeoAPI">Extent</code>           extent = idInfo.getExtents()
          .iterator().next();
+    <code class="GeoAPI">GeographicExtent</code> bbox   = extent.getGeographicElements().iterator().next();
+
+    System.out.println(<i>"The geographic bounding box is:"</i>);
+    System.out.println(bbox);
+}</code></pre>
+
+<p>
+This example produces the following output (this area is located in Vietnam):
+</p>
+
+<pre><samp>The geographic bounding box is:
+Geographic Bounding Box
+  ├─West bound longitude…………………………… 108°20′10,464″E
+  ├─East bound longitude…………………………… 110°26′39,66″E
+  ├─South bound latitude…………………………… 10°29′59,604″N
+  └─North bound latitude…………………………… 12°37′25,716″N</samp></pre>
+
+<p>
+The Java code in this example extracts metadata elements by Java method invocations like
<code class="GeoAPI">getExtents()</code>,
+but the next chapters will introduce another way using paths given as character strings.
+That later approach is more convenient when the methods to invoke are not known at compile-time.
+</p>
+</div>
 
 <p>
-The <abbr title="International Organization for Standardization">ISO</abbr> 19115
standard defines hundreds of elements.
+The <abbr>ISO</abbr> 19115 standard defines hundreds of elements.
 Some of them will be introduced progressively in next chapters.
 But in order to give some idea about what is available, the following table lists a few metadata
elements.
 Most of the nodes accept an arbitrary amount of values.

Modified: sis/site/trunk/content/book/fr/developer-guide.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/fr/developer-guide.html?rev=1814385&r1=1814384&r2=1814385&view=diff
==============================================================================
--- sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] Sun Nov  5 23:27:02 2017
@@ -773,21 +773,21 @@ Le lecteur peut ignorer ces boîtes gris
 </header>
 <nav>Dans ce chapitre:<ul class="toc"/></nav>
 <p>
-Bien qu’il soit possible de créer des structures de données directement en mémoire,
+Bien qu’il soit possible de créer des structures de données programmatiquement en mémoire,
 le plus souvent les données sont lues à partir de fichiers ou autres types d’entrepôts.
 Il y a plusieurs moyens d’accéder à ces données, mais une façon pratique est d’utiliser
-la méthode de commodité <code>DataStores​.open(Object)</code>.
+la méthode de commodité <code class="sis">DataStores​.open(Object)</code>.
 L’argument donné à cette méthode peut être un chemin vers un fichier
 (<code>File</code>, <code>Path</code>, <code>URL</code>,
<code>URI</code>),
 un flux d’entrée vers un fichier déjà ouvert
 (<code>Channel</code>, <code>DataInput</code>, <code>InputStream</code>,
<code>Reader</code>),
 une connexion à une base de données (<code>DataSource</code>, <code>Connection</code>)
 ou d’autres types d’objets spécifiques à la source de données.
-La méthode <code>DataStores​.open(Object)</code> se charge de détecter le
format de données
-et retourne une instance de <code>DataStore</code> pouvant le lire.
+La méthode <code class="sis">DataStores​.open(Object)</code> se charge de
détecter le format de données
+et retourne une instance de <code class="SIS">DataStore</code> pouvant le lire.
 </p>
 <p>
-Les fonctionnalités d’un <code>DataStore</code> dépendent de la nature des
données à manipuler
+Les fonctionnalités d’un <code class="SIS">DataStore</code> dépendent de
la nature des données à manipuler
 (couvertures de données, ensembles de géométries, séries temporelles, <i>etc.</i>),
 mais dans tous les cas il y aura toujours au moins quelques méta-données que l’on peut
extraire.
 Les méta-données permettent d’identifier les phénomènes ou entités décrits par les
données
@@ -796,10 +796,10 @@ la région géographique ou la plage tem
 Certains sources suffisamment riches fournissent aussi une estimation de la qualité des
données,
 des informations permettant de contacter la personne ou l’organisme responsable des données,
 les contraintes légales ou techniques à l’utilisation, l’historique des traitements,
-les dates prévues des prochaines mise-à-jour de mises-à-jour, <i>etc.</i>
+les dates prévues des prochaines mises-à-jour, <i>etc.</i>
 </p>
 <p>
-Les différents formats de données ont souvent leur propre modèle de méta-données,
+Les différents formats de données ont souvent leurs propres modèles de méta-données,
 mais Apache <abbr title="Spatial Information System">SIS</abbr> les traduit tous
vers un modèle unique afin de cacher cette hétérogénéité.
 Cette approche, consistant à choisir un seul modèle de méta-données comme <em>modèle
pivot</em>, est fréquemment utilisée par d’autres bibliothèques aussi.
 Par exemple Apache Tika utilise le standard <cite>Dublin Core</cite> comme modèle
pivot,
@@ -811,14 +811,15 @@ Ce modèle organise les méta-données d
 peu importe l’origine de cette information.
 Par exemple si un format de données peut nous fournir les coordonnées géographiques d’une
boîte englobant toutes les données,
 alors cette information sera toujours accessible (peu importe le format de données) à partir
de l’objet <code class="GeoAPI">Metadata</code>
-sous le noeud <code>identificationInfo</code>, sous-noeud <code>extent</code>,
sous-noeud <code>geographicElement</code>.
+sous le noeud <code class="OGC">identificationInfo</code>, sous-noeud <code
class="OGC">extent</code>,
+sous-noeud <code class="OGC">geographicElement</code>.
 </p>
 <div class="example"><p><b>Exemple:</b>
 le code suivant lit un fichier de méta-données d’une image Landsat-8 et affiche les limites
géographiques qui y sont déclarées:
 </p>
 
-<pre><code><b>try</b> (DataStore ds = DataStores.open(<b>new</b>
File(<i>"LC81230522014071LGN00_MTL.txt"</i>))) {
-    <code class="GeoAPI">Metadata</code> md = getMetadata();
+<pre><code><b>try</b> (<code class="SIS">DataStore</code>
ds = DataStores.open(<b>new</b> File(<i>"LC81230522014071LGN00_MTL.txt"</i>)))
{
+    <code class="GeoAPI">Metadata</code> md = ds.getMetadata();
 
     <code class="comment">// Afin de simplifier cet exemple, nous omettons les vérifications
de valeurs nulles ou de collections vides.
 </code>    <code class="GeoAPI">Identification</code>   idInfo = md   
.getIdentificationInfo().iterator().next();
@@ -843,7 +844,7 @@ Geographic Bounding Box
 <p>
 Le code Java dans cet exemple extrait des éléments de méta-données par des appels à
des méthodes Java telles que <code class="GeoAPI">getExtents()</code>,
 mais les chapitres suivants introduiront d’autres façons utilisant des identifiants sous
forme de chaînes de caractères.
-Ces approches alternatives sont plus pratiques lorsque l’on ne connaît pas à l’avance
les méthodes à appeler.
+Ces approches alternatives sont plus pratiques lorsque l’on ne connaît pas au moment de
la compilation quelles méthodes appeler.
 </p>
 </div>
 



Mime
View raw message