Fixes #444, #478.

doc/source/math/geocoordinates.rst

@@ -35,26 +35,41 @@ Structure
 
         * - Suffix
           - Type
+	  - Args
           - Description
 
         * - :attr:`LAT`
           - scalar (deg)
+	  - none
           - Latitude
         * - :attr:`LNG`
           - scalar (deg)
+	  - none
           - Longitude
         * - :attr:`DISTANCE`
           - scalar (m)
+	  - none
           - distance from :ref:`CPU Vessel <cpu vessel>`
         * - :attr:`TERRAINHEIGHT`
           - scalar (m)
+	  - none
           - above or below sea level
         * - :attr:`HEADING`
           - scalar (deg)
+	  - none
           - *absolute* heading from :ref:`CPU Vessel <cpu vessel>`
         * - :attr:`BEARING`
           - scalar (deg)
+	  - none
           - *relative* direction from :ref:`CPU Vessel <cpu vessel>`
+        * - :attr:`POSITION`
+          - `Vector` (3D Ship-Raw coords)
+	  - none
+          - Position of the surface point.
+        * - :attr:`ALTITUDEPOSITION`
+          - `Vector` (3D Ship-Raw coords)
+	  - scalar (altitude above sea level)
+          - Position of a point above (or below) the surface point, by giving the altitude number.
 
 .. attribute:: GeoCoordinates:LAT
 
@@ -80,6 +95,14 @@ Structure
 
     The *relative* compass direction from the :ref:`CPU_Vessel <cpu vessel>` to this point on the surface. For example, if the vessel is heading at compass heading 45, and the geo-coordinates location is at heading 30, then :attr:`GeoCoordinates:BEARING` will return -15.
 
+.. attribute:: GeoCoordinates:POSITION
+
+    The ship-raw 3D position on the surface of the body, relative to the current ship's Center of mass.
+
+.. attribute:: GeoCoordinates:ALTITUDEPOSITION (altitude)
+
+    The ship-raw 3D position above or below the surface of the body, relative to the current ship's Center of mass.  You pass in an altitude number for the altitude above "sea" level of the desired location.
+
 Examples Usage
 --------------
 
@@ -105,6 +128,20 @@ Examples Usage
                                              // location 5  degrees east
                                              // of the old one
 
+    // Point nose of ship at a spot 100,000 meters altitude above a
+    // particular known latitude of 50 east, 20.2 north:
+    LOCK STEERING TO LATLNG(50,20.2):ALTITUDEPOSITION(100000).
+
+    // A nice complex example:
+    // -------------------------
+    // Drawing an debug arrow in 3D space at the spot where the Geocoordinate 'spot' is:
+    // It starts at a position 100m above the ground altitude and is aimed down at
+    // the spot on the ground:
+    SET VD TO VECDRAWARGS(
+                  spot:ALTITUDEPOSITION(spot:TERRAINHEIGHT+100),
+                  spot:POSITION - spot:ALTITUDEPOSITION(TERRAINHEIGHT+100),
+                  red, "THIS IS THE SPOT", 1, true).
+
     PRINT "THESE TWO NUMBERS SHOULD BE THE SAME:".
     PRINT (SHIP:ALTITIUDE - SHIP:GEOPOSITION:TERRAINHEIGHT).
     PRINT ALT:RADAR.

src/kOS/Suffixed/GeoCoordinates.cs

@@ -118,7 +118,7 @@ private double GetTerrainAltitude()
                 // a point a bit below it, to aim down to the terrain:
                 Vector3d worldRayCastStop = Body.GetWorldSurfacePosition( Lat, Lng, alt+POINT_AGL );
                 RaycastHit hit;
-                if (Physics.Raycast(worldRayCastStart, (worldRayCastStop - worldRayCastStart), out hit, 1<<TERRAIN_MASK_BIT ))
+                if (Physics.Raycast(worldRayCastStart, (worldRayCastStop - worldRayCastStart), out hit, float.MaxValue, 1<<TERRAIN_MASK_BIT ))
                 {
                     // Ensure hit is on the topside of planet, near the worldRayCastStart, not on the far side.
                     if (Mathf.Abs(hit.distance) < 3000)
@@ -158,9 +158,30 @@ private double GetHeadingFrom()
         /// <returns>distance scalar</returns>
         private double GetDistanceFrom()
         {
-            Vector3d latLongCoords = Body.GetWorldSurfacePosition( Lat, Lng, GetTerrainAltitude() );
+            return GetPosition().Magnitude();
+        }
+
+        /// <summary>
+        ///   The surface point of this LAT/LONG from where
+        ///   the current CPU vessel is now.
+        /// </summary>
+        /// <returns>position vector</returns>
+        public Vector GetPosition()
+        {
+            return GetAltitudePosition(GetTerrainAltitude());
+        }
+
+        /// <summary>
+        ///   The point above or below the surface of this LAT/LONG from where
+        ///   the current CPU vessel is now.
+        /// </summary>
+        /// <param name="altitude">The (sea level) altitude to get a position for</param>>
+        /// <returns>position vector</returns>
+        public Vector GetAltitudePosition(double altitude)
+        {
+            Vector3d latLongCoords = Body.GetWorldSurfacePosition(Lat, Lng, altitude);
             Vector3d hereCoords = Shared.Vessel.findWorldCenterOfMass();
-            return Vector3d.Distance( latLongCoords, hereCoords );
+            return new Vector(latLongCoords - hereCoords);
         }
 
         private void GeoCoordsInitializeSuffixes()
@@ -172,6 +193,12 @@ private void GeoCoordsInitializeSuffixes()
             AddSuffix("DISTANCE", new Suffix<double>(GetDistanceFrom));
             AddSuffix("HEADING", new Suffix<double>(GetHeadingFrom));
             AddSuffix("BEARING", new Suffix<double>(GetBearing));
+            AddSuffix("POSITION", new Suffix<Vector>(GetPosition,
+                                                     "Get the 3-D space position relative to the ship center, of this lat/long, " +
+                                                     "at a point on the terrain surface"));
+            AddSuffix("ALTITUDEPOSITION", new OneArgsSuffix<Vector,double>(GetAltitudePosition,
+                                                                           "Get the 3-D space position relative to the ship center, " +
+                                                                           "of this lat/long, at this (sea level) altitude"));
         }
 
         public override string ToString()