sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1794573 [2/10] - in /sis/site/trunk/book: en/ fr/
Date Tue, 09 May 2017 13:09:59 GMT
Modified: sis/site/trunk/book/en/geometry.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/geometry.html?rev=1794573&r1=1794572&r2=1794573&view=diff
==============================================================================
--- sis/site/trunk/book/en/geometry.html [UTF-8] (original)
+++ sis/site/trunk/book/en/geometry.html [UTF-8] Tue May  9 13:09:58 2017
@@ -31,181 +31,183 @@
       Content below this point is copied in "../../content/book/en/developer-guide.html"
       by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
     -->
-    <header>
-      <h1 id="Geometry">Geometries</h1>
-    </header>
-    <p>
-      This chapter introduces a few aspects of <abbr>ISO</abbr> 19107 standard
(<i>Spatial schema</i>)
-      and the Apache <abbr>SIS</abbr> classes that implement them.
-    </p>
-
-
-
-    <h2 id="Geometry-root">Base classes</h2>
-    <p>
-      Each geometric object is considered an infinite set of points.
-      As a set, their most fundamental operations are of the same nature as the standard
operations of Java collections.
-      We may therefore see a geometry as a kind of <code>java.util.Set</code>
in which the elements are points,
-      except that the number of elements contained in the set is infinite (with the exception
of geometries representing a simple point).
-      To better represent this concept, the <abbr>ISO</abbr> standard and GeoAPI
define a <code class="OGC">TransfiniteSet</code> interface
-      which we could see as a <code>Set</code> of infinite size.
-      Although a parent relationship exists conceptually between these interfaces,
-      GeoAPI does not define <code class="GeoAPI">TransfiniteSet</code> as a
sub-interface of <code>java.util.Set</code>,
-      as the definition of certain methods such as <code>size()</code> and <code>iterator()</code>
would be problematic.
-      However, we find very similar methods such as <code class="GeoAPI">contains(…)</code>
and <code class="GeoAPI">intersects(…)</code>.
-    </p>
-    <p>
-      All geometries are specializations of <code>TransfiniteSet</code>.
-      The parent class of those geometries is called <code>GM_Object</code> in
<abbr>ISO</abbr> 19107 standard.
-      GeoAPI interfaces use the <code>Geometry</code> name instead, as the omission
of the <code class="OGC">GM_</code>
-      prefix (as prescribed in GeoAPI convention) would leave a name too similar to Java's
<code>Object</code> class.
-    </p>
-
-
-
-    <h3 id="DirectPosition">Direct points and positions</h3>
-    <p>
-      <abbr>ISO</abbr> 19107 defines two types of structures to represent a point:
-      <code>GM_Point</code> and <code class="OGC">DirectPosition</code>.
-      The first type is a true geometry and may therefore be relatively cumbersome, depending
on the implementation.
-      The second type is not formally considered to be a geometry;
-      it extends neither <code>GM_Object</code> nor <code class="OGC">TransfiniteSet</code>.
-      It barely defines any operations besides the storing of a sequence of numbers representing
a coordinate.
-      It may therefore be a more lightweight object.
-    </p>
-    <p>
-      In order to allow the <abbr>API</abbr> to work equally with these two types
of positions,
-      <abbr>ISO</abbr> 19107 defines <code class="OGC">Position</code>
as a <cite>union</cite> of
-      <code class="OGC">DirectPosition</code> and <code>GM_Point</code>.
-      It is a union in the sense of C/C++. For the Java language, GeoAPI obtains the same
effect by defining
-      <code>Position</code> as the parent interface of <code>DirectPosition</code>
and <code>Point</code>.
-      In practice, the great majority of Apache <abbr>SIS</abbr>'s <abbr>API</abbr>
works on <code>DirectPosition</code>s,
-      or occasionally on <code>Position</code>s when it seems useful to also
allow geometric points.
-    </p>
-
-
-
-    <h3 id="Envelope">Envelopes</h3>
-    <p>
-      Envelopes store minimal and maximal coordinate values of a geometry.
-      Envelopes are <em>not</em> geometries themselves; they are not infinite
sets of points (<code class="OGC">TransfiniteSet</code>).
-      There is no guarantee that all the positions contained within the limits of an envelope
are geographically valid.
-      Envelopes must be seen as information about extreme values that might take the coordinates
of a geometry as if
-      each dimension were independent of the others, nothing more.
-      Nevertheless, we speak of envelopes as rectangles, cubes or hyper-cubes (depending
on the number of dimensions)
-      in order to facilitate discussion, while bearing in mind their non-geometric nature.
-    </p>
-    <div class="example"><p><b>Example:</b>
-      We could test whether a position is within the limits of an envelope.
-      A positive result does not guarantee that the position is within the geometry delimited
by the envelope,
-      but a negative result guarantees that it is outside the envelope.
-      We can perform intersection tests in the same way.
-      On the other hand, it makes little sense to apply a rotation to an envelope,
-      as the result may be very different from that which we would obtain be performing a
rotation on the original geometry,
-      and then recalculating its envelope.
-    </p></div>
-    <p>
-      An envelope might be represented by two positions corresponding to two opposite corners
of a rectangle,
-      cube or hyper-cube.
-      For the first corner, we often take the one whose ordinates all have the maximal value
(<code class="OGC">upperCorner</code>).
-      When displayed using a conventional system of coordinates (with <var>y</var>
axis values running upwards),
-      these two positions appear respectively in the lower left corner and the upper right
corner of a rectangle.
-      Care must be taken with different coordinate systems, however, which may vary the positions
of these corners on the screen.
-      The expressions <i>lower corner</i> and <i>upper corner</i>
should thus be understood in the mathematical rather than the visual sense.
-    </p>
-
-
-
-    <h4 id="AntiMeridian">Envelopes that cross the antimeridian</h4>
-    <p>
-      Minimums and maximums are the values most often assigned to <code class="OGC">lowerCorner</code>
-      and <code class="OGC">upperCorner</code>.
-      But the situation becomes complicated when an envelope crosses the antimeridian (-180°
or 180° longitude).
-      For example, an envelope 10° in size may begin at 175° longitude and end at -175°.
-      In this case, the longitude value assigned to <code class="OGC">lowerCorner</code>
is greater than that assigned to <code class="OGC">upperCorner</code>.
-      Apache <abbr>SIS</abbr> therefore uses a slightly different definition
of these two corners:
-    </p>
-    <ul>
-      <li><b><code class="SIS">lowerCorner</code>:</b>
-        the starting point, if we move along the inside of the envelope in the direction
of ascending values.
-      </li>
-      <li><b><code class="SIS">upperCorner</code>:</b>
-        the end-point, if we move along the inside of the envelope in the direction of ascending
values.
-      </li>
-    </ul>
-    <p>
-      If the envelope does not cross the antimeridian, these two definitions are equivalent
to the selection of minimal and
-      maximal values respectively. This is the case in the green rectangle in the figure
below.
-      When the envelope crosses the antimeridian, the <code class="SIS">lowerCorner</code>
and the
-      <code class="SIS">upperCorner</code> appear again at the bottom and top
of the rectangle
-      (assuming a standard system of coordinates), so their names remain appropriate from
a visual standpoint.
-      However, the left and right positions are switched.
-      This case is illustrated by the red rectangle in the figure below.
-    </p>
-    <p style="text-align:center">
-      <img src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"
-           alt="Envelope example with and without anti-meridian spanning."/>
-    </p>
-    <p>
-      The notions of inclusion and intersection, however, interpreted slightly differently
in these two cases.
-      In the usual case where we do not cross the antimeridian, the green rectangle covers
a region of inclusion.
-      The regions excluded from this rectangle continue on to infinity in all directions.
-      In other words, the region of inclusion is not repeated every 360°.
-      But in the case of the red rectangle, the information provided by the envelope actually
covers a region of exclusion
-      between the two edges of the rectangle. The region of inclusion extends to infinity
to the left and right.
-      We could stipulate that all longitudes below -180° or above 180° are considered excluded,
-      but this would be an arbitrary decision that would not be an exact counterpart to the
usual case (green rectangle).
-      A developer may wish to use these values, for example, in a mosaic where the map of
the world is repeated several times
-      horizontally and each repetition is considered distinct.
-      If developers wish to perform operations as though the regions of inclusion or exclusion
were repeated every 360°,
-      they themselves will have to bring the longitudinal values between -180° and 180°
in advance.
-      All the <code class="SIS">add(…)</code>, <code class="SIS">contains(…)</code>,
-      <code class="SIS">intersect(…)</code>, etc. functions of all the envelopes
defined in the
-      <code>org.apache.sis.geometry</code> package perform their calculations
according to this convention.
-    </p>
-    <aside>
-      <h5>Generalizing to other types of axes</h5>
-      <p>
-        This section specifically relates to longitude, as it is the most usual example of
a cyclic axis.
-        However, in Apache <abbr>SIS</abbr> envelopes, there is no explicit mention
of longitude, or of its 360° cycle.
-        The characteristics of the range of values of each axis (its extremum, units, type
of cycle, etc.)
-        are attributes of <code>CoordinateSystemAxis</code> objects,
-        indirectly associated with envelopes via the coordinate reference system.
-        Apache <abbr>SIS</abbr> inspects these attributes to determine the way
in which it must perform these operations.
-        Thus, any axis associated with the code <code>RangeMeaning.WRAPAROUND</code>
benefit from
-        the same treatment as does longitude.
-        For example, this could be a time axis for climatological data (one “year” represents
the average temperature in all the
-        months of January, followed by the average of all the months of February, etc.)
-        This generalization also applies to longitude axes defined by a range of 0° to 360°
rather than -180° to 180°.
-      </p>
-    </aside>
-    <p>
-      In order for functions such as <code class="SIS">add(…)</code> to work
correctly,
-      all objects involved must use the same coordinate reference system, including the same
range of values.
-      Thus an envelope that expresses longitudes in the range [-180 … +180]° is not
compatible with an envelope that expresses
-      longitudes in the range [0 … 360]°.
-      The conversions, if necessary, are up to the user
-      (the <code>Envelopes</code> class provides convenience methods to do this).
-      Moreover, the envelope's coordinates must be included within the system of coordinates,
-      unless the developer explicitly decides to consider (for example) 300° longitude as
a position distinct from -60°.
-      The <code>GeneralEnvelope</code> class provides a <code class="SIS">normalize()</code>
method to bring
-      coordinates within the desired limits, sometimes at the coast of <cite><i>lower</i></cite>
values being higher than
-      <cite><i>upper</i></cite> values.
-    </p>
-    <aside>
-      <h5>The special case of [+0 … -0] range</h5>
-      <p>
-        Java (or more generally, IEEE Standard 754) defines two values distinct from zero:
-        a positive zero and a negative zero. These two values are considered equal when we
compare them with the <code>==</code> operator in Java.
-        But in <abbr>SIS</abbr> envelopes, they may actually return opposite
results for axes using <code>RangeMeaning.WRAPAROUND</code>.
-        An envelope whose range is [0 … 0], [-0 … -0] or [-0 … +0] would normally
be considered an empty envelope,
-        but the [+0 … -0] range would in fact be considered to include the entire set
of values all around the world.
-        This behaviour conforms to the definition of <code class="SIS">lowerCorner</code>
and <code class="SIS">upperCorner</code>,
-        which considers +0 as the starting point, and -0 as the end-point after cycling through
all possible values.
-        Such behaviour only occurs for the pair of values +0 and -0, and only in that order.
-        For all other real values, if the condition <code>lower</code> <code>==</code>
<code>upper</code> is true,
-        then it is guaranteed that the envelope is empty.
+    <section>
+      <header>
+        <h1 id="Geometry">Geometries</h1>
+      </header>
+      <p>
+        This chapter introduces a few aspects of <abbr>ISO</abbr> 19107 standard
(<i>Spatial schema</i>)
+        and the Apache <abbr>SIS</abbr> classes that implement them.
+      </p>
+
+
+
+      <h2 id="Geometry-root">Base classes</h2>
+      <p>
+        Each geometric object is considered an infinite set of points.
+        As a set, their most fundamental operations are of the same nature as the standard
operations of Java collections.
+        We may therefore see a geometry as a kind of <code>java.util.Set</code>
in which the elements are points,
+        except that the number of elements contained in the set is infinite (with the exception
of geometries representing a simple point).
+        To better represent this concept, the <abbr>ISO</abbr> standard and GeoAPI
define a <code class="OGC">TransfiniteSet</code> interface
+        which we could see as a <code>Set</code> of infinite size.
+        Although a parent relationship exists conceptually between these interfaces,
+        GeoAPI does not define <code class="GeoAPI">TransfiniteSet</code> as
a sub-interface of <code>java.util.Set</code>,
+        as the definition of certain methods such as <code>size()</code> and
<code>iterator()</code> would be problematic.
+        However, we find very similar methods such as <code class="GeoAPI">contains(…)</code>
and <code class="GeoAPI">intersects(…)</code>.
+      </p>
+      <p>
+        All geometries are specializations of <code>TransfiniteSet</code>.
+        The parent class of those geometries is called <code>GM_Object</code>
in <abbr>ISO</abbr> 19107 standard.
+        GeoAPI interfaces use the <code>Geometry</code> name instead, as the
omission of the <code class="OGC">GM_</code>
+        prefix (as prescribed in GeoAPI convention) would leave a name too similar to Java's
<code>Object</code> class.
+      </p>
+
+
+
+      <h3 id="DirectPosition">Direct points and positions</h3>
+      <p>
+        <abbr>ISO</abbr> 19107 defines two types of structures to represent a
point:
+        <code>GM_Point</code> and <code class="OGC">DirectPosition</code>.
+        The first type is a true geometry and may therefore be relatively cumbersome, depending
on the implementation.
+        The second type is not formally considered to be a geometry;
+        it extends neither <code>GM_Object</code> nor <code class="OGC">TransfiniteSet</code>.
+        It barely defines any operations besides the storing of a sequence of numbers representing
a coordinate.
+        It may therefore be a more lightweight object.
+      </p>
+      <p>
+        In order to allow the <abbr>API</abbr> to work equally with these two
types of positions,
+        <abbr>ISO</abbr> 19107 defines <code class="OGC">Position</code>
as a <cite>union</cite> of
+        <code class="OGC">DirectPosition</code> and <code>GM_Point</code>.
+        It is a union in the sense of C/C++. For the Java language, GeoAPI obtains the same
effect by defining
+        <code>Position</code> as the parent interface of <code>DirectPosition</code>
and <code>Point</code>.
+        In practice, the great majority of Apache <abbr>SIS</abbr>'s <abbr>API</abbr>
works on <code>DirectPosition</code>s,
+        or occasionally on <code>Position</code>s when it seems useful to also
allow geometric points.
+      </p>
+
+
+
+      <h3 id="Envelope">Envelopes</h3>
+      <p>
+        Envelopes store minimal and maximal coordinate values of a geometry.
+        Envelopes are <em>not</em> geometries themselves; they are not infinite
sets of points (<code class="OGC">TransfiniteSet</code>).
+        There is no guarantee that all the positions contained within the limits of an envelope
are geographically valid.
+        Envelopes must be seen as information about extreme values that might take the coordinates
of a geometry as if
+        each dimension were independent of the others, nothing more.
+        Nevertheless, we speak of envelopes as rectangles, cubes or hyper-cubes (depending
on the number of dimensions)
+        in order to facilitate discussion, while bearing in mind their non-geometric nature.
+      </p>
+      <div class="example"><p><b>Example:</b>
+        We could test whether a position is within the limits of an envelope.
+        A positive result does not guarantee that the position is within the geometry delimited
by the envelope,
+        but a negative result guarantees that it is outside the envelope.
+        We can perform intersection tests in the same way.
+        On the other hand, it makes little sense to apply a rotation to an envelope,
+        as the result may be very different from that which we would obtain be performing
a rotation on the original geometry,
+        and then recalculating its envelope.
+      </p></div>
+      <p>
+        An envelope might be represented by two positions corresponding to two opposite corners
of a rectangle,
+        cube or hyper-cube.
+        For the first corner, we often take the one whose ordinates all have the maximal
value (<code class="OGC">upperCorner</code>).
+        When displayed using a conventional system of coordinates (with <var>y</var>
axis values running upwards),
+        these two positions appear respectively in the lower left corner and the upper right
corner of a rectangle.
+        Care must be taken with different coordinate systems, however, which may vary the
positions of these corners on the screen.
+        The expressions <i>lower corner</i> and <i>upper corner</i>
should thus be understood in the mathematical rather than the visual sense.
+      </p>
+
+
+
+      <h4 id="AntiMeridian">Envelopes that cross the antimeridian</h4>
+      <p>
+        Minimums and maximums are the values most often assigned to <code class="OGC">lowerCorner</code>
+        and <code class="OGC">upperCorner</code>.
+        But the situation becomes complicated when an envelope crosses the antimeridian (-180°
or 180° longitude).
+        For example, an envelope 10° in size may begin at 175° longitude and end at -175°.
+        In this case, the longitude value assigned to <code class="OGC">lowerCorner</code>
is greater than that assigned to <code class="OGC">upperCorner</code>.
+        Apache <abbr>SIS</abbr> therefore uses a slightly different definition
of these two corners:
+      </p>
+      <ul>
+        <li><b><code class="SIS">lowerCorner</code>:</b>
+          the starting point, if we move along the inside of the envelope in the direction
of ascending values.
+        </li>
+        <li><b><code class="SIS">upperCorner</code>:</b>
+          the end-point, if we move along the inside of the envelope in the direction of
ascending values.
+        </li>
+      </ul>
+      <p>
+        If the envelope does not cross the antimeridian, these two definitions are equivalent
to the selection of minimal and
+        maximal values respectively. This is the case in the green rectangle in the figure
below.
+        When the envelope crosses the antimeridian, the <code class="SIS">lowerCorner</code>
and the
+        <code class="SIS">upperCorner</code> appear again at the bottom and top
of the rectangle
+        (assuming a standard system of coordinates), so their names remain appropriate from
a visual standpoint.
+        However, the left and right positions are switched.
+        This case is illustrated by the red rectangle in the figure below.
+      </p>
+      <p style="text-align:center">
+        <img src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"
+             alt="Envelope example with and without anti-meridian spanning."/>
+      </p>
+      <p>
+        The notions of inclusion and intersection, however, interpreted slightly differently
in these two cases.
+        In the usual case where we do not cross the antimeridian, the green rectangle covers
a region of inclusion.
+        The regions excluded from this rectangle continue on to infinity in all directions.
+        In other words, the region of inclusion is not repeated every 360°.
+        But in the case of the red rectangle, the information provided by the envelope actually
covers a region of exclusion
+        between the two edges of the rectangle. The region of inclusion extends to infinity
to the left and right.
+        We could stipulate that all longitudes below -180° or above 180° are considered
excluded,
+        but this would be an arbitrary decision that would not be an exact counterpart to
the usual case (green rectangle).
+        A developer may wish to use these values, for example, in a mosaic where the map
of the world is repeated several times
+        horizontally and each repetition is considered distinct.
+        If developers wish to perform operations as though the regions of inclusion or exclusion
were repeated every 360°,
+        they themselves will have to bring the longitudinal values between -180° and 180°
in advance.
+        All the <code class="SIS">add(…)</code>, <code class="SIS">contains(…)</code>,
+        <code class="SIS">intersect(…)</code>, etc. functions of all the envelopes
defined in the
+        <code>org.apache.sis.geometry</code> package perform their calculations
according to this convention.
+      </p>
+      <aside>
+        <h5>Generalizing to other types of axes</h5>
+        <p>
+          This section specifically relates to longitude, as it is the most usual example
of a cyclic axis.
+          However, in Apache <abbr>SIS</abbr> envelopes, there is no explicit
mention of longitude, or of its 360° cycle.
+          The characteristics of the range of values of each axis (its extremum, units, type
of cycle, etc.)
+          are attributes of <code>CoordinateSystemAxis</code> objects,
+          indirectly associated with envelopes via the coordinate reference system.
+          Apache <abbr>SIS</abbr> inspects these attributes to determine the
way in which it must perform these operations.
+          Thus, any axis associated with the code <code>RangeMeaning.WRAPAROUND</code>
benefit from
+          the same treatment as does longitude.
+          For example, this could be a time axis for climatological data (one “year”
represents the average temperature in all the
+          months of January, followed by the average of all the months of February, etc.)
+          This generalization also applies to longitude axes defined by a range of 0° to
360° rather than -180° to 180°.
+        </p>
+      </aside>
+      <p>
+        In order for functions such as <code class="SIS">add(…)</code> to work
correctly,
+        all objects involved must use the same coordinate reference system, including the
same range of values.
+        Thus an envelope that expresses longitudes in the range [-180 … +180]° is not
compatible with an envelope that expresses
+        longitudes in the range [0 … 360]°.
+        The conversions, if necessary, are up to the user
+        (the <code>Envelopes</code> class provides convenience methods to do
this).
+        Moreover, the envelope's coordinates must be included within the system of coordinates,
+        unless the developer explicitly decides to consider (for example) 300° longitude
as a position distinct from -60°.
+        The <code>GeneralEnvelope</code> class provides a <code class="SIS">normalize()</code>
method to bring
+        coordinates within the desired limits, sometimes at the coast of <cite><i>lower</i></cite>
values being higher than
+        <cite><i>upper</i></cite> values.
       </p>
