static/apidocs/org/apache/sis/referencing/operation/projection/package-summary.html - sis-site - Git at Google

 <!DOCTYPE HTML>
 <!-- NewPage -->
 <html lang="en">
 <head>
 <!-- Generated by javadoc (11.0.4) on Fri Sep 20 12:10:30 CEST 2019 -->
 <title>org.apache.sis.referencing.operation.projection (Apache SIS 1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <meta name="dc.created" content="2019-09-20">
 <meta name="keywords" content="org.apache.sis.referencing.operation.projection package">
 <link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../../../../sis.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../../../../jquery/jquery-ui.css" title="Style">
 <script type="text/javascript" src="../../../../../../script.js"></script>
 <script type="text/javascript" src="../../../../../../jquery/jszip/dist/jszip.min.js"></script>
 <script type="text/javascript" src="../../../../../../jquery/jszip-utils/dist/jszip-utils.min.js"></script>
 <!--[if IE]>
 <script type="text/javascript" src="../../../../../../jquery/jszip-utils/dist/jszip-utils-ie.min.js"></script>
 <![endif]-->
 <script type="text/javascript" src="../../../../../../jquery/jquery-3.3.1.js"></script>
 <script type="text/javascript" src="../../../../../../jquery/jquery-migrate-3.0.1.js"></script>
 <script type="text/javascript" src="../../../../../../jquery/jquery-ui.js"></script>
 </head>
 <body>
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
             parent.document.title="org.apache.sis.referencing.operation.projection (Apache SIS 1.0 API)";
         }
     }
     catch(err) {
     }
 //-->
 var pathtoroot = "../../../../../../";
 var useModuleDirectories = false;
 loadScripts(document, 'script');</script>
 <noscript>
 <div>JavaScript is disabled on your browser.</div>
 </noscript>
 <header role="banner">
 <nav role="navigation">
 <div class="fixedNav">
 <!-- ========= START OF TOP NAVBAR ======= -->
 <div class="topNav"><a id="navbar.top">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
 <a id="navbar.top.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../../../../index.html">Overview</a></li>
 <li class="navBarCell1Rev">Package</li>
 <li>Class</li>
 <li><a href="package-use.html">Use</a></li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../../../index-all.html">Index</a></li>
 <li><a href="../../../../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList" id="allclasses_navbar_top">
 <li><a href="../../../../../../allclasses.html">All&nbsp;Classes</a></li>
 </ul>
 <ul class="navListSearch">
 <li><label for="search">SEARCH:</label>
 <input type="text" id="search" value="search" disabled="disabled">
 <input type="reset" id="reset" value="reset" disabled="disabled">
 </li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_top");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 <noscript>
 <div>JavaScript is disabled on your browser.</div>
 </noscript>
 </div>
 <a id="skip.navbar.top">
 <!--   -->
 </a></div>
 <!-- ========= END OF TOP NAVBAR ========= -->
 </div>
 <div class="navPadding">&nbsp;</div>
 <script type="text/javascript"><!--
 $('.navPadding').css('padding-top', $('.fixedNav').css("height"));
 //-->
 </script>
 </nav>
 </header>
 <main role="main">
 <div class="header">
 <h1 title="Package" class="title">Package&nbsp;org.apache.sis.referencing.operation.projection</h1>
 </div>
 <div class="contentContainer">
 <section role="region"><a id="package.description">
 <!--   -->
 </a>
 <div class="block">Map projection implementations.
  This package is mostly for documentation purpose (each projection documents its name and parameters)
  and for implementers 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
  <a href="../DefaultCoordinateOperationFactory.html" title="class in org.apache.sis.referencing.operation">coordinate operation factory</a>
  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 <a href="../transform/DefaultMathTransformFactory.html" title="class in org.apache.sis.referencing.operation.transform">math
  transform factory</a> instead.
  The <a href="../transform/DefaultMathTransformFactory.html#createParameterizedTransform(org.opengis.parameter.ParameterValueGroup)"><code>createParameterizedTransform(…)</code></a> 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/tables/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>


  <div class="section">Definition of terms</div>
  <ul class="verbose">
    <li><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.</li>
    <li><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.</li>
    <li><b>Normalized 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 normalized projection.</li>
  </ul>


  <div class="section">Axis units and orientation</div>
  Many <a href="../../crs/DefaultGeographicCRS.html" title="class in org.apache.sis.referencing.crs">geographic coordinate reference systems</a>
  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
  <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/cs/AxisDirection.html?is-external=true#EAST" title="class or interface in org.opengis.referencing.cs" class="externalLink">East</a>, while some others use longitude values
  increasing toward <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/cs/AxisDirection.html?is-external=true#WEST" title="class or interface in org.opengis.referencing.cs" class="externalLink">West</a>.
  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 coordinates.
  </blockquote>

  The Apache SIS implementation extends this rule to axis directions as well, i.e. (<var>x</var>, <var>y</var>) coordinates
  must be (<a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/cs/AxisDirection.html?is-external=true#EAST" title="class or interface in org.opengis.referencing.cs" class="externalLink">East</a>,
  <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/cs/AxisDirection.html?is-external=true#NORTH" title="class or interface in org.opengis.referencing.cs" class="externalLink">North</a>) 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
  <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/cs/CoordinateSystemAxis.html?is-external=true" title="class or interface in org.opengis.referencing.cs" class="externalLink">coordinate system axis</a> 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
  <a href="../transform/DefaultMathTransformFactory.html#createBaseToDerived(org.opengis.referencing.crs.CoordinateReferenceSystem,org.opengis.parameter.ParameterValueGroup,org.opengis.referencing.cs.CoordinateSystem)"><code>createBaseToDerived(…)</code></a> method defined in the <code>MathTransformFactory</code> 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.


  <div class="section">Projection on unit ellipse</div>
  A map projection in this package is actually the concatenation of the following transforms, in that order
  (ignoring <a href="../../cs/CoordinateSystems.html#swapAndScaleAxes(org.opengis.referencing.cs.CoordinateSystem,org.opengis.referencing.cs.CoordinateSystem)">axis order changes</a>
  and conversions from/to units other then degrees and metres, which are not the purpose of this package):

  <ul>
    <li>A <a href="../transform/ContextualParameters.html#normalizeGeographicInputs(double)">normalization</a> affine transform</li>
    <li>A <a href="NormalizedProjection.html" title="class in org.apache.sis.referencing.operation.projection"><code>NormalizedProjection</code></a> subclass</li>
    <li>A <a href="../transform/ContextualParameters.html#getMatrix(org.apache.sis.referencing.operation.transform.ContextualParameters.MatrixRole)">denormalization</a> affine transform</li>
  </ul>

  The first step (<cite>"normalization"</cite>) converts longitude and latitude values from degrees to radians
  and removes the <cite>central meridian</cite> from the longitude.
  The last step (<cite>"denormalization"</cite>) multiplies the result of the middle step by the global scale factor
  (typically the product of the <cite>scale factor</cite> with the <cite>semi-major</cite> axis length),
  then adds the <cite>false easting</cite> and <cite>false northing</cite>.
  This means that the middle step (<cite>"normalized projection"</cite>) is performed on an ellipse (or sphere)
  having a semi-major axis of 1.

  <p>In other words, the
  <a href="NormalizedProjection.html#transform(double%5B%5D,int,double%5B%5D,int,boolean)">transform</a> 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 (<a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/cs/AxisDirection.html?is-external=true#EAST" title="class or interface in org.opengis.referencing.cs" class="externalLink">East</a>,
  <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/cs/AxisDirection.html?is-external=true#NORTH" title="class or interface in org.opengis.referencing.cs" class="externalLink">North</a>) 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 normalization and denormalization affine transforms.</p>

  <div class="note"><b>Note:</b>
  In <a href="http://proj4.org/">Proj.4</a>, the same standardization is handled by <code>pj_fwd.c</code> and <code>pj_inv.c</code>.
  This normalization makes the equations closer to the ones published in Snyder's book, where the
  <cite>false easting</cite>, <cite>false northing</cite> and <cite>scale factor</cite> are usually not given.</div>

  <div class="section">References</div>
  <ul>
    <li>IOGP. <u>Coordinate Conversions and Transformations including Formulas.</u><br>
        Geomatics Guidance Note Number 7, part 2, Version 49.</li>
    <li>Snyder, John P. <u>Map Projections - A Working Manual.</u><br>
        U.S. Geological Survey Professional Paper 1395, 1987.</li>
  </ul></div>
 <dl>
 <dt><span class="simpleTagLabel">Since:</span></dt>
 <dd>0.6</dd>
 <dt><span class="seeLabel">See Also:</span></dt>
 <dd><a href="http://mathworld.wolfram.com/MapProjection.html">Map projections on MathWorld</a></dd>

 <p><font size="-1">Defined in the <code>sis-referencing</code> module</font></p>
 </dl>
 </section>
 <ul class="blockList">
 <li class="blockList">
 <table class="typeSummary">
 <caption><span>Class Summary</span><span class="tabEnd">&nbsp;</span></caption>
 <tr>
 <th class="colFirst" scope="col">Class</th>
 <th class="colLast" scope="col">Description</th>
 </tr>
 <tbody>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="AlbersEqualArea.html" title="class in org.apache.sis.referencing.operation.projection">AlbersEqualArea</a></th>
 <td class="colLast">
 <div class="block"><cite>Albers Equal Area</cite> projection (EPSG code 9822).</div>
 </td>
 </tr>
 <tr class="rowColor">
 <th class="colFirst" scope="row"><a href="CylindricalEqualArea.html" title="class in org.apache.sis.referencing.operation.projection">CylindricalEqualArea</a></th>
 <td class="colLast">
 <div class="block"><cite>Cylindrical Equal Area</cite> projection (EPSG codes 9834, 9835).</div>
 </td>
 </tr>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="LambertConicConformal.html" title="class in org.apache.sis.referencing.operation.projection">LambertConicConformal</a></th>
 <td class="colLast">
 <div class="block"><cite>Lambert Conic Conformal</cite> projection (EPSG codes 9801, 9802, 9803, 9826, 1051).</div>
 </td>
 </tr>
 <tr class="rowColor">
 <th class="colFirst" scope="row"><a href="Mercator.html" title="class in org.apache.sis.referencing.operation.projection">Mercator</a></th>
 <td class="colLast">
 <div class="block"><cite>Mercator Cylindrical</cite> projection (EPSG codes 9804, 9805, 1026, 1024, 1044, <span class="deprecated">9841</span>).</div>
 </td>
 </tr>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="Mollweide.html" title="class in org.apache.sis.referencing.operation.projection">Mollweide</a></th>
 <td class="colLast">
 <div class="block"><cite>Mollweide</cite> projection.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <th class="colFirst" scope="row"><a href="NormalizedProjection.html" title="class in org.apache.sis.referencing.operation.projection">NormalizedProjection</a></th>
 <td class="colLast">
 <div class="block">Base class for conversion services between ellipsoidal and cartographic projections.</div>
 </td>
 </tr>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="ObliqueMercator.html" title="class in org.apache.sis.referencing.operation.projection">ObliqueMercator</a></th>
 <td class="colLast">
 <div class="block"><cite>Oblique Mercator</cite> projection (EPSG codes 9812, 9815).</div>
 </td>
 </tr>
 <tr class="rowColor">
 <th class="colFirst" scope="row"><a href="ObliqueStereographic.html" title="class in org.apache.sis.referencing.operation.projection">ObliqueStereographic</a></th>
 <td class="colLast">
 <div class="block"><cite>Oblique Stereographic</cite> projection (EPSG code 9809).</div>
 </td>
 </tr>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="PolarStereographic.html" title="class in org.apache.sis.referencing.operation.projection">PolarStereographic</a></th>
 <td class="colLast">
 <div class="block"><cite>Polar Stereographic</cite> projection (EPSG codes 9810, 9829, 9830).</div>
 </td>
 </tr>
 <tr class="rowColor">
 <th class="colFirst" scope="row"><a href="Polyconic.html" title="class in org.apache.sis.referencing.operation.projection">Polyconic</a></th>
 <td class="colLast">
 <div class="block"><cite>American Polyconic</cite> projection (EPSG codes 9818).</div>
 </td>
 </tr>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="Sinusoidal.html" title="class in org.apache.sis.referencing.operation.projection">Sinusoidal</a></th>
 <td class="colLast">
 <div class="block"><cite>Sinusoidal equal-area</cite> projection, also known as <cite>"Sanson-Flamsteed"</cite>.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <th class="colFirst" scope="row"><a href="TransverseMercator.html" title="class in org.apache.sis.referencing.operation.projection">TransverseMercator</a></th>
 <td class="colLast">
 <div class="block"><cite>Transverse Mercator</cite> projection (EPSG codes 9807).</div>
 </td>
 </tr>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="ZonedGridSystem.html" title="class in org.apache.sis.referencing.operation.projection">ZonedGridSystem</a></th>
 <td class="colLast">
 <div class="block"><cite>Transverse Mercator Zoned Grid System</cite> projection (EPSG codes 9824).</div>
 </td>
 </tr>
 </tbody>
 </table>
 </li>
 <li class="blockList">
 <table class="typeSummary">
 <caption><span>Enum Summary</span><span class="tabEnd">&nbsp;</span></caption>
 <tr>
 <th class="colFirst" scope="col">Enum</th>
 <th class="colLast" scope="col">Description</th>
 </tr>
 <tbody>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="NormalizedProjection.ParameterRole.html" title="enum in org.apache.sis.referencing.operation.projection">NormalizedProjection.ParameterRole</a></th>
 <td class="colLast">
 <div class="block">Maps the parameters to be used for initializing <a href="NormalizedProjection.html" title="class in org.apache.sis.referencing.operation.projection"><code>NormalizedProjection</code></a> and its
  <a href="../transform/ContextualParameters.html#getMatrix(org.apache.sis.referencing.operation.transform.ContextualParameters.MatrixRole)">normalization / denormalization</a> matrices.</div>
 </td>
 </tr>
 </tbody>
 </table>
 </li>
 <li class="blockList">
 <table class="typeSummary">
 <caption><span>Exception Summary</span><span class="tabEnd">&nbsp;</span></caption>
 <tr>
 <th class="colFirst" scope="col">Exception</th>
 <th class="colLast" scope="col">Description</th>
 </tr>
 <tbody>
 <tr class="altColor">
 <th class="colFirst" scope="row"><a href="ProjectionException.html" title="class in org.apache.sis.referencing.operation.projection">ProjectionException</a></th>
 <td class="colLast">
 <div class="block">Thrown by <a href="NormalizedProjection.html" title="class in org.apache.sis.referencing.operation.projection"><code>NormalizedProjection</code></a> when a map projection failed.</div>
 </td>
 </tr>
 </tbody>
 </table>
 </li>
 </ul>
 </div>
 </main>
 <footer role="contentinfo">
 <nav role="navigation">
 <!-- ======= START OF BOTTOM NAVBAR ====== -->
 <div class="bottomNav"><a id="navbar.bottom">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
 <a id="navbar.bottom.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../../../../index.html">Overview</a></li>
 <li class="navBarCell1Rev">Package</li>
 <li>Class</li>
 <li><a href="package-use.html">Use</a></li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../../../index-all.html">Index</a></li>
 <li><a href="../../../../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList" id="allclasses_navbar_bottom">
 <li><a href="../../../../../../allclasses.html">All&nbsp;Classes</a></li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_bottom");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 <noscript>
 <div>JavaScript is disabled on your browser.</div>
 </noscript>
 </div>
 <a id="skip.navbar.bottom">
 <!--   -->
 </a></div>
 <!-- ======== END OF BOTTOM NAVBAR ======= -->
 </nav>
 <p class="legalCopy"><small>Copyright &#169; 2010&#x2013;2019 <a href="https://www.apache.org/">The Apache Software Foundation</a>. All rights reserved.</small></p>
 </footer>
 </body>
 </html>