static/openoffice/formula.html

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE html>  <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en"> <head> <title>Formulas added to Calc by the add-in</title> <meta charset="UTF-8"/> <link rel="stylesheet" type="text/css" href="openoffice.css"/> </head> <body> <h1>Formulas added to Calc by the add-in</h1> <p> Apache <abbr title="Spatial Information System">SIS</abbr> add-in for Open/LibreOffice provides new functions in two categories: <i>Text</i> and <i>Add-in</i>. Most <i>Add-in</i> functions expect one or two Coordinate Reference Systems (<abbr>CRS</abbr>) identified by a code from the <a href="https://epsg.org/"><abbr>EPSG</abbr> geodetic dataset</a> or other authority. The <abbr>EPSG</abbr> geodetic dataset defines more then 6000 coordinate reference systems in use around the Earth, together with methods and parameters for performing coordinate operations from one system to another system. Some add-in functions fetch information about a given coordinate reference system, for example its domain of validity. Those functions expect a single <abbr>EPSG</abbr> code in argument. Some other functions work on a <em>coordinate operation</em> between two coordinate reference systems. Those functions expect two <abbr>EPSG</abbr> codes in arguments, each of them identifying a different reference system. The first code identifies the source reference system and the second code identifies the target reference system. The operation is defined by the algorithm transforming coordinates from the source system to the target system. </p><p> Authoritative definitions of <abbr>EPSG</abbr> codes can be browsed on-line on <a href="https://epsg.org/"><abbr>EPSG</abbr> repository</a>. This add-in for Open/LibreOffice contains a copy (in binary format) of <abbr>EPSG</abbr> database for convenience, but note that its use <a href="https://epsg.org/terms-of-use.html">is subject to conditions</a>. Apache <abbr>SIS</abbr> extends this list with a few codes defined outside <abbr>EPSG</abbr>, in particular codes defined by <abbr title="Open Geospatial Consortium">OGC</abbr>. A summary of codes embedded in Apache <abbr>SIS</abbr> is <a href="../tables/CoordinateReferenceSystems.html">available here</a>. Recognized code syntax <a href="../apidocs/org.apache.sis.referencing/org/apache/sis/referencing/CRS.html#forCode(java.lang.String)">is described in Apache <abbr>SIS</abbr> Javadoc</a>. For example, all following codes are considered equivalent to <code>"EPSG:4326"</code>: </p> <ul> <li><code>"EPSG::4326"</code></li> <li><code>"urn:ogc:def:crs:EPSG::4326"</code></li> <li><code>"http://www.opengis.net/def/crs/epsg/0/4326"</code></li> <li><code>"http://www.opengis.net/gml/srs/epsg.xml#4326"</code></li> </ul> <p> Most functions performing coordinate operations are matrix functions: their results require many columns, as many as the number of dimensions in the output coordinate reference system. For example if a function returns a three-dimensional coordinates, then users have to select three columns before to type the function and validate by pressing [Ctrl] + [Shift] + [Enter]. </p><p> While it is possible to enter one function per line and copy that line for each point to transform, such approach is inefficient. It is much more efficient to take advantage of matrix nature of above-cited functions: in addition to selecting as many columns as necessary, select also as many lines as there is points to transform. This approach allows Apache <abbr>SIS</abbr> to compute information related to <abbr>EPSG</abbr> codes only once for every lines in the output matrix, instead of repeating that operation for each copied lines. </p> <section> <h2 id="TEXT.ANGLE">TEXT.ANGLE</h2> <p> Converts a numerical value to a characters sequence representing an angle. The numerical value must be an angle in decimal degrees (for example 12.5 for 12°30′). The returned text may be a decimal or sexagesimal angle, depending on the pattern given in argument. This pattern contains some special characters <a href="../apidocs/org.apache.sis.util/org/apache/sis/measure/AngleFormat.html">described in Apache <abbr>SIS</abbr> Javadoc</a>. The main ones are: <var>D</var>, <var>M</var>, <var>S</var>, <var>d</var>, <var>m</var> and <var>s</var>. The <var>D</var> character represents the integer part of degrees and <var>d</var> the fractional part. The <var>M</var> character represents the integer part of minutes and <var>m</var> the fractional part. The <var>S</var> character represents the integer part of seconds and <var>s</var> the fractional part. </p> <table> <caption>Examples</caption> <tr><th>Formula</th> <th>Result</th></tr> <tr><td><code>=TEXT.ANGLE(167,1590; "DD°")</code></td> <td>167°</td></tr> <tr><td><code>=TEXT.ANGLE(167,1590; "DD°MM′")</code></td> <td>167°10′</td></tr> <tr><td><code>=TEXT.ANGLE(167,1590; "DD°MM′SS″")</code></td> <td>167°09′32″</td></tr> <tr><td><code>=TEXT.ANGLE(167,1590; "DD°MM′SS.s″")</code></td> <td>167°09′32,4″</td></tr> </table> </section> <section> <h2 id="VALUE.ANGLE">VALUE.ANGLE</h2> <p> Converts the text representation of a (potentially sexagesimal) angle to its numerical value. This function is the converse of <code><a href="#TEXT.ANGLE">TEXT.ANGLE</a></code>. The text may represent any sexagesimal angle provided that the °, ′ and ″ symbols are used as suffixes for degrees, minutes and seconds fields respectively. Hemisphere (<cite>N</cite>, <cite>S</cite>, <cite>E</cite> or <cite>W</cite>) is optional. The function result is always an angle in decimal degrees. </p><p> The °, ′ and ″ symbols are not strictly mandatory; they can be omitted if a pattern is given in argument. For example if the given pattern is <cite>DDMM</cite>, then this function will convert "0430" text into 4.5 numerical value. Except for such cases where the field separator symbols are completely absent, patterns given to this <code>VALUE.ANGLE</code> function are only indicative. This function is quite tolerant and should interpret correctly character sequences that do not comply fully with the given pattern. </p> </section> <section> <h2 id="CRS.NAME">CRS.NAME</h2> <p> Returns the name of the Coordinate Reference System identified by the given code. The reference system code is the only argument expected by this function. While this function is designed for operating on Coordinate Reference System (<abbr>CRS</abbr>) objects by default, it can also work with other kinds of objects provided that the type is explicitly specified (for example: <code>"urn:ogc:def:<b>datum</b>:EPSG::6326"</code>). </p> <table> <caption>Examples</caption> <tr><th>Formula</th> <th>Result</th></tr> <tr><td><code>=CRS.NAME("EPSG:3060")</code></td> <td>IGN72 Grande Terre / UTM zone 58S</td></tr> <tr><td><code>=CRS.NAME("EPSG:3061")</code></td> <td>Porto Santo 1995 / UTM zone 28N</td></tr> <tr><td><code>=CRS.NAME("EPSG:4326")</code></td> <td>WGS 84</td></tr> <tr><td><code>=CRS.NAME("EPSG:4329")</code></td> <td>WGS 84 (3D)</td></tr> </table> </section> <section> <h2><a id="CRS.USAGE">CRS.USAGE</a></h2> <p> Returns the scope of the Coordinate Reference System identified by the given code. The reference system code is the only argument expected by this function. While this function is designed for operating on Coordinate Reference System (<abbr>CRS</abbr>) objects by default, it can also work with other kinds of objects provided that the type is explicitly specified (for example: <code>"urn:ogc:def:<b>datum</b>:EPSG::6326"</code>). </p> <table> <caption>Examples</caption> <tr><th>Formula</th> <th>Result</th></tr> <tr><td><code>=CRS.USAGE("EPSG:3060")</code></td> <td>Large and medium scale topographic mapping and engineering survey.</td></tr> <tr><td><code>=CRS.USAGE("EPSG:4327")</code></td> <td>Used by GPS satellite navigation system.</td></tr> </table> </section> <section> <h2 id="REGION.NAME">REGION.NAME</h2> <p> Returns an object domain of validity as a textual description. This description usually contains country or province names where the reference system is valid. The given argument is often, but not necessarily, a Coordinate Reference System (<abbr>CRS</abbr>) code. </p> <table> <caption>Examples</caption> <tr><th>Formula</th> <th>Result</th></tr> <tr><td><code>=REGION.NAME("EPSG:3060")</code></td> <td>New Caledonia - Grande Terre.</td></tr> <tr><td><code>=REGION.NAME("EPSG:4326")</code></td> <td>World.</td></tr> </table> </section> <section> <h2 id="GEOGRAPHIC.AREA">GEOGRAPHIC.AREA</h2> <p> Returns an object domain of validity as a geographic bounding box. If the given code identifies a spatial reference system, then this function returns the geographic coordinates where the reference system is valid. The bounding box is represented by a 2×2 matrix with latitudes in the first column and longitudes in the second columns, always in this order and always in decimal degrees. The first line contains coordinates for upper-left corner and the second line contains coordinates for lower-right corner. In other words, values returned by this functions are distributed as below: </p> <table class="grid"> <tr><td>North</td> <td>West</td></tr> <tr><td>South</td> <td>East</td></tr> </table> </section> <section> <h2 id="CRS.AXIS">CRS.AXIS</h2> <p> Returns name and units of measurement for a single axis in a coordinate reference system. This function expects a Coordinate Reference System (<abbr>CRS</abbr>) code, followed by the index of a <abbr>CRS</abbr> dimension in arguments. Indices are numbered from 1 to the number of <abbr>CRS</abbr> dimensions, inclusive. This function is useful for fetching column labels in the header of a coordinates table. </p> <table> <caption>Examples</caption> <tr><th>Formula</th> <th>Result</th></tr> <tr><td><code>=CRS.AXIS("EPSG:4326"; 1)</code></td> <td>Latitude (°)</td></tr> <tr><td><code>=CRS.AXIS("EPSG:4326"; 2)</code></td> <td>Longitude (°)</td></tr> <tr><td><code>=CRS.AXIS("EPSG:32758"; 1)</code></td> <td>Easting (m)</td></tr> <tr><td><code>=CRS.AXIS("EPSG:32758"; 2)</code></td> <td>Northing (m)</td></tr> </table> </section> <section> <h2 id="TRANSFORM.POINTS">TRANSFORM.POINTS</h2> <p> Applies a coordinate operation (transformation or conversion) on a set of points. The coordinates to transform must be represented as a table with one point per line and a number of columns equal to the number of dimensions in their coordinate reference system (usually two or three columns). The result will be represented in the same way. This function expects three arguments: </p> <ul> <li>Code of the source coordinate reference system.</li> <li>Code of the target coordinate reference system.</li> <li>The coordinates to transform (a matrix).</li> </ul> <p> The order and number of columns for source coordinates depend on the source reference system. The order and number of columns for target coordinates (this function result) depend on the target reference system. It is helpful to use the <code><a href="#CRS.AXIS">CRS.AXIS</a></code> functions for showing the axis labels. </p><p> Note that different operations may have different accuracy. To obtain an estimation of a coordinate operations accuracy, one can use the <code><a href="#TRANSFORM.ACCURACY">TRANSFORM.ACCURACY</a></code> function with the same arguments than the ones specified to this <code>TRANSFORM.POINTS</code> function. </p> </section> <section> <h2 id="TRANSFORM.ENVELOPE">TRANSFORM.ENVELOPE</h2> <p> Applies an operation (transformation or conversion) on a bounding box. This function expects the same arguments than <code><a href="#TRANSFORM.POINTS">TRANSFORM.POINTS</a></code>, but returns only two lines. The first line will contain the minimal coordinate values while the second line will contain the maximal coordinate values. This result may be different than transforming all points first, then computing their minimal and maximal values. The reason for this difference is because <code>TRANSFORM.ENVELOPE</code> takes in account the bounding box curvature caused by some map projections or other operations. </p> </section> <section> <h2><a id="TRANSFORM.ACCURACY">TRANSFORM.ACCURACY</a></h2> <p> Returns an <strong>estimation</strong> of the accuracy of coordinate transformations between two coordinate reference systems. This function expects two reference system codes in argument. They are usually the codes specified to <code><a href="#TRANSFORM.POINTS">TRANSFORM.POINTS</a></code>. This function returns an error estimation for that coordinate operation, always in metres. This is not an error caused by limitation of floating point arithmetics, but rather an error caused by the stochastic nature of coordinate operations when datum shifts are involved (the parameter values for such operations are determined empirically from a set of points having coordinates measured in the two reference systems). Any software using the same parameters will have the same errors. </p><p> Uncertainties on coordinate operation results happen when there is a datum change, in which case the operation is a <cite>coordinate transformation</cite> in <abbr title="International Organization for Standardization">ISO</abbr> 19111 terminology. But when the operation is for example a map projection without datum change, then the operation is a <cite>coordinate conversion</cite> in <abbr>ISO</abbr> terminology. In this case, <code>TRANSFORM.ACCURACY</code> may return 0, which means that infinitely accurate answers exist in theory. In practice, Apache <abbr>SIS</abbr> is limited by floating point accuracy and numerical approximations of some non-linear formulas. Consequently the error is <em>not really</em> null, but should be small. </p> </section> </body> </html>

static/openoffice/formula.html (239 lines of code) (raw):