sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1660202 - in /sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation: projection/ transform/
Date Mon, 16 Feb 2015 21:06:54 GMT
Author: desruisseaux
Date: Mon Feb 16 21:06:54 2015
New Revision: 1660202

URL: http://svn.apache.org/r1660202
Log:
Documentation editions.

Modified:
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -36,9 +36,8 @@
  * More on this convention is explained below.</p>
  *
  * <p>Users wanting to know more about the available projections and their parameters
should look at the
- * <a href="http://sis.apache.org/CoordinateOperationMethods.html">Coordinate Operation
Methods</a> page.
- * Only users interested in the <em>implementation</em> or parameters of those
projections should look at
- * this package.</p>
+ * <a href="http://sis.apache.org/CoordinateOperationMethods.html">list of coordinate
operation methods</a>.
+ * Only users interested in the <em>implementation</em> of those projections
should look at this package.</p>
  *
  *
  * {@section Definition of terms}
@@ -93,7 +92,7 @@
  * where the other steps change units and swap ordinates.
  * </blockquote>
  *
- * The Geotk implementation extends this rule to axis directions as well, i.e. (<var>x</var>,
<var>y</var>) coordinates
+ * The Apache SIS implementation extends this rule to axis directions as well, i.e. (<var>x</var>,
<var>y</var>) coordinates
  * must be ({@linkplain org.opengis.referencing.cs.AxisDirection#EAST East},
  * {@linkplain org.opengis.referencing.cs.AxisDirection#NORTH North}) oriented.
  *
@@ -164,6 +163,5 @@
  *
  * @see <a href="http://www.remotesensing.org/geotiff/proj_list">Projections list on
RemoteSensing.org</a>
  * @see <a href="http://mathworld.wolfram.com/MapProjection.html">Map projections on
MathWorld</a>
- * @see <a href="http://atlas.gc.ca/site/english/learningresources/carto_corner/map_projections.html">Map
projections on the atlas of Canada</a>
  */
 package org.apache.sis.referencing.operation.projection;

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -81,6 +81,8 @@ import static org.apache.sis.util.Argume
  * @since   0.5
  * @version 0.5
  * @module
+ *
+ * @see DefaultMathTransformFactory
  */
 public abstract class AbstractMathTransform extends FormattableObject
         implements MathTransform, Parameterized, LenientComparable

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -67,21 +67,76 @@ import org.apache.sis.util.resources.Mes
 
 /**
  * Low level factory for creating {@linkplain AbstractMathTransform math transforms}.
- * High level GIS applications usually do not need to use this factory directly.
+ * The objects created by this factory do not know what the source and target coordinate
systems mean.
+ * Because of this low semantic value, high level GIS applications usually do not need to
use this factory directly.
  * They can use the static convenience methods in the {@link org.apache.sis.referencing.CRS}
  * or {@link MathTransforms} classes instead.
  *
- * {@section Math transforms discovery}
- * Unless {@linkplain #DefaultMathTransformFactory(Iterable) specified explicitely at construction
time},
- * {@code OperationMethod} implementations shall be listed in the following file:
- *
- * {@preformat text
- *     META-INF/services/org.opengis.referencing.operation.OperationMethod
- * }
- *
- * {@code DefaultMathTransformFactory} parses the above-cited files in all JAR files in order
to find all available
- * operation methods. By default, only operation methods that implement the {@link MathTransformProvider}
interface
- * can be used by the {@code create(…)} methods in this class.
+ *
+ * {@section Standard parameters}
+ * {@code MathTransform} instances are created from {@linkplain org.apache.sis.parameter.DefaultParameterValueGroup
+ * parameter values}. The parameters expected by each operation available in a default Apache
SIS installation is
+ * <a href="http://sis.apache.org/CoordinateOperationMethods.html">listed here</a>.
+ * The set of parameters varies for each operation or projection, but the following can be
considered typical:
+ *
+ * <ul>
+ *   <li>A <cite>semi-major</cite> and <cite>semi-minor</cite>
axis length in metres.</li>
+ *   <li>A <cite>central meridian</cite> and <cite>latitude of origin</cite>
in decimal degrees.</li>
+ *   <li>A <cite>scale factor</cite>, which default to 1.</li>
+ *   <li>A <cite>false easting</cite> and <cite>false northing</cite>
in metres, which default to 0.</li>
+ * </ul>
+ *
+ * <p>Each descriptor has many aliases, and those aliases may vary between different
projections.
+ * For example the <cite>false easting</cite> parameter is usually called {@code
"false_easting"}
+ * by OGC, while EPSG uses various names like "<cite>False easting</cite>" or
"<cite>Easting at
+ * false origin</cite>".</p>
+ *
+ * {@section Dynamic parameters}
+ * A few non-standard parameters are defined for compatibility reasons,
+ * but delegates their work to standard parameters. Those dynamic parameters are not listed
in the
+ * {@linkplain org.apache.sis.parameter.DefaultParameterValueGroup#values() parameter values}.
+ * Dynamic parameters are:
+ *
+ * <ul>
+ *   <li>{@code "earth_radius"}, which copy its value to the {@code "semi_major"} and
+ *       {@code "semi_minor"} parameter values.</li>
+ *   <li>{@code "inverse_flattening"}, which compute the {@code "semi_minor"} value
from
+ *       the {@code "semi_major"} parameter value.</li>
+ *   <li>{@code "standard_parallel"} expecting an array of type {@code double[]}, which
copy
+ *       its elements to the {@code "standard_parallel_1"} and {@code "standard_parallel_2"}
+ *       parameter scalar values.</li>
+ * </ul>
+ *
+ * <p>The main purpose of those dynamic parameters is to support some less commonly
used conventions
+ * without duplicating the most commonly used conventions. The alternative ways are used
in NetCDF
+ * files for example, which often use spherical models instead than ellipsoidal ones.</p>
+ *
+ *
+ * <a name="Obligation">{@section Mandatory and optional parameters}</a>
+ * Parameters are flagged as either <cite>mandatory</cite> or <cite>optional</cite>.
+ * A parameter may be mandatory and still have a default value. In the context of this package,
"mandatory"
+ * means that the parameter is an essential part of the projection defined by standards.
+ * Such mandatory parameters will always appears in any <cite>Well Known Text</cite>
(WKT) formatting,
+ * even if not explicitly set by the user. For example the central meridian is typically
a mandatory
+ * parameter with a default value of 0° (the Greenwich meridian).
+ *
+ * <p>Optional parameters, on the other hand, are often non-standard extensions.
+ * They will appear in WKT formatting only if the user defined explicitly a value which is
different than the
+ * default value.</p>
+ *
+ *
+ * {@section Operation methods discovery}
+ * {@link OperationMethod} describes all the parameters expected for instantiating a particular
kind of
+ * math transform. The set of operation methods known to this factory can be obtained in
two ways:
+ *
+ * <ul>
+ *   <li>{@linkplain #DefaultMathTransformFactory(Iterable) specified explicitely at
construction time}, or</li>
+ *   <li>{@linkplain #DefaultMathTransformFactory() discovered by scanning the classpath}.</li>
+ * </ul>
+ *
+ * The default way is to scan the classpath. See {@link MathTransformProvider} for indications
about how to add
+ * custom coordinate operation methods in a default Apache SIS installation.
+ *
  *
  * {@section Thread safety}
  * This class is safe for multi-thread usage if all referenced {@code OperationMethod} instances
are thread-safe.
@@ -91,6 +146,9 @@ import org.apache.sis.util.resources.Mes
  * @since   0.6
  * @version 0.6
  * @module
+ *
+ * @see MathTransformProvider
+ * @see AbstractMathTransform
  */
 public class DefaultMathTransformFactory extends AbstractFactory implements MathTransformFactory
{
     /*
@@ -155,7 +213,7 @@ public class DefaultMathTransformFactory
 
     /**
      * Creates a new factory which will discover operation methods with a {@link ServiceLoader}.
-     * {@code OperationMethod} implementations shall be listed in the following file:
+     * The {@link OperationMethod} implementations shall be listed in the following file:
      *
      * {@preformat text
      *     META-INF/services/org.opengis.referencing.operation.OperationMethod
@@ -164,6 +222,8 @@ public class DefaultMathTransformFactory
      * {@code DefaultMathTransformFactory} parses the above-cited files in all JAR files
in order to find all available
      * operation methods. By default, only operation methods that implement the {@link MathTransformProvider}
interface
      * can be used by the {@code create(…)} methods in this class.
+     *
+     * @see #reload()
      */
     public DefaultMathTransformFactory() {
         this(ServiceLoader.load(OperationMethod.class));
@@ -586,20 +646,23 @@ public class DefaultMathTransformFactory
     }
 
     /**
-     * Creates a transform from a group of parameters. The {@code OperationMethod} name is
inferred
-     * from the {@linkplain ParameterDescriptorGroup#getName() parameter group name}.
+     * Creates a transform from a group of parameters.
+     * The set of expected parameters varies for each operation.
+     * The easiest way to provide parameter values is to get an initially empty group for
the desired
+     * operation by calling {@link #getDefaultParameters(String)}, then to fill the parameter
values.
      * Example:
      *
      * {@preformat java
-     *     ParameterValueGroup p = factory.getDefaultParameters("Transverse_Mercator");
-     *     p.parameter("semi_major").setValue(6378137.000);
-     *     p.parameter("semi_minor").setValue(6356752.314);
-     *     MathTransform mt = factory.createParameterizedTransform(p);
+     *     ParameterValueGroup group = factory.getDefaultParameters("Transverse_Mercator");
+     *     group.parameter("semi_major").setValue(6378137.000);
+     *     group.parameter("semi_minor").setValue(6356752.314);
+     *     MathTransform mt = factory.createParameterizedTransform(group);
      * }
      *
-     * @param  parameters The parameter values.
-     * @return The parameterized transform.
-     * @throws NoSuchIdentifierException if there is no transform registered for the coordinate
operation method.
+     * @param  parameters The parameter values. The {@linkplain ParameterDescriptorGroup#getName()
parameter group name}
+     *         shall be the name of the desired {@linkplain DefaultOperationMethod operation
method}.
+     * @return The transform created from the given parameters.
+     * @throws NoSuchIdentifierException if there is no method for the given parameter group
name.
      * @throws FactoryException if the object creation failed. This exception is thrown
      *         if some required parameter has not been supplied, or has illegal value.
      *

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/MathTransformProvider.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -25,33 +25,55 @@ import org.opengis.referencing.operation
 
 
 /**
- * An object capable to create {@code MathTransform} instances from given parameter values.
- * {@code MathTransformProvider} is the Apache SIS mechanism by which
+ * An object capable to create {@link MathTransform} instances from given parameter values.
+ * This interface is the Apache SIS mechanism by which
  * {@linkplain org.apache.sis.referencing.operation.DefaultFormula formula} are concretized
as Java code.
- * There is one {@code MathTransformProvider} for each map projection: one for Mercator,
one for Lambert,
- * <i>etc</i>.
  *
- * <p>This interface is used by {@link DefaultMathTransformFactory} or by developers
who want to plug
- * their own operation methods into Apache SIS. This interface is generally not used directly.
- * The recommended way to get a {@code MathTransform} is to first get the {@code CoordinateOperation}
+ * <p>Implementations of this interface usually extend {@link org.apache.sis.referencing.operation.DefaultOperationMethod},
+ * but this is not mandatory. This interface can also be used alone since {@link MathTransform}
instances can be created
+ * for other purpose than coordinate operations.</p>
+ *
+ * <p>This interface is generally not used directly. The recommended way to get a {@code
MathTransform}
+ * is to {@linkplain org.apache.sis.referencing.CRS#findOperation find the coordinate operation}
  * (generally from a pair of <var>source</var> and <var>target</var>
CRS), then to invoke
- * {@link org.opengis.referencing.operation.CoordinateOperation#getMathTransform()}.</p>
+ * {@link org.opengis.referencing.operation.CoordinateOperation#getMathTransform()}.
+ * Alternative, one can also use a {@linkplain DefaultMathTransformFactory math transform
factory}</p>
+ *
  *
- * {@section How to add custom coordinate operations}
- * To define a custom coordinate operation,
+ * {@section How to add custom coordinate operations to Apache SIS}
+ * {@link DefaultMathTransformFactory} can discover automatically new coordinate operations
+ * (including map projections) by scanning the classpath. To define a custom coordinate operation,
  * one needs to define a <strong>thread-safe</strong> class implementing <strong>both</strong>
this
  * {@code MathTransformProvider} interface and the {@link org.opengis.referencing.operation.OperationMethod}
one.
  * While not mandatory, we suggest to extend {@link org.apache.sis.referencing.operation.DefaultOperationMethod}.
- * Then the fully-qualified class name of that implementation should be listed in a file
having this exact name:
+ * Example:
+ *
+ * <div class="note">{@preformat java
+ *     public class MyProjectionProvider extends DefaultOperationMethod implements MathTransformProvider
{
+ *         public MyProjectionProvider() {
+ *             super(Collections.singletonMap(NAME_KEY, "My projection"),
+ *                     2, // Number of source dimensions
+ *                     2, // Number of target dimensions
+ *                     parameters);
+ *         }
+ *
+ *         &#64;Override
+ *         public MathTransform createMathTransform(ParameterValueGroup values) {
+ *             double semiMajor = values.parameter("semi_major").doubleValue(SI.METRE);
+ *             double semiMinor = values.parameter("semi_minor").doubleValue(SI.METRE);
+ *             // etc...
+ *             return new MyProjection(semiMajor, semiMinor, ...);
+ *         }
+ *     }
+ * }</div>
+ *
+ * Then the fully-qualified class name of that implementation should be listed in a file
reachable on the classpath
+ * with this exact name:
  *
  * {@preformat text
  *     META-INF/services/org.opengis.referencing.operation.OperationMethod
  * }
  *
- * <div class="note"><b>Design note:</b>
- * this {@code MathTransformProvider} interface does not extend {@code OperationMethod} directly
- * in order to allow its usage in other contexts than coordinate operations.</div>
- *
  * @author  Martin Desruisseaux (Geomatys, IRD)
  * @since   0.6
  * @version 0.6
@@ -71,10 +93,12 @@ public interface MathTransformProvider {
      * before to instantiate the transform:
      *
      * {@preformat java
-     *     double semiMajor = values.parameter("semi_major").doubleValue(SI.METRE);
-     *     double semiMinor = values.parameter("semi_minor").doubleValue(SI.METRE);
-     *     // etc...
-     *     return new MyTransform(semiMajor, semiMinor, ...);
+     *     public MathTransform createMathTransform(ParameterValueGroup values) {
+     *         double semiMajor = values.parameter("semi_major").doubleValue(SI.METRE);
+     *         double semiMinor = values.parameter("semi_minor").doubleValue(SI.METRE);
+     *         // etc...
+     *         return new MyProjection(semiMajor, semiMinor, ...);
+     *     }
      * }
      * </div>
      *

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java?rev=1660202&r1=1660201&r2=1660202&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
[UTF-8] Mon Feb 16 21:06:54 2015
@@ -38,57 +38,15 @@
  * in their own {@linkplain org.apache.sis.referencing.operation.projection projection} package.</p>
  *
  *
- * {@section Standard parameters}
- * Some {@code MathTransform} implementations declare a single {@link org.opengis.parameter.ParameterDescriptorGroup}
- * constant named {@code PARAMETERS}. Each group describes all the parameters expected by
the
- * {@linkplain org.apache.sis.referencing.operation.DefaultOperationMethod operation method}
- * associated to the transform implementation.
- * The set of parameters varies for each operation or projection, but the following can be
considered typical:
- *
- * <ul>
- *   <li>A <cite>semi-major</cite> and <cite>semi-minor</cite>
axis length in metres.</li>
- *   <li>A <cite>central meridian</cite> and <cite>latitude of origin</cite>
in decimal degrees.</li>
- *   <li>A <cite>scale factor</cite>, which default to 1.</li>
- *   <li>A <cite>false easting</cite> and <cite>false northing</cite>
in metres, which default to 0.</li>
- * </ul>
- *
- * <p>Each descriptor has many aliases, and those aliases may vary between different
projections.
- * For example the <cite>false easting</cite> parameter is usually called {@code
"false_easting"}
- * by OGC, while EPSG uses various names like "<cite>False easting</cite>" or
"<cite>Easting at
- * false origin</cite>".</p>
- *
- * {@section Dynamic parameters}
- * A few non-standard parameters are defined for compatibility reasons,
- * but delegates their work to standard parameters. Those dynamic parameters are not listed
in the
- * {@linkplain org.apache.sis.parameter.DefaultParameterValueGroup#values() parameter values}.
- * Dynamic parameters are:
- *
- * <ul>
- *   <li>{@code "earth_radius"}, which copy its value to the {@code "semi_major"} and
- *       {@code "semi_minor"} parameter values.</li>
- *   <li>{@code "inverse_flattening"}, which compute the {@code "semi_minor"} value
from
- *       the {@code "semi_major"} parameter value.</li>
- *   <li>{@code "standard_parallel"} expecting an array of type {@code double[]}, which
copy
- *       its elements to the {@code "standard_parallel_1"} and {@code "standard_parallel_2"}
- *       parameter scalar values.</li>
- * </ul>
- *
- * <p>The main purpose of those dynamic parameters is to support some less commonly
used conventions
- * without duplicating the most commonly used conventions. The alternative ways are used
in NetCDF
- * files for example, which often use spherical models instead than ellipsoidal ones.</p>
- *
- *
- * {@section Mandatory and optional parameters}
- * <a name="Obligation">Parameters are flagged as either <cite>mandatory</cite>
or <cite>optional</cite></a>.
- * A parameter may be mandatory and still have a default value. In the context of this package,
"mandatory"
- * means that the parameter is an essential part of the projection defined by standards.
- * Such mandatory parameters will always appears in any <cite>Well Known Text</cite>
(WKT) formatting,
- * even if not explicitly set by the user. For example the central meridian is typically
a mandatory
- * parameter with a default value of 0° (the Greenwich meridian).
- *
- * <p>Optional parameters, on the other hand, are often non-standard extensions.
- * They will appear in WKT formatting only if the user defined explicitly a value which is
different than the
- * default value.</p>
+ * {@section Creating math transforms}
+ * {@code MathTransform} instances can be created either directly or indirectly.
+ * The recommended way is the indirect one: first
+ * {@linkplain org.apache.sis.referencing.CRS#findOperation find the coordinate operation}
+ * (generally from a pair of <var>source</var> and <var>target</var>
CRS), then invoke
+ * {@link org.opengis.referencing.operation.CoordinateOperation#getMathTransform()}.
+ * However sophisticated users can also create math transforms explicitely from a group of
parameter values
+ * using the {@linkplain org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory
math
+ * transform factory}.
  *
  *
  * {@section Non-spatial coordinates}
@@ -104,7 +62,7 @@
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @author  Adrian Custer (Geomatys)
  * @since   0.5
- * @version 0.5
+ * @version 0.6
  * @module
  */
 package org.apache.sis.referencing.operation.transform;



Mime
View raw message