source: project/wiki/eggref/5/geo-utils @ 36191

Last change on this file since 36191 was 36191, checked in by Kon Lovett, 14 months ago

rel 1.0.0

File size: 10.3 KB
Line 
1[[tags: egg]]
2
3== geo-utils
4
5Geographic Utilities
6
7[[toc:]]
8
9
10== Documentation
11
12API for constructing and manipulating geographic data.
13
14
15=== Module geopoint
16
17==== Usage
18
19<enscript language=scheme>
20(import geopoint)
21</enscript>
22
23==== Argument Conventions
24
25; {{GP}} : {{geopoint}}.
26; {{LAT}} : latitude {{real}}.
27; {{LON}} : longitude {{real}}.
28
29==== make-geopoint
30
31<procedure>(make-geopoint LAT LON) => geopoint</procedure>
32
33==== geopoint?
34
35<procedure>(geopoint? OBJ) => boolean</procedure>
36
37==== check-geopoint
38
39<procedure>(check-geopoint LOC OBJ [VARNAM]) => geopoint</procedure>
40
41==== error-geopoint
42
43<procedure>(error-geopoint LOC OBJ [VARNAM])</procedure>
44
45==== geopoint-latitude
46
47<procedure>(geopoint-latitude GP) => real</procedure>
48
49==== geopoint-longitude
50
51<procedure>(geopoint-longitude GP) => real</procedure>
52
53==== geopoint-strictly-above?
54
55<procedure>(geopoint-strictly-above? GP1 GP2) => boolean</procedure>
56
57==== geopoint-above?
58
59<procedure>(geopoint-above? GP1 GP2) => boolean</procedure>
60
61==== geopoint-strictly-below?
62
63<procedure>(geopoint-strictly-below? GP1 GP2) => boolean</procedure>
64
65==== geopoint-below?
66
67<procedure>(geopoint-below? GP1 GP2) => boolean</procedure>
68
69==== geopoint-strictly-left?
70
71<procedure>(geopoint-strictly-left? GP1 GP2) => boolean</procedure>
72
73==== geopoint-left?
74
75<procedure>(geopoint-left? GP1 GP2) => boolean</procedure>
76
77==== geopoint-strictly-right?
78
79<procedure>(geopoint-strictly-right? GP1 GP2) => boolean</procedure>
80
81==== geopoint-right?
82
83<procedure>(geopoint-right? GP1 GP2) => boolean</procedure>
84
85==== geopoint=
86
87<procedure>(geopoint= GP1 GP2) => boolean</procedure>
88
89==== geopoint<
90
91<procedure>(geopoint< GP1 GP2) => boolean</procedure>
92
93==== geopoint>
94
95<procedure>(geopoint> GP1 GP2) => boolean</procedure>
96
97==== geopoint<=
98
99<procedure>(geopoint<= GP1 GP2) => boolean</procedure>
100
101==== geopoint>=
102
103<procedure>(geopoint>= GP1 GP2) => boolean</procedure>
104
105
106=== Module geobox
107
108==== Usage
109
110<enscript language=scheme>
111(import geobox)
112</enscript>
113
114==== Argument Conventions
115
116; {{GB}} : {{geobox}}.
117
118==== make-geobox
119
120<procedure>(make-geobox GP-MIN GP-MAX) => geobox</procedure>
121
122==== geobox?
123
124<procedure>(geobox? OBJ) => boolean</procedure>
125
126==== check-geobox
127
128<procedure>(check-geobox LOC OBJ [VARNAM]) => geobox</procedure>
129
130==== error-geobox
131
132<procedure>(error-geobox LOC OBJ [VARNAM])</procedure>
133
134==== geobox-minimum
135
136<procedure>(geobox-minimum GB) => geopoint</procedure>
137
138==== geobox-maximum
139
140<procedure>(geobox-maximum GB) => geopoint</procedure>
141
142==== geobox=
143
144<procedure>(geobox= GB1 GB2) => boolean</procedure>
145
146==== geobox<
147
148<procedure>(geobox< GB1 GB2) => boolean</procedure>
149
150==== geobox>
151
152<procedure>(geobox> GB1 GB2) => boolean</procedure>
153
154==== geobox<=
155
156<procedure>(geobox<= GB1 GB2) => boolean</procedure>
157
158==== geobox>=
159
160<procedure>(geobox>= GB1 GB2) => boolean</procedure>
161
162==== geopoint-within-box
163
164<procedure>(geopoint-within-box GP GB) => boolean</procedure>
165
166
167=== Module geopolygon
168
169==== Usage
170
171<enscript language=scheme>
172(import geopolygon)
173</enscript>
174
175==== Argument Conventions
176
177; {{GPOLY}} : {{geopolygon}}.
178
179==== make-geopolygon
180
181<procedure>(make-geopolygon GP ...) => geopolygon</procedure>
182
183{{GP}} is a {{geopoint}}.
184
185<procedure>(make-geopolygon GPS) => geopolygon</procedure>
186
187{{GPS}} is {{(or (list-of geopoint) (vector-of geopoint))}}.
188
189==== geopolygon?
190
191<procedure>(geopolygon? OBJ) => boolean</procedure>
192
193==== check-geopolygon
194
195<procedure>(check-geopolygon LOC OBJ [VARNAM]) => geopolygon</procedure>
196
197==== error-geopolygon
198
199<procedure>(error-geopolygon LOC OBJ [VARNAM])</procedure>
200
201==== geopolygon
202
203<procedure>(geopolygon GP...) => geopolygon</procedure>
204
205==== geopolygon-closed?
206
207<procedure>(geopolygon-closed? GPOLY) => boolean</procedure>
208
209Polygon has the same initial and final {{geopoint}}.
210
211==== geopolygon-open?
212
213<procedure>(geopolygon-open? GPOLY) => boolean</procedure>
214
215Polygon does not have the same initial and final {{geopoint}}.
216
217==== geopolygon-bounding-box
218
219<procedure>(geopolygon-bounding-box GPOLY) => geobox</procedure>
220
221
222=== Module geopoint-utils
223
224==== Usage
225
226<enscript language=scheme>
227(import geopoint-utils)
228</enscript>
229
230==== geopoint-in-closed-polygon?
231
232<procedure>(geopoint-in-closed-polygon? GP GPOLY [INTERSECTS? intersects?-pnp]) => boolean</procedure>
233
234Is the {{(: GP geopoint)}} in the {{(: GPOLY (or (vector-of geopoint)
235(list-of geopoint)))}}?
236
237{{INTERSECTS?}} is a {{(procedure ((: PI geopoint) (: PJ geopoint) (: LAT
238real) (: LON real)) => boolean)}} testing for ray intersection.
239
240Treats an open geopolygon as closed.
241
242==== intersects?-pnp
243
244<procedure>(intersects?-pnp PI PJ LAT LON) => boolean</procedure>
245
246==== intersects?-pip
247
248<procedure>(intersects?-pip PI PJ LAT LON) => boolean</procedure>
249
250
251=== Module geo-utils
252
253==== Usage
254
255<enscript language=scheme>
256(import geo-utils)
257</enscript>
258
259==== pythagorean-distance
260
261<procedure>(pythagorean-distance LAT1 LON1 LAT2 LON2) => real</procedure>
262
263==== pythagorean-distance*
264
265<procedure>(pythagorean-distance* LAT1 LON1 LAT2 LON2) => real</procedure>
266
267==== spherical-surface-distance
268
269<procedure>(spherical-surface-distance LAT1 LON1 LAT2 LON2 (R EARTH-RADIUS-KILOMETERS)) => real</procedure>
270
271==== great-circle-distance
272
273<procedure>(great-circle-distance LAT1 LON1 LAT2 LON2 (R EARTH-RADIUS-KILOMETERS)) => real</procedure>
274
275==== great-circle-distance-radians
276
277<procedure>(great-circle-distance-radians LAT1 LON1 LAT2 LON2 (R EARTH-RADIUS-KILOMETERS)) => real</procedure>
278
279==== approximate-ellipsoid-distance
280
281<procedure>(approximate-ellipsoid-distance LAT1 LON1 LAT2 LON2 (R EARTH-RADIUS-KILOMETERS) (F EARTH-FLATTENING)) => real</procedure>
282
283==== great-circle-azimuth
284
285<procedure>(great-circle-azimuth LAT1 LON1 LAT2 LON2 [PREC 5]) => real</procedure>
286
287==== great-circle-position
288
289<procedure>(great-circle-position LAT LON DIS AZI (R EARTH-RADIUS-KILOMETERS)) => (values latitude longitude)</procedure>
290
291
292=== Module geo-dms
293
294==== Usage
295
296<enscript language=scheme>
297(import geo-dms)
298</enscript>
299
300==== Argument Conventions
301
302; {{D}} : degrees {{real}}.
303; {{M}} : minutes {{real}}.
304; {{S}} : seconds {{real}}.
305; {{DEG}} : degrees{{real}}.
306; {{LAT?}} : latitude? {{boolean}}.
307; {{PAD}} : padding between elements {{string}}.
308; {{LEADING-DIR?}} : compass direction is prefix?
309
310==== degree-minute-second-text
311
312<procedure>(degree-minute-second-text [DMS-TEXT]) => (list-of string)</procedure>
313
314{{DMS-TEXT}} is a 3 element {{list}} of {{string}} of the form {{(<degrees
315suffix> <minutes suffix> <seconds suffix>)}}.
316
317==== dms->degree
318
319<procedure>(dms->degree D M S) => real</procedure>
320
321==== degree->dms
322
323<procedure>(degree->dms DEG) => (values D M S)</procedure>
324
325Returns the degree+minutes+seconds for the degrees {{DEG}}.
326
327==== dms->string
328
329<procedure>(dms->string D M S [LAT? [LEADING-DIR? [PAD ""]]]) => string</procedure>
330
331Example: 122°45'10"W
332
333==== dms->string*
334
335<procedure>(dms->string* D M S [PAD ""]) => string</procedure>
336
337Example: 122°45'10"
338
339==== string-dms->degree
340
341<procedure>(string-dms->degree STR [LAT?]) => real</procedure>
342
343Returns the degrees for string form of dms {{STR}}.
344
345==== string->degree
346
347<procedure>(string->degree STR [LAT?]) => real</procedure>
348
349Synonym of {{string-dms->degree}}.
350
351==== degree->string
352
353<procedure>(degree->string DEG [LAT? [LEADING-DIR? [PAD ""]]]) => string</procedure>
354
355Returns the dms-string for the degrees {{DEG}}.
356
357
358=== Module globe
359
360==== Usage
361
362<enscript language=scheme>
363(import geo-globe)
364</enscript>
365
366==== make-globe
367
368<procedure>(make-globe RADIUS FLATTENING) => globe</procedure>
369
370==== globe?
371
372<procedure>(globe? OBJ) => boolean</procedure>
373
374==== check-globe
375
376<procedure>(check-globe LOC OBJ [VARNAM]) => globe</procedure>
377
378==== error-globe
379
380<procedure>(error-globe LOC OBJ [VARNAM])</procedure>
381
382==== globe-radius-kilometers
383
384<procedure>(globe-radius-kilometers GLOBE) => number</procedure>
385
386==== globe-flattening-factor
387
388<procedure>(globe-flattening-factor GLOBE) => number</procedure>
389
390==== spherical-surface-distance
391
392<procedure>(spherical-surface-distance GLOBE GP1 GP2) => number</procedure>
393
394==== great-circle-distance
395
396<procedure>(great-circle-distance GLOBE GP1 GP2) => number</procedure>
397
398==== great-circle-distance-radians
399
400<procedure>(great-circle-distance-radians GLOBE GP1 GP2) => number</procedure>
401
402==== approximate-ellipsoid-distance
403
404<procedure>(approximate-ellipsoid-distance GLOBE GP1 GP2) => number</procedure>
405
406==== great-circle-azimuth
407
408<procedure>(great-circle-azimuth GP1 GP2 [PRECISION 5]) => number</procedure>
409
410==== great-circle-position
411
412<procedure>(great-circle-position GLOBE GP DISTANCE AZIMUTH) => geopoint</procedure>
413
414
415=== Module earth
416
417==== Usage
418
419<enscript language=scheme>
420(import geo-earth)
421</enscript>
422
423==== *earth-flattening*
424
425<variable>*earth-flattening* => real</variable>
426
427==== *earth-radius-miles*
428
429<variable>*earth-radius-miles* => real</variable>
430
431==== *earth-radius-kilometers*
432
433<variable>*earth-radius-kilometers* => real</variable>
434
435==== make-earth
436
437<procedure>(make-earth) => globe</procedure>
438
439
440== Bugs & Limitations
441
442* Probably some.
443
444
445== Notes
446
447* The relational predicates are rather useless.
448
449* Incomplete.
450
451
452== Requirements
453
454[[mathh]]
455[[vector-lib]]
456[[check-errors]]
457
458
459== Author
460
461[[/users/kon-lovett|Kon Lovett]]
462
463
464== Version history
465
466; 1.0.0 : CHICKEN 5 release.
467; 0.5.0 : Add {{earth}}.
468; 0.4.0 : SI default. Add {{globe}}.
469; 0.3.2 : Uses numbers.
470; 0.3.1 : Uses test.
471; 0.3.0 : .
472; 0.2.0 : .
473; 0.1.1 : .
474; 0.1.0 : Hello
475
476
477== License
478
479Copyright (C) 2017-2018 Kon Lovett.  All rights reserved.
480
481Permission is hereby granted, free of charge, to any person obtaining a
482copy of this software and associated documentation files (the Software),
483to deal in the Software without restriction, including without limitation
484the rights to use, copy, modify, merge, publish, distribute, sublicense,
485and/or sell copies of the Software, and to permit persons to whom the
486Software is furnished to do so, subject to the following conditions:
487
488The above copyright notice and this permission notice shall be included
489in all copies or substantial portions of the Software.
490
491THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
492IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
493FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
494THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
495OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
496ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
497OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.