Author: desruisseaux
Date: Thu Sep 19 19:43:43 2013
New Revision: 1524814
URL: http://svn.apache.org/r1524814
Log:
Javadoc (in particular, emphase that those methods does not check the Envelope
CRS).
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrices.java
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrices.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrices.java?rev=1524814&r1=1524813&r2=1524814&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrices.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrices.java
[UTF-8] Thu Sep 19 19:43:43 2013
@@ -130,7 +130,7 @@ public final class Matrices extends Stat
/**
* Creates a matrix of size {@code numRow} × {@code numCol} filled with
zero values.
- * This constructor is convenient when the caller want to initialize the
matrix elements himself.
+ * This constructor is convenient when the caller wants to initialize the
matrix elements himself.
*
* <blockquote><font size=-1><b>Implementation note:</b>
* For {@code numRow} == {@code numCol} with a value between
@@ -263,9 +263,20 @@ public final class Matrices extends Stat
* then the transform will append trailing ordinates with the 0
value.</li>
* </ul>
*
- * <b>Example:</b> Given a source envelope of size 100 × 200 (the units do
not matter for this method)
- * and a destination envelope of size 300 × 500, and given the {@linkplain
Envelope#getLowerCorner()
- * lower corner} translated from (-20, -40) to (-10, -25), then the
following method call:
+ * This method ignores the {@linkplain
Envelope#getCoordinateReferenceSystem() envelope CRS}, which may be null.
+ * Actually this method is used more often for {@linkplain
org.opengis.coverage.grid.GridEnvelope grid envelopes}
+ * (which have no CRS) than geodetic envelopes.
+ *
+ * {@section Spanning the anti-meridian of a Geographic CRS}
+ * If the given envelopes cross the date line, then this method requires
their {@code getSpan(int)} method
+ * to behave as documented in the {@link
org.apache.sis.geometry.AbstractEnvelope#getSpan(int)} javadoc.
+ * Furthermore the matrix created by this method will produce expected
results only for source or destination
+ * points before the date line, since the wrap around operation can not be
represented by an affine transform.
+ *
+ * {@section Example}
+ * Given a source envelope of size 100 × 200 (the units do not matter for
this method) and a destination
+ * envelope of size 300 × 500, and given {@linkplain
Envelope#getLowerCorner() lower corner} translation
+ * from (-20, -40) to (-10, -25), then the following method call:
*
* {@preformat java
* matrix = Matrices.createTransform(
@@ -283,12 +294,6 @@ public final class Matrices extends Stat
* └ ┘ └ ┘ └ ┘
* }
*
- * {@section Spanning the anti-meridian of a Geographic CRS}
- * If the given envelope is crossing the date line, then this method
requires the envelope {@code getSpan(int)}
- * method to behave as documented in the {@link
org.apache.sis.geometry.AbstractEnvelope#getSpan(int)} javadoc.
- * Furthermore the matrix created by this method will produce expected
results only for source or destination
- * points before the date line, since the wrap around operation can not be
represented by an affine transform.
- *
* @param srcEnvelope The source envelope.
* @param dstEnvelope The destination envelope.
* @return The transform from the given source envelope to target envelope.
@@ -345,7 +350,8 @@ public final class Matrices extends Stat
* (<i>easting</i>, <i>northing</i>) - this is the first above
case, but illegal
* to transform (<i>easting</i>, <i>northing</i>) to
(<i>easting</i>, <i>up</i>).}
*
- * <b>Example:</b> the following method call:
+ * {@section Example}
+ * The following method call:
*
* {@preformat java
* matrix = Matrices.createTransform(
@@ -388,8 +394,19 @@ public final class Matrices extends Stat
* <li><code>{@linkplain #createTransform(AxisDirection[],
AxisDirection[]) createTransform}(srcAxes, dstAxes)</code></li>
* </ul>
*
- * <b>Example:</b> combining the examples documented in the above {@code
createTransform(…)} methods,
- * the following method call:
+ * This method ignores the {@linkplain
Envelope#getCoordinateReferenceSystem() envelope CRS}, which may be null.
+ * Actually this method is used more often for {@linkplain
org.opengis.coverage.grid.GridEnvelope grid envelopes}
+ * (which have no CRS) than geodetic envelopes.
+ *
+ * {@section Spanning the anti-meridian of a Geographic CRS}
+ * If the given envelopes cross the date line, then this method requires
their {@code getSpan(int)} method
+ * to behave as documented in the {@link
org.apache.sis.geometry.AbstractEnvelope#getSpan(int)} javadoc.
+ * Furthermore the matrix created by this method will produce expected
results only for source or destination
+ * points on one side of the date line (depending on whether axis
direction is reversed), since the wrap around
+ * operation can not be represented by an affine transform.
+ *
+ * {@section Example}
+ * Combining the examples documented in the above {@code
createTransform(…)} methods, the following method call:
*
* {@preformat java
* matrix = Matrices.createTransform(
@@ -410,13 +427,6 @@ public final class Matrices extends Stat
* └ ┘ └ ┘ └ ┘
* }
*
- * {@section Spanning the anti-meridian of a Geographic CRS}
- * If the given envelope is crossing the date line, then this method
requires the envelope {@code getSpan(int)}
- * method to behave as documented in the {@link
org.apache.sis.geometry.AbstractEnvelope#getSpan(int)} javadoc.
- * Furthermore the matrix created by this method will produce expected
results only for source or destination
- * points on one side of the date line (depending on whether axis
direction is reversed), since the wrap around
- * operation can not be represented by an affine transform.
- *
* @param srcEnvelope The source envelope.
* @param srcAxes The ordered sequence of axis directions for source
coordinate system.
* @param dstEnvelope The destination envelope.
@@ -471,8 +481,9 @@ public final class Matrices extends Stat
* <li>For any row <var>j</var> other than the last row, the column
{@code selectedDimensions[j]}.</li>
* </ul>
*
- * <b>Example:</b> Given
(<var>x</var>,<var>y</var>,<var>z</var>,<var>t</var>) ordinate values, if one
wants to
- * keep (<var>y</var>,<var>x</var>,<var>t</var>) ordinates (note the
<var>x</var> ↔ <var>y</var> swapping)
+ * {@section Example}
+ * Given (<var>x</var>,<var>y</var>,<var>z</var>,<var>t</var>) ordinate
values, if one wants to keep
+ * (<var>y</var>,<var>x</var>,<var>t</var>) ordinates (note the
<var>x</var> ↔ <var>y</var> swapping)
* and discard the <var>z</var> values, then the indices of source
ordinates to select are 1 for <var>y</var>,
* 0 for <var>x</var> and 3 for <var>t</var>. One can use the following
method call:
*
@@ -543,8 +554,8 @@ public final class Matrices extends Stat
* is copied in the last column of the sub-matrix.</li>
* </ul>
*
- * <b>Example:</b> Given the following sub-matrix which converts height
values from feet to metres,
- * then subtract 25 metres:
+ * {@section Example}
+ * Given the following sub-matrix which converts height values from feet
to metres before to subtracts 25 metres:
*
* {@preformat math
* ┌ ┐ ┌ ┐ ┌ ┐
@@ -555,7 +566,7 @@ public final class Matrices extends Stat
*
* Then a call to {@code Matrices.createPassThrough(2, subMatrix, 1)} will
return the following matrix,
* which can be used for converting the height (<var>z</var>) without
affecting the other ordinate values
- * in (<var>x</var>,<var>y</var>,<var>t</var>) coordinates:
+ * (<var>x</var>,<var>y</var>,<var>t</var>):
*
* {@preformat math
* ┌ ┐ ┌ ┐ ┌ ┐
@@ -801,10 +812,12 @@ public final class Matrices extends Stat
* <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT}:
* the two matrices must have the same size and the same element
values,
* but are not required to be the same implementation class (any
{@link Matrix} is okay).</li>
- * <li>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}: same as
{@code BY_CONTRACT}.
+ * <li>{@link ComparisonMode#IGNORE_METADATA IGNORE_METADATA}: same as
{@code BY_CONTRACT},
+ * since matrices have no metadata.</li>
* <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE}:
* the two matrices must have the same size, but the element values
can differ up to some threshold.
- * The threshold value is determined empirically and may change in
any future SIS versions.</li>
+ * The threshold value is determined empirically and may change in
any future SIS versions.
+ * For more control, use {@link #equals(Matrix, Matrix, double,
boolean)} instead.</li>
* </ul>
*
* @param m1 The first matrix to compare, or {@code null}.
