sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1660162 - in /sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis: internal/referencing/provider/ referencing/operation/projection/ referencing/operation/transform/
Date Mon, 16 Feb 2015 16:46:22 GMT
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



Mime
View raw message