-    </aside>
+      <aside>
+        <h5>The special case of [+0 … -0] range</h5>
+        <p>
+          Java (or more generally, IEEE Standard 754) defines two values distinct from zero:
+          a positive zero and a negative zero. These two values are considered equal when
we compare them with the <code>==</code> operator in Java.
+          But in <abbr>SIS</abbr> envelopes, they may actually return opposite
results for axes using <code>RangeMeaning.WRAPAROUND</code>.
+          An envelope whose range is [0 … 0], [-0 … -0] or [-0 … +0] would normally
be considered an empty envelope,
+          but the [+0 … -0] range would in fact be considered to include the entire set
of values all around the world.
+          This behaviour conforms to the definition of <code class="SIS">lowerCorner</code>
and <code class="SIS">upperCorner</code>,
+          which considers +0 as the starting point, and -0 as the end-point after cycling
through all possible values.
+          Such behaviour only occurs for the pair of values +0 and -0, and only in that order.
+          For all other real values, if the condition <code>lower</code> <code>==</code>
<code>upper</code> is true,
+          then it is guaranteed that the envelope is empty.
+        </p>
+      </aside>
+    </section>
   </body>
 </html>

Modified: sis/site/trunk/book/en/index.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/index.html?rev=1794573&r1=1794572&r2=1794573&view=diff
==============================================================================
--- sis/site/trunk/book/en/index.html [UTF-8] (original)
+++ sis/site/trunk/book/en/index.html [UTF-8] Tue May  9 13:09:58 2017
@@ -43,13 +43,13 @@
     </nav>
 
     <main>
-      <section><xi:include href="introduction.html"/></section>
-      <section><xi:include href="referencing.html"/></section>
-      <section><xi:include href="geometry.html"/></section>
-      <section><xi:include href="coverage.html"/></section>
-      <section><xi:include href="utility.html"/></section>
-      <section><xi:include href="xml.html"/></section>
-      <section><xi:include href="annexes.html"/></section>
+      <xi:include href="introduction.html"/>
+      <xi:include href="referencing.html"/>
+      <xi:include href="geometry.html"/>
+      <xi:include href="coverage.html"/>
+      <xi:include href="utility.html"/>
+      <xi:include href="xml.html"/>
+      <xi:include href="annexes.html"/>
     </main>
   </body>
 </html>



Mime
View raw message