ISO Geometry
------------

The OpenGIS module defines a set of interfaces aligned with the ISO 19107 Geometry Specification.

Before we get distracted in details here is the section of ISO 19107 we actually use. You will see these
classes in a casual use of GeoTools.


.. image:: /images/geometry_iso3.PNG

That is it - just three of them:

* ``Envelope`` represents an extent with an upper and lower bounds
* ``BoundingBox`` specifically represents a two dimensional extent
* ``DirectPosition`` is a location on the earth defined using a set of ordinates, and a ``CoordinateReferenceSystem`` so we can tell what the numbers mean

ISO 19107
^^^^^^^^^

While they follow roughly the same idea as JTS, the follow things through in three stages.
There is a lot of noise in the above diagram as "helpful" interfaces have been defined to
isolate common qualities.

* High Level "Geometry" classes
  
  * ``Point``
  * ``Curve``
  * ``Surface``

* Composed of smaller segments or patches
  
  * ``Point`` is defined by a single ``DirectPosition``
  * ``Curve`` is defined as a series of ``CurveSegment``
  * ``Surface`` is defined as a series of ``SurfacePatch``

* There is a wide range of options when defining a segment or patch
  
  * ``LineString`` - a simple list of ``LineSegments`` (just like we are used to)
  * ``SplineCurve`` - a range of common splines such as ``BSpline``
  * ``Conic`` - very useful for great circles in GIS
  * ``ArcString`` - common with CAD drawings

Here is an example of the types defined around ``Geometry``, see if you can spot ``Point``, ``Curve`` and ``Surface`` mentioned above.


.. image:: /images/geometry_iso.PNG
   :width: 510
   :height: 578

Here is an example of the selection available when defining a curve.

.. image:: /images/geometry_iso2.PNG
   :width: 371
   :height: 359

These interfaces are many, varied, and well documented. The problem is they are not useful.

* They are complex (in comparison to the Simple Feature Specification used by JTS)
* The two implementations are unsupported modules
  
  * Geometry Plugin a port of JTS 1.7 to the ISO Geometry interfaces
  * JTS Wrapper Plugin an implementation that delegates all the work to JTS
  
  You should only include one on your CLASSPATH at any point in time.

* Q: I want to work in 3D?
  
  I am afraid we cannot be much help at this time, you are welcome to pick up one of the
  unsupported modules above. We welcome volunteers.

* Q: I need to represent Curves?
  
  Have a look at our JTS utility class, there are methods that help you define a JTS ``LineString``
  based on a curve formula.

* Q: Which implementation should I use?
  
  Neither - unless you have a direct need for these implementations
  (because you are limiting your project to ISO19107 only interfaces)
  they are not recommended.
  
  * The ``JTSWrapper`` implementation is field tested, but limited to
    constructs similar to JTS. On the bright side because it always
    uses the latest JTS the performance of this implementation has
    improved over time.
  
  * The Geometry module has now had a lot of testing; but since it
    is a port of JTS 1.7 it will lag behind JTS in speed. It is
    however less complicated in terms of duplication of
    information.

* Q: How do I use ISO Geometry
  
  Check out the documentation for the unsupported Geometry Plugin.
  There is a nice series of source code examples.
