From 6ecba7ae144843919152d37793721483ec0fa0be Mon Sep 17 00:00:00 2001
From: Matt Birkholz <puck@birchwood-abbey.net>
Date: Mon, 13 Jun 2016 19:31:23 -0700
Subject: [PATCH] planetarium/mit-scheme-planetarium.texi: Add Terrain Viewer
 node.

---
 src/planetarium/mit-scheme-planetarium.texi | 106 +++++++++++++++++++-
 1 file changed, 104 insertions(+), 2 deletions(-)

diff --git a/src/planetarium/mit-scheme-planetarium.texi b/src/planetarium/mit-scheme-planetarium.texi
index 70ee5eb33..3de84eb0f 100644
--- a/src/planetarium/mit-scheme-planetarium.texi
+++ b/src/planetarium/mit-scheme-planetarium.texi
@@ -46,10 +46,11 @@ Documentation License.''
 
 @menu
 * Introduction::
+* Terrain Viewer::
 * GNU Free Documentation License::
 @end menu
 
-@node Introduction, GNU Free Documentation License, Top, Top
+@node Introduction, Terrain Viewer, Top, Top
 @chapter Introduction
 
 This planetarium currently is just a simple tellurion that shows the
@@ -108,7 +109,108 @@ you apply it to @code{go}.
     (t 'GO)
 @end example
 
-@node GNU Free Documentation License, , Introduction, Top
+@node Terrain Viewer, GNU Free Documentation License, Introduction, Top
+
+This planetarium includes a viewer for visualizing meshes.  It can
+generate meshes from a few mathematical functions, and it can download
+elevation data from Google Earth.
+
+To generate a terrain from a simple mathematical function, startup
+mit-scheme and enter the following three s-expressions at the REPL
+prompt.
+
+@example
+    (load-option 'planetarium)
+    (ge '(planetarium terrain))
+    (write-function-terrain
+     "sample-terrain.txt"
+     -3 3 50
+     -3 3 50
+     (lambda (x y)
+       (let ((d^2+1 (+ (* x x) (* y y) 1)))
+         (* 1000 (/ (sin d^2+1) d^2+1)))))
+@end example
+
+A @file{sample-terrain.txt} file will be created in the current
+directory and filled with 2500 samples of the given function as x and
+y vary between -3 and 3.  The function is scaled by 1000 because it
+is interpreted as meters given degrees of longitude and latitude.
+
+To view your sample terrain enter the following four s-expressions.
+
+@example
+    (define v (make-terrain
+               'filename "sample-terrain.txt"
+               'rows 50 'columns 50
+               'latitude 0. 'longitude 0.
+               'step .001))
+    (v 'position -.02 -.02 4000.)
+    (v 'heading 45.)
+    (v 'tilt -40.)
+@end example
+
+A viewer window should appear and display an image like
+the one at this URL:
+@code{http://birchwood-abbey.net/~matt/Scheme/sample-terrain.png}.
+@c How do I inset a small image?
+
+In the viewer window your up/down arrow keys should move the camera
+forward/backward approximately 100 meters.  The left/right keys turn
+the camera.  Hold the Ctrl key and press up/down to tilt the camera.
+
+Generating a terrain by querying Google Earth can take a while, so you
+will want to create a restartable script and run it in the background.
+Here is an example that downloads 10201 elevations in a 101 by 101
+grid across 1 degree of latitude and longitude centered on Monterey
+Bay, California.
+
+@example
+    #!/bin/bash
+    mit-scheme --batch-mode <<\EOF
+    (begin
+      (load-option 'planetarium)
+      (request-google-elevations "monterey.txt"
+                                 (make-latitudes/longitudes
+                                  (iota 101 36. .01)
+                                  (iota 101 -122.5 .01)))
+      )
+    EOF
+@end example
+
+You might name the script @file{~/job.sh} and run it in the background
+using the Unix @code{at} command, as shown below, then wait for email
+notifying you that the job is complete.  If it fails, you might submit
+it again just as before; it will pick up where it left off.  It will
+request elevations only as fast as Google's free service allows, so
+you might wait an entire day for 10201 elevations to download.
+
+@example
+    $ chmod +x ~/job.sh
+    $ at now
+    > ~/job.sh
+    > ^D
+@end example
+
+Tomorrow, after you get email saying your job has successfully
+completed, you can view the data by entering the following four
+s-expressions.
+
+@example
+    (ge '(planetarium terrain))
+    (define v (make-terrain
+               'filename "monterey.txt" 'rows 101 'columns 101
+               'latitude 36. 'longitude -122.5 'step .01
+               'color-function height-color))
+    (v 'position 36.5 -122.7 15000.)
+    (v 'heading 85.)
+    (v 'tilt -25.)
+@end example
+
+A viewer window should appear and display an image like
+the one at this URL:
+@code{http://birchwood-abbey.net/~matt/Scheme/monterey-bay-1.png}.
+
+@node GNU Free Documentation License, , Terrain Viewer, Top
 @appendix GNU Free Documentation License
 
 @cindex FDL, GNU Free Documentation License
-- 
2.25.1