Author: desruisseaux
Date: Mon Feb 16 16:46:22 2015
New Revision: 1660162
URL: http://svn.apache.org/r1660162
Log:
Added documentation.
Added:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/package-info.java
(with props)
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
(with props)
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
Added:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/package-info.java?rev=1660162&view=auto
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/package-info.java
(added)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/package-info.java
[UTF-8] Mon Feb 16 16:46:22 2015
@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * {@linkplain
org.apache.sis.referencing.operation.transform.MathTransformProvider Math
transform provider}
+ * implementations. See {@link
org.apache.sis.referencing.operation.transform.MathTransformProvider} for a
+ * discussion of parameters.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @since 0.6
+ * @version 0.6
+ * @module
+ *
+ * @see org.apache.sis.referencing.operation.transform.MathTransformProvider
+ */
+package org.apache.sis.internal.referencing.provider;
Propchange:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/package-info.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/package-info.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Added:
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=1660162&view=auto
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
(added)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
[UTF-8] Mon Feb 16 16:46:22 2015
@@ -0,0 +1,169 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Map projection implementations.
+ * This package is mostly for documentation purpose (each projection documents
its name and parameters)
+ * and for implementors who want to extend a map projection. This package
should usually not be used directly.
+ *
+ * <p>The best way to get a projection is to use the
+ * {@linkplain
org.apache.sis.referencing.operation.DefaultCoordinateOperationFactory
coordinate operation factory}
+ * with the source and target CRS. That factory can bundle the projections
defined in this package, together with any
+ * affine transform required for handling unit conversions and axis swapping,
in a single (potentially concatenated)
+ * operation.</p>
+ *
+ * <p>Users wanting to build their transforms directly should also avoid
instantiating objects directly from this
+ * package and use a {@linkplain
org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory math
+ * transform factory} instead.
+ * The {@link
org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory#createParameterizedTransform
+ * createParameterizedTransform(…)} method of that factory is subjects to the
same rules than this package,
+ * namely input coordinates must be (<var>longitude</var>,
<var>latitude</var>) in decimal degrees
+ * and output coordinates must be (<var>easting</var>, <var>northing</var>) in
metres.
+ * 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>
+ *
+ *
+ * {@section Definition of terms}
+ * <ul>
+ * <li><p><b>Coordinate operation</b><br>
+ * In the particular case of this package, the conversion of geographic
coordinates in any
+ * axis order, geodesic orientation and angular units to projected
coordinates in any axis
+ * order, horizontal orientation and linear units.<p></li>
+ * <li><p><b>Map projection</b> (a.k.a. cartographic projection)<br>
+ * The conversion of geographic coordinates from (<var>longitude</var>,
<var>latitude</var>)
+ * in decimal degrees to projected coordinates (<var>x</var>,
<var>y</var>) in metres.<p></li>
+ * <li><p><b>Unitary projection</b><br>
+ * The conversion of geographic coordinates from (<var>longitude</var>,
<var>latitude</var>)
+ * in radians to projected coordinates (<var>x</var>, <var>y</var>) on a
sphere or ellipse
+ * having a semi-major axis length of 1. This definition may be slightly
relaxed if some
+ * projection-specifics coefficients are concatenated with the
conversions that take place
+ * between the above map projection and this unitary projection.<p></li>
+ * </ul>
+ *
+ *
+ * {@section Axis units and orientation}
+ * Many {@linkplain org.apache.sis.referencing.crs.DefaultGeographicCRS
geographic coordinate reference systems}
+ * use axis in (<var>latitude</var>, <var>longitude</var>) order, but not all.
Axis order, orientation and units
+ * are CRS-dependent. For example some CRS use longitude values increasing
toward
+ * {@linkplain org.opengis.referencing.cs.AxisDirection#EAST East}, while some
others use longitude values
+ * increasing toward {@linkplain org.opengis.referencing.cs.AxisDirection#WEST
West}.
+ * The axis order must be specified in all CRS, and any method working with
them should take their
+ * axis order and units in account.
+ *
+ * <p>However, map projections defined in this package are <strong>transform
steps</strong>, not the full transform
+ * to the final CRS. All projections defined in this package must comply with
the OGC 01-009 specification.
+ * This specification says (quoting section 10.6 at page 34):</p>
+ *
+ * <blockquote>
+ * Cartographic projection transforms are used by projected coordinate
reference systems to map
+ * geographic coordinates (e.g. <var>longitude</var> and <var>latitude</var>)
into (<var>x</var>,
+ * <var>y</var>) coordinates. These (<var>x</var>, <var>y</var>) coordinates
can be imagined to
+ * lie on a plane, such as a paper map or a screen. All cartographic
projection transforms will
+ * have the following properties:
+ *
+ * <ul>
+ * <li>Converts from (<var>longitude</var>, <var>latitude</var>) coordinates
to (<var>x</var>,<var>y</var>).</li>
+ * <li>All angles are assumed to be decimal degrees, and all distances are
assumed to be metres.</li>
+ * <li>The domain should be a subset of {[-180 … 180)×[-90 … 90]}°.</li>
+ * </ul>
+ *
+ * Although all cartographic projection transforms must have the properties
listed above, many projected coordinate
+ * reference systems have different properties. For example, in Europe some
projected coordinate reference systems
+ * use grads instead of decimal degrees, and often the base geographic
coordinate reference system is
+ * (<var>latitude</var>, <var>longitude</var>) instead of
(<var>longitude</var>, <var>latitude</var>).
+ * This means that the cartographic projected transform is often used as a
single step in a series of transforms,
+ * 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
+ * must be ({@linkplain org.opengis.referencing.cs.AxisDirection#EAST East},
+ * {@linkplain org.opengis.referencing.cs.AxisDirection#NORTH North}) oriented.
+ *
+ * <div class="note"><b>Implications on South oriented projections</b><br>
+ * The above rule implies a non-intuitive behavior for the <cite>Transverse
Mercator (South Orientated)</cite>
+ * projection, which still projects coordinates with <var>y</var> values
increasing toward North.
+ * The real axis flip is performed outside this projection package, upon
+ * {@linkplain org.opengis.referencing.cs.CoordinateSystemAxis coordinate
system axis} inspection,
+ * as a concatenation of the North oriented cartographic projection with an
affine transform.
+ * Such axis analysis and transforms concatenation can be performed
automatically by the
+ * {@link
org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory#createBaseToDerived
+ * createBaseToDerived(…)} method defined in the {@code MathTransformFactory}
interface.
+ * The same rule applies to the <cite>Krovak</cite> projection as well (at the
opposite of what ESRI does).
+ * </div>
+ *
+ * In order to reduce the risk of confusion, this package never defines south
oriented map projection.
+ * This rule removes ambiguity when reading a transform in <cite>Well Known
Text</cite> (WKT) format,
+ * since only the north-oriented variant is used and the affine transform
coefficients tell exactly
+ * which axis flips are applied.
+ *
+ *
+ * {@section Projection on unit ellipse}
+ * A map projection in this package is actually the concatenation of the
following transforms, in that order:
+ *
+ * <ul>
+ * <li>{@link
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#normalize(boolean)
normalize} affine transform</li>
+ * <li>{@link
org.apache.sis.referencing.operation.projection.UnitaryProjection} subclass</li>
+ * <li>{@link
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#normalize(boolean)
denormalize} affine transform</li>
+ * </ul>
+ *
+ * The first step ("<cite>normalize</cite>") converts longitude and latitude
values from degrees to radians and removes the
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#centralMeridian
central meridian}
+ * from the longitude. The last step ("<cite>denormalize</cite>") multiplies
the result of the middle
+ * step by the global scale factor (which is typically, but not always, the
product of the
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#scaleFactor
scale factor} with the
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#semiMajor
semi-major} axis length),
+ * then adds the
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#falseEasting
false easting} and
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#falseNorthing
false northing}.
+ * This means that the middle step ("<cite>unitary projection</cite>") is
performed on an ellipse
+ * (or sphere) having a semi-major axis of 1.
+ *
+ * <p>In other words, the
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection#transform(double[],int,double[],int,boolean)
+ * transform} method of the middle step works typically on longitude and
latitude values in <strong>radians</strong>
+ * relative to the central meridian (not necessarily Greenwich). Its results
are typically (<var>x</var>, <var>y</var>)
+ * coordinates having ({@linkplain
org.opengis.referencing.cs.AxisDirection#EAST East},
+ * {@linkplain org.opengis.referencing.cs.AxisDirection#NORTH North}) axis
orientation.
+ * However in some cases the actual input and output coordinates may be
different than the above by some scale factor,
+ * translation or rotation, if the projection implementation choose to combine
some linear coefficients with the
+ * above-cited normalize and denormalize affine transforms.</p>
+ *
+ * <div class="note"><b>Note:</b>
+ * In <a href="http://www.remotesensing.org/proj/";>PROJ.4</a>, the same
standardization is handled by {@code pj_fwd.c}
+ * and {@code pj_inv.c}. This normalization makes the equations closer to the
ones published in Snyder's book, where the
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#falseEasting
false easting},
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#falseNorthing
false northing} and
+ * {@linkplain
org.apache.sis.referencing.operation.projection.UnitaryProjection.Parameters#scaleFactor
scale factor}
+ * are usually not given.
+ * </div>
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @author Rémi Maréchal (Geomatys)
+ * @author Adrian Custer (Geomatys)
+ * @since 0.6
+ * @version 0.6
+ * @module
+ *
+ * @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;
Propchange:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
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=1660162&r1=1660161&r2=1660162&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 16:46:22 2015
@@ -37,6 +37,60 @@
* <p>This package does not include map projections, which are a special kind
of transforms defined
* 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 Non-spatial coordinates}
* {@code MathTransform} usually performs conversions or transformations from
points given in a
* {@linkplain
org.apache.sis.referencing.operation.DefaultCoordinateOperation#getSourceCRS()
@@ -48,6 +102,7 @@
* transfer functions}.
*
* @author Martin Desruisseaux (IRD, Geomatys)
+ * @author Adrian Custer (Geomatys)
* @since 0.5
* @version 0.5
* @module
