pgLatLon
changeset 82:8a08dc69de98
Use cmark instead of markdown2 in make-doc.sh
| author | jbe |
|---|---|
| date | Thu Oct 23 15:19:13 2025 +0200 (2 days ago) |
| parents | b0e17a5a0258 |
| children | 037e28f426e7 |
| files | README.html make-doc.sh |
line diff
1.1 --- a/README.html Thu Oct 23 15:15:56 2025 +0200 1.2 +++ b/README.html Thu Oct 23 15:19:13 2025 +0200 1.3 @@ -1,125 +1,92 @@ 1.4 <html><head><title>pgLatLon v0.15 documentation</title></head><body> 1.5 <h1>pgLatLon v0.15 documentation</h1> 1.6 - 1.7 <p>pgLatLon is a spatial database extension for the PostgreSQL object-relational 1.8 database management system providing geographic data types and spatial indexing 1.9 for the WGS-84 spheroid.</p> 1.10 - 1.11 <p>While many other spatial databases still use imprecise bounding boxes for 1.12 many operations, pgLatLon aims to support more precise calculations for all 1.13 implemented geographic operators. Efficient indexing of geographic objects 1.14 is provided using space-filling fractal curves. Optimizations on bit level 1.15 (including logarithmic compression) allow for a highly memory-efficient 1.16 non-overlapping index suitable for huge datasets.</p> 1.17 - 1.18 <p>pgLatLon is a lightweight solution as it only depends on PostgreSQL itself (and 1.19 a C compiler for building).</p> 1.20 - 1.21 <p>Unlike competing spatial extensions for PostgreSQL, pgLatLon is available under 1.22 the permissive MIT/X11 license to avoid problems with viral licenses like the 1.23 GPLv2/v3.</p> 1.24 - 1.25 <h2>Installation</h2> 1.26 - 1.27 <h3>Automatic installation</h3> 1.28 - 1.29 <p>Prerequisites:</p> 1.30 - 1.31 <ul> 1.32 <li>Ensure that the <code>pg_config</code> binary is in your path (shipped with PostgreSQL).</li> 1.33 <li>Ensure that GNU Make is available (either as <code>make</code> or <code>gmake</code>).</li> 1.34 </ul> 1.35 - 1.36 <p>Then simply type:</p> 1.37 - 1.38 <pre><code>make install 1.39 </code></pre> 1.40 - 1.41 <h3>Manual installation</h3> 1.42 - 1.43 <p>It is also possible to compile and install the extension without GNU Make as 1.44 follows:</p> 1.45 - 1.46 <pre><code>cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0010.so latlon-v0010.c 1.47 cp latlon-v0010.so `pg_config --pkglibdir` 1.48 cp latlon.control `pg_config --sharedir`/extension/ 1.49 cp latlon--*.sql `pg_config --sharedir`/extension/ 1.50 </code></pre> 1.51 - 1.52 <h3>Loading the extension</h3> 1.53 - 1.54 <p>After installation, you can create a database and load the extension as 1.55 follows:</p> 1.56 - 1.57 <pre><code>% createdb test_database 1.58 % psql test_database 1.59 psql (9.5.4) 1.60 -Type "help" for help. 1.61 +Type "help" for help. 1.62 1.63 test_database=# CREATE EXTENSION latlon; 1.64 </code></pre> 1.65 - 1.66 <h3>Updating</h3> 1.67 - 1.68 <p>Before updating your database cluster to a new version of pgLatLon, you may 1.69 -want to uninstall the old by calling "<code>make uninstall</code>" in the unpacked source 1.70 +want to uninstall the old by calling "<code>make uninstall</code>" in the unpacked source 1.71 code directory of your old pgLatLon version. You may also manually delete the 1.72 <code>latlon-v????.so</code> files from your PostgreSQL library directory and the 1.73 <code>latlon.control</code> and <code>latlon--*.sql</code> files from your PostgreSQL extension 1.74 directory.</p> 1.75 - 1.76 <p>The new version can be installed as described above. For altering an existing 1.77 database to use the installed new version (mandatory if you removed the old 1.78 version), execute the following SQL command in the respective databases:</p> 1.79 - 1.80 <pre><code>ALTER EXTENSION latlon UPDATE; 1.81 </code></pre> 1.82 - 1.83 <p>If the update contains modifications to operator classes, it may be necessary 1.84 to drop all indices on geographic data types first (you will get an error 1.85 message in this case). These indices can be re-created after the update.</p> 1.86 - 1.87 <p>Note that taking several update steps at once (e.g. updating from version 0.2 1.88 directly to version 0.4) requires the intermediate versions to be installed 1.89 (i.e. in this example version 0.3 would need to be installed). Whenever you 1.90 install or uninstall an intermediate or old version, make sure to afterwards 1.91 re-install the latest pgLatLon version to ensure that the <code>latlon.control</code> file 1.92 is available and points to the latest version.</p> 1.93 - 1.94 <p>If the update contains modifications to the internal data representation 1.95 format, an update path might not be available. In this case, create a dump of 1.96 your database, delete your database, and restore it from your dump.</p> 1.97 - 1.98 <p>Be sure to always keep backups of all your data before attempting to update.</p> 1.99 - 1.100 <h2>Reference</h2> 1.101 - 1.102 <h3>1. Types</h3> 1.103 - 1.104 <p>pgLatLon provides four geographic types: <code>epoint</code>, <code>ebox</code>, <code>ecircle</code>, and 1.105 <code>ecluster</code>.</p> 1.106 - 1.107 <h4><code>epoint</code></h4> 1.108 - 1.109 <p>A point on the Earth spheroid (WGS-84).</p> 1.110 - 1.111 <p>The text input format is <code>'[N|S]<float> [E|W]<float>'</code>, where each float is in 1.112 degrees. Note the required white space between the latitude and longitude 1.113 components. Each floating point number may have a sign, in which case <code>N</code>/<code>S</code> 1.114 or <code>E</code>/<code>W</code> are switched respectively (e.g. <code>E-5</code> is the same as <code>W5</code>).</p> 1.115 - 1.116 <p>An <code>epoint</code> may also be created from two floating point numbers by calling 1.117 <code>epoint(latitude, longitude)</code>, where positive latitudes are used for the 1.118 northern hemisphere, negative latitudes are used for the southern hemisphere, 1.119 positive longitudes indicate positions east of the prime meridian, and negative 1.120 longitudes indicate positions west of the prime meridian.</p> 1.121 - 1.122 <p>Latitudes exceeding -90 or +90 degrees are truncated to -90 or +90 1.123 respectively, in which case a warning will be issued. Longitudes exceeding -180 1.124 or +180 degrees will be converted to values between -180 and +180 (both 1.125 inclusive) by adding or substracting a multiple of 360 degrees, in which case a 1.126 notice will be issued.</p> 1.127 - 1.128 <p>If the latitude is -90 or +90 (south pole or north pole), a longitude value is 1.129 still stored in the datum, and if a point is on the prime meridian or the 1.130 180th meridian, the east/west bit is also stored in the datum. In case of the 1.131 @@ -129,21 +96,16 @@ 1.132 operator, however, returns true when the same points on Earth are described, 1.133 i.e. the longitude is ignored for the poles, and 180 degrees west is considered 1.134 to be equal to 180 degrees east.</p> 1.135 - 1.136 <h4><code>ebox</code></h4> 1.137 - 1.138 <p>An area on Earth demarcated by a southern and northern latitude, and a western 1.139 and eastern longitude (all given in WGS-84).</p> 1.140 - 1.141 <p>The text input format is 1.142 <code>'{N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float>'</code>, where each float is in 1.143 degrees. The ordering of the four white-space separated blocks is not 1.144 significant. To include the 180th meridian, one longitude boundary must be 1.145 equal to or exceed <code>W180</code> or <code>E180</code>, e.g. <code>'N10 N20 E170 E190'</code>.</p> 1.146 - 1.147 <p>A special value is the empty area, denoted by the text represenation <code>'empty'</code>. 1.148 Such an <code>ebox</code> does not contain any point.</p> 1.149 - 1.150 <p>An <code>ebox</code> may also be created from four floating point numbers by calling 1.151 <code>ebox(min_latitude, max_latitude, min_longitude, max_longitude)</code>, where 1.152 positive values are used for north and east, and negative values are used for 1.153 @@ -151,128 +113,90 @@ 1.154 empty <code>ebox</code> is created. If <code>min_longitude</code> is greater than <code>max_longitude</code> and 1.155 if both longitudes are between -180 and +180 degrees, then the area oriented in 1.156 such way that the 180th meridian is included.</p> 1.157 - 1.158 <p>If the longitude span is less than 120 degrees, an <code>ebox</code> may be alternatively 1.159 -created from two <code>epoints</code> in the following way: <code>ebox(epoint(lat1, lon1), 1.160 -epoint(lat2, lon2))</code>. In this case <code>lat1</code> and <code>lat2</code> as well as <code>lon1</code> and 1.161 +created from two <code>epoints</code> in the following way: <code>ebox(epoint(lat1, lon1), epoint(lat2, lon2))</code>. In this case <code>lat1</code> and <code>lat2</code> as well as <code>lon1</code> and 1.162 <code>lon2</code> can be swapped without any impact.</p> 1.163 - 1.164 <h4><code>ecircle</code></h4> 1.165 - 1.166 <p>An area containing all points not farther away from a given center point 1.167 (WGS-84) than a given radius.</p> 1.168 - 1.169 <p>The text input format is <code>'{N|S}<float> {E|W}<float> <float>'</code>, where the first 1.170 two floats denote the center point in degrees and the third float denotes the 1.171 radius in meters. A radius equal to minus infinity denotes an empty circle 1.172 which contains no point at all (despite having a center), while a radius equal 1.173 to zero denotes a circle that includes a single point.</p> 1.174 - 1.175 <p>An <code>ecircle</code> may also be created by calling <code>ecircle(epoint(...), radius)</code> or 1.176 -from three floating point numbers by calling <code>ecircle(latitude, longitude, 1.177 -radius)</code>.</p> 1.178 - 1.179 +from three floating point numbers by calling <code>ecircle(latitude, longitude, radius)</code>.</p> 1.180 <h4><code>ecluster</code></h4> 1.181 - 1.182 <p>A collection of points, paths, polygons, and outlines on the WGS-84 spheroid. 1.183 Each path, polygon, or outline must cover a longitude range of less than 1.184 180 degrees to avoid ambiguities.</p> 1.185 - 1.186 <p>The text input format is a white-space separated list of the following items:</p> 1.187 - 1.188 <ul> 1.189 <li><code>point ({N|S}<float> {E|W}<float>)</code></li> 1.190 <li><code>path ({N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> ...)</code></li> 1.191 <li><code>outline ({N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> ...)</code></li> 1.192 <li><code>polygon ({N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> ...)</code></li> 1.193 </ul> 1.194 - 1.195 <p>Paths are open by default (i.e. there is no connection from the last point in 1.196 the list to the first point in the list). Outlines and polygons, in contrast, 1.197 are automatically closed (i.e. there is a line segment from the last point in 1.198 the list to the first point in the list) which means the first point should not 1.199 be repeated as last point in the list. Polygons are filled, outlines are not.</p> 1.200 - 1.201 <h3>2. Indices</h3> 1.202 - 1.203 <p>Two kinds of indices are supported: B-tree and GiST indices.</p> 1.204 - 1.205 <h4>B-tree indices</h4> 1.206 - 1.207 <p>A B-tree index can be used for simple equality searches and is supported by the 1.208 <code>epoint</code>, <code>ebox</code>, and <code>ecircle</code> data types. B-tree indices can not be used for 1.209 geographic searches.</p> 1.210 - 1.211 <h4>GiST indices</h4> 1.212 - 1.213 <p>For geographic searches, GiST indices must be used. The <code>epoint</code>, <code>ecircle</code>, 1.214 and <code>ecluster</code> data types support GiST indexing. A GiST index for geographic 1.215 searches can be created as follows:</p> 1.216 - 1.217 <pre><code>CREATE TABLE tbl ( 1.218 id serial4 PRIMARY KEY, 1.219 loc epoint NOT NULL ); 1.220 1.221 CREATE INDEX name_of_index ON tbl USING gist (loc); 1.222 </code></pre> 1.223 - 1.224 <p>GiST indices also support nearest neighbor searches when using the distance 1.225 operator (<code><-></code>) in the ORDER BY clause.</p> 1.226 - 1.227 <h4>Indices on other data types (e.g. GeoJSON)</h4> 1.228 - 1.229 <p>Note that further types can be indexed by using an index on an expression with 1.230 a conversion function. One conversion function provided by pgLatLon is the 1.231 <code>GeoJSON_to_ecluster(jsonb, text)</code> function:</p> 1.232 - 1.233 <pre><code>CREATE TABLE tbl ( 1.234 id serial4 PRIMARY KEY, 1.235 loc jsonb NOT NULL ); 1.236 1.237 -CREATE INDEX name_of_index ON tbl USING gist ((GeoJSON_to_ecluster("loc"))); 1.238 +CREATE INDEX name_of_index ON tbl USING gist ((GeoJSON_to_ecluster("loc"))); 1.239 </code></pre> 1.240 - 1.241 <p>When using the conversion function in an expression, the index will be used 1.242 automatically:</p> 1.243 - 1.244 -<pre><code>SELECT * FROM tbl WHERE GeoJSON_to_ecluster("loc") && 'N50 E10 10000'::ecircle; 1.245 +<pre><code>SELECT * FROM tbl WHERE GeoJSON_to_ecluster("loc") && 'N50 E10 10000'::ecircle; 1.246 </code></pre> 1.247 - 1.248 <h3>3. Operators</h3> 1.249 - 1.250 <h4>Equality operator <code>=</code></h4> 1.251 - 1.252 <p>Tests if two geographic objects are equal.</p> 1.253 - 1.254 <p>The longitude is ignored for the poles, and 180 degrees west is considered to 1.255 be equal to 180 degrees east.</p> 1.256 - 1.257 <p>For boxes and circles, two empty objects are considered equal. (Note that a 1.258 circle is not empty if the radius is zero but only if it is negative infinity, 1.259 i.e. smaller than zero.) Two circles with a positive infinite radius are also 1.260 considered equal.</p> 1.261 - 1.262 <p>Implemented for:</p> 1.263 - 1.264 <ul> 1.265 <li><code>epoint = epoint</code></li> 1.266 <li><code>ebox = ebox</code></li> 1.267 <li><code>ecircle = ecircle</code></li> 1.268 </ul> 1.269 - 1.270 <p>The negation is the inequality operator (<code><></code> or <code>!=</code>).</p> 1.271 - 1.272 <h4>Linear ordering operators <code><<<</code>, <code><<<=</code>, <code>>>>=</code>, <code>>>></code></h4> 1.273 - 1.274 <p>These operators create an arbitrary (but well-defined) linear ordering of 1.275 geographic objects, which is used internally for B-tree indexing and merge 1.276 joins. These operators will usually not be used by an application programmer.</p> 1.277 - 1.278 <h4>Overlap operator <code>&&</code></h4> 1.279 - 1.280 <p>Tests if two geographic objects have at least one point in common. Currently 1.281 implemented for:</p> 1.282 - 1.283 <ul> 1.284 <li><code>epoint && ebox</code></li> 1.285 <li><code>epoint && ecircle</code></li> 1.286 @@ -284,16 +208,12 @@ 1.287 <li><code>ecircle && ecluster</code></li> 1.288 <li><code>ecluster && ecluster</code></li> 1.289 </ul> 1.290 - 1.291 -<p>The <code>&&</code> operator is commutative, i.e. "<code>a && b</code>" is the same as "<code>b && a</code>". 1.292 +<p>The <code>&&</code> operator is commutative, i.e. "<code>a && b</code>" is the same as "<code>b && a</code>". 1.293 Each commutation is supported as well.</p> 1.294 - 1.295 <h4>Lossy overlap operator <code>&&+</code></h4> 1.296 - 1.297 <p>Tests if two geographic objects may have at least one point in common. Opposed 1.298 to the <code>&&</code> operator, the <code>&&+</code> operator may return false positives and is 1.299 currently implemented for:</p> 1.300 - 1.301 <ul> 1.302 <li><code>epoint &&+ ecluster</code></li> 1.303 <li><code>ebox &&+ ecircle</code></li> 1.304 @@ -301,18 +221,13 @@ 1.305 <li><code>ecircle &&+ ecluster</code></li> 1.306 <li><code>ecluster &&+ ecluster</code></li> 1.307 </ul> 1.308 - 1.309 -<p>The <code>&&+</code> operator is commutative, i.e. "<code>a &&+ b</code>" is the same as "<code>b &&+ a</code>". 1.310 +<p>The <code>&&+</code> operator is commutative, i.e. "<code>a &&+ b</code>" is the same as "<code>b &&+ a</code>". 1.311 Each commutation is supported as well.</p> 1.312 - 1.313 <p>Where two data types support both the <code>&&</code> and the <code>&&+</code> operator, the <code>&&+</code> 1.314 operator computes faster.</p> 1.315 - 1.316 <h4>Contains operator <code>@></code></h4> 1.317 - 1.318 <p>Tests if the object right of the operator is contained in the object left of 1.319 the operator. Currently implemented for:</p> 1.320 - 1.321 <ul> 1.322 <li><code>ebox @> epoint</code> (alias for <code>&&</code>)</li> 1.323 <li><code>ebox @> ebox</code></li> 1.324 @@ -321,21 +236,16 @@ 1.325 <li><code>ecluster @> ebox</code></li> 1.326 <li><code>ecluster @> ecluster</code></li> 1.327 </ul> 1.328 - 1.329 -<p>The commutator of <code>@></code> ("contains") is <code><@</code> ("is contained in"), i.e. 1.330 -"<code>a @> b</code>" is the same as "<code>b <@ a</code>".</p> 1.331 - 1.332 +<p>The commutator of <code>@></code> ("contains") is <code><@</code> ("is contained in"), i.e. 1.333 +"<code>a @> b</code>" is the same as "<code>b <@ a</code>".</p> 1.334 <p>Whether the perimeter of an object is taken into account is undefined and may 1.335 differ between the left and the right hand side of the operator. The current 1.336 implementation (where not an alias for <code>&&</code>) returns true only if an object is 1.337 contained completely within the other object, not touching its perimeter, 1.338 paths, outlines, or any singular points.</p> 1.339 - 1.340 <h4>Distance operator <code><-></code></h4> 1.341 - 1.342 <p>Calculates the shortest distance between two geographic objects in meters (zero 1.343 if the objects are overlapping). Currently implemented for:</p> 1.344 - 1.345 <ul> 1.346 <li><code>epoint <-> epoint</code></li> 1.347 <li><code>epoint <-> ebox</code></li> 1.348 @@ -348,159 +258,99 @@ 1.349 <li><code>ecircle <-> ecluster</code></li> 1.350 <li><code>ecluster <-> ecluster</code></li> 1.351 </ul> 1.352 - 1.353 -<p>The <code><-></code> operator is commutative, i.e. "<code>a <-> b</code>" is the same as "<code>b <-> a</code>". 1.354 +<p>The <code><-></code> operator is commutative, i.e. "<code>a <-> b</code>" is the same as "<code>b <-> a</code>". 1.355 Each commutation is supported as well.</p> 1.356 - 1.357 <p>For short distances, the result is very accurate (i.e. respects the dimensions 1.358 of the WGS-84 spheroid). For longer distances in the order of magnitude of 1.359 Earth's radius or greater, the value is only approximate (but the error is 1.360 still less than 0.2% as long as no polygons with very long edges are involved).</p> 1.361 - 1.362 <p>The functions <code>distance(epoint, epoint)</code> and <code>distance(ecluster, epoint)</code> can 1.363 be used as an alias for this operator.</p> 1.364 - 1.365 <p>Note: In case of radial searches with a fixed radius, this operator should 1.366 not be used. Instead, an <code>ecircle</code> should be created and used in combination 1.367 with the overlap operator (<code>&&</code>). Alternatively, the functions 1.368 -<code>distance_within(epoint, epoint, float8)</code> or <code>distance_within(ecluster, epoint, 1.369 -float8)</code> can be used for fixed-radius searches.</p> 1.370 - 1.371 +<code>distance_within(epoint, epoint, float8)</code> or <code>distance_within(ecluster, epoint, float8)</code> can be used for fixed-radius searches.</p> 1.372 <h3>4. Functions</h3> 1.373 - 1.374 <h4><code>center(circle)</code></h4> 1.375 - 1.376 <p>Returns the center of an <code>ecircle</code> as an <code>epoint</code>.</p> 1.377 - 1.378 <h4><code>distance(epoint, epoint)</code></h4> 1.379 - 1.380 <p>Calculates the distance between two <code>epoint</code> datums in meters. This function is 1.381 an alias for the distance operator <code><-></code>.</p> 1.382 - 1.383 <p>Note: In case of radial searches with a fixed radius, this function should not be 1.384 used. Use <code>distance_within(epoint, epoint, float8)</code> instead.</p> 1.385 - 1.386 <h4><code>distance(ecluster, epoint)</code></h4> 1.387 - 1.388 <p>Calculates the distance from an <code>ecluster</code> to an <code>epoint</code> in meters. This 1.389 function is an alias for the distance operator <code><-></code>.</p> 1.390 - 1.391 <p>Note: In case of radial searches with a fixed radius, this function should not be 1.392 used. Use <code>distance_within(epoint, epoint, float8)</code> instead.</p> 1.393 - 1.394 <h4><code>distance_within(</code>variable <code>epoint,</code> fixed <code>epoint,</code> radius <code>float8)</code></h4> 1.395 - 1.396 <p>Checks if the distance between two <code>epoint</code> datums is not greater than a given 1.397 value (search radius).</p> 1.398 - 1.399 <p>Note: In case of radial searches with a fixed radius, the first argument must 1.400 be used for the table column, while the second argument must be used for the 1.401 search center. Otherwise an existing index cannot be used.</p> 1.402 - 1.403 <h4><code>distance_within(</code>variable <code>ecluster,</code> fixed <code>epoint,</code> radius <code>float8)</code></h4> 1.404 - 1.405 <p>Checks if the distance from an <code>ecluster</code> to an <code>epoint</code> is not greater than a 1.406 given value (search radius).</p> 1.407 - 1.408 <h4><code>ebox(</code>latmin <code>float8,</code> latmax <code>float8,</code> lonmin <code>float8,</code> lonmax <code>float8)</code></h4> 1.409 - 1.410 <p>Creates a new <code>ebox</code> with the given boundaries. 1.411 -See "1. Types", subsection <code>ebox</code> for details.</p> 1.412 - 1.413 +See "1. Types", subsection <code>ebox</code> for details.</p> 1.414 <h4><code>ebox(epoint, epoint)</code></h4> 1.415 - 1.416 <p>Creates a new <code>ebox</code>. This function may only be used if the longitude 1.417 difference is less than or equal to 120 degrees. 1.418 -See "1. Types", subsection <code>ebox</code> for details.</p> 1.419 - 1.420 +See "1. Types", subsection <code>ebox</code> for details.</p> 1.421 <h4><code>ecircle(epoint, float8)</code></h4> 1.422 - 1.423 <p>Creates an <code>ecircle</code> with the given center point and radius.</p> 1.424 - 1.425 <h4><code>ecircle(</code>latitude <code>float8,</code> longitude <code>float8,</code> radius <code>float8)</code></h4> 1.426 - 1.427 <p>Creates an <code>ecircle</code> with the given center point and radius.</p> 1.428 - 1.429 <h4><code>ecluster_concat(ecluster, ecluster)</code></h4> 1.430 - 1.431 <p>Combines two clusters to form a new <code>ecluster</code> by uniting all entries of both 1.432 clusters. Note that two overlapping areas of polygons annihilate each other 1.433 (which may be used to create polygons with holes).</p> 1.434 - 1.435 <h4><code>ecluster_concat(ecluster[])</code></h4> 1.436 - 1.437 <p>Creates a new <code>ecluster</code> that unites all entries of all clusters in the passed 1.438 array. Note that two overlapping areas of polygons annihilate each other (which 1.439 may be used to create polygons with holes).</p> 1.440 - 1.441 <h4><code>ecluster_create_multipoint(epoint[])</code></h4> 1.442 - 1.443 <p>Creates a new <code>ecluster</code> which contains multiple points.</p> 1.444 - 1.445 <h4><code>ecluster_create_outline(epoint[])</code></h4> 1.446 - 1.447 <p>Creates a new <code>ecluster</code> that is an outline given by the passed points.</p> 1.448 - 1.449 <h4><code>ecluster_create_path(epoint[])</code></h4> 1.450 - 1.451 <p>Creates a new <code>ecluster</code> that is a path given by the passed points.</p> 1.452 - 1.453 <h4><code>ecluster_create_polygon(epoint[])</code></h4> 1.454 - 1.455 <p>Creates a new <code>ecluster</code> that is a polygon given by the passed points.</p> 1.456 - 1.457 <h4><code>ecluster_extract_outlines(ecluster)</code></h4> 1.458 - 1.459 <p>Set-returning function that returns the outlines of an <code>ecluster</code> as <code>epoint[]</code> 1.460 rows.</p> 1.461 - 1.462 <h4><code>ecluster_extract_paths(ecluster)</code></h4> 1.463 - 1.464 <p>Set-returning function that returns the paths of an <code>ecluster</code> as <code>epoint[]</code> 1.465 rows.</p> 1.466 - 1.467 <h4><code>ecluster_extract_points(ecluster)</code></h4> 1.468 - 1.469 <p>Set-returning function that returns the points of an <code>ecluster</code> as <code>epoint</code> 1.470 rows.</p> 1.471 - 1.472 <h4><code>ecluster_extract_polygons(ecluster)</code></h4> 1.473 - 1.474 <p>Set-returning function that returns the polygons of an <code>ecluster</code> as <code>epoint[]</code> 1.475 rows.</p> 1.476 - 1.477 <h4><code>empty_ebox</code>()</h4> 1.478 - 1.479 <p>Returns the empty <code>ebox</code>. 1.480 -See "1. Types", subsection <code>ebox</code> for details.</p> 1.481 - 1.482 +See "1. Types", subsection <code>ebox</code> for details.</p> 1.483 <h4><code>epoint(</code>latitude <code>float8,</code> longitude <code>float8)</code></h4> 1.484 - 1.485 <p>Returns an <code>epoint</code> with the given latitude and longitude.</p> 1.486 - 1.487 <h4><code>epoint_latlon(</code>latitude <code>float8,</code> longitude <code>float8)</code></h4> 1.488 - 1.489 <p>Alias for <code>epoint(float8, float8)</code>.</p> 1.490 - 1.491 <h4><code>epoint_lonlat(</code>longitude <code>float8,</code> latitude <code>float8)</code></h4> 1.492 - 1.493 <p>Same as <code>epoint(float8, float8)</code> but with arguments reversed.</p> 1.494 - 1.495 <h4><code>fair_distance(ecluster, epoint,</code> samples <code>int4 = 10000)</code></h4> 1.496 - 1.497 <p>When working with user-generated content, users may be tempted to create 1.498 intentionally oversized objects in order to optimize search results in an 1.499 unfair manner. The <code>fair_distance</code> function aims to handle this by returning an 1.500 adjusted distance (i.e. distance increased by a penalty) if a geographic object 1.501 (the <code>ecluster</code>) consists of more than one point.</p> 1.502 - 1.503 <p>The first argument to this function is an <code>ecluster</code>, the second argument is a 1.504 search point (<code>epoint</code>), and the third argument is an interger related to the 1.505 precision (higher precision will require more computation time).</p> 1.506 - 1.507 <p>The penalty by which the returned distance is increased fulfills (at least) the 1.508 following properties:</p> 1.509 - 1.510 <ul> 1.511 <li>The penalty function is continuous (except noise created by numerical 1.512 integration, see paragraph after this list) as long as no objects are added 1.513 @@ -524,66 +374,44 @@ 1.514 <code>ecluster</code> as long as the <code>ecluster</code> does not cover more than a half of 1.515 earth's surface.</li> 1.516 </ul> 1.517 - 1.518 <p>The function uses numerical integration to compute the result. The third 1.519 parameter (which defaults to 10000) can be used to adjust the number of samples 1.520 taken. A higher sample count increases precision as well as execution time of 1.521 the function. Because this function internally uses a spherical model of earth 1.522 for certain steps of the calculation, the precision cannot be increased 1.523 unboundedly.</p> 1.524 - 1.525 <p>Despite the limitations explained above, it is ensured that the penalty is 1.526 always positive, i.e. results returned by the <code>fair_distance</code> function are 1.527 always equal to or greater than the results returned by the <code>distance</code> 1.528 function regardless of stochastic effects. Furthermore, all results are 1.529 deterministic and reproducible with the same version of pgLatLon.</p> 1.530 - 1.531 <h4><code>GeoJSON_to_epoint(jsonb, text)</code></h4> 1.532 - 1.533 -<p>Maps a GeoJSON object of type "Point" or "Feature" (which contains a 1.534 -"Point") to an <code>epoint</code> datum. For any other JSON objects, NULL is returned.</p> 1.535 - 1.536 +<p>Maps a GeoJSON object of type "Point" or "Feature" (which contains a 1.537 +"Point") to an <code>epoint</code> datum. For any other JSON objects, NULL is returned.</p> 1.538 <p>The second parameter (which defaults to <code>epoint_lonlat</code>) may be set to a name 1.539 of a conversion function that transforms two coordinates (two <code>float8</code> 1.540 parameters) to an <code>epoint</code>.</p> 1.541 - 1.542 <h4><code>GeoJSON_to_ecluster(jsonb, text)</code></h4> 1.543 - 1.544 <p>Maps a (valid) GeoJSON object to an <code>ecluster</code>. Note that this function 1.545 does not check whether the JSONB object is a valid GeoJSON object.</p> 1.546 - 1.547 <p>The second parameter (which defaults to <code>epoint_lonlat</code>) may be set to a name 1.548 of a conversion function that transforms two coordinates (two <code>float8</code> 1.549 parameters) to an <code>epoint</code>.</p> 1.550 - 1.551 <h4><code>max_latitude(ebox)</code></h4> 1.552 - 1.553 <p>Returns the northern boundary of a given <code>ebox</code> in degrees between -90 and +90.</p> 1.554 - 1.555 <h4><code>max_longitude(ebox)</code></h4> 1.556 - 1.557 <p>Returns the eastern boundary of a given <code>ebox</code> in degrees between -180 and +180 1.558 (both inclusive).</p> 1.559 - 1.560 <h4><code>min_latitude(ebox)</code></h4> 1.561 - 1.562 <p>Returns the southern boundary of a given <code>ebox</code> in degrees between -90 and +90.</p> 1.563 - 1.564 <h4><code>min_longitude(ebox)</code></h4> 1.565 - 1.566 <p>Returns the western boundary of a given <code>ebox</code> in degrees between -180 and +180 1.567 (both inclusive).</p> 1.568 - 1.569 <h4><code>latitude(epoint)</code></h4> 1.570 - 1.571 <p>Returns the latitude value of an <code>epoint</code> in degrees between -90 and +90.</p> 1.572 - 1.573 <h4><code>longitude(epoint)</code></h4> 1.574 - 1.575 <p>Returns the longitude value of an <code>epoint</code> in degrees between -180 and +180 1.576 (both inclusive).</p> 1.577 - 1.578 <h4><code>radius(ecircle)</code></h4> 1.579 - 1.580 <p>Returns the radius of an <code>ecircle</code> in meters.</p> 1.581 </body></html>
2.1 --- a/make-doc.sh Thu Oct 23 15:15:56 2025 +0200 2.2 +++ b/make-doc.sh Thu Oct 23 15:19:13 2025 +0200 2.3 @@ -4,5 +4,5 @@ 2.4 # README.md file. 2.5 2.6 echo "<html><head><title>"`grep '[^ \t\r\n][^ \t\r\n]*' README.md | head -n 1`"</title></head><body>" > README.html 2.7 -markdown2 README.md >> README.html 2.8 +cmark README.md >> README.html 2.9 echo "</body></html>" >> README.html