Updating license, readme, and documentation

LICENSE

@@ -0,0 +1,22 @@
+© Copyright and database rights Ordnance Survey Limited 2016, © Crown copyright and database rights Land & Property Services 2016 and/or © Ordnance Survey Ireland, 2016. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,104 @@
+go-osgb
+============
+
+A Go library for performing accurate conversions between OS National Grid and GPS coordinates. (More technically, coordinate transformations between the OSGB36/ODN and ETRS89 geodetic datums)
+
+Why would I need this?
+------------
+Geodetic transformations that assume perfect geometry lose precision on imperfect geoids (e.g. The Helmert transformation for ETRS89 to OSGB36/ODN has errors up to 5m). This library implements the definitive transformation developed by Ordnance Survey for converting between National Grid and GPS coordinates, resulting in very accurate conversions (average < 0.1m error).
+
+Features
+------------
+  - Supports OSTN02/OSGM02 and OSTN15/OSGM15 transformations
+  - All transformation parameters are included in the library. No need to load additional files!
+  - Fully tested against the conversion samples provided in the Ordnance Survey developer resources
+
+Installation
+------------
+    go get github.com/fofanov/go-osgb
+
+Usage
+------------
+Converting from National Grid to GPS
+```go
+    import (
+        "log"
+
+        osgb "github.com/fofanov/go-osgb"
+    )
+
+    func main() {
+        trans, err := osgb.NewOSTN15Transformer()
+        if err != nil {
+            log.Fatal(err)
+        }
+        easting := 400001.4
+        northing := 305001.4
+        height := 5.0
+        nationalGridCoord := osgb.NewOSGB36Coord(easting, northing, height)
+        gpsCoord, err := trans.FromNationalGrid(nationalGridCoord)
+        if err != nil {
+            log.Fatal(err)
+        }
+        log.Printf("%#v\n", gpsCoord)
+        // &osgb.ETRS89Coordinate{Lon:-2.001408181413446, Lat:52.64276984554203, Height:55.34172940576156}
+    }
+```
+
+Converting from GPS to National Grid
+```go
+    import (
+        "log"
+
+        osgb "github.com/fofanov/go-osgb"
+    )
+
+    func main() {
+        trans, err := osgb.NewOSTN15Transformer()
+        if err != nil {
+            log.Fatal(err)
+        }
+
+        lon := -0.1262
+        lat := 51.5080
+        height := 10.5
+        gpsCoord := osgb.NewETRS89Coord(lon, lat height)
+        nationalGridCoord, err := trans.ToNationalGrid(gpsCoord)
+        if err != nil {
+            log.Fatal(err)
+        }
+        log.Printf("%#v\n", nationalGridCoord)
+        // &osgb.OSGB36Coordinate{Easting:530136.3274244666, Northing:180449.45428526515, Height:-35.04663654446814}
+    }
+```
+
+Coordinate Units
+------------
+National Grid eastings, northings and ODN height are all in metres.
+GPS longitude and latitude are in decimal degrees. Height is in metres.
+
+Transformation Limits
+------------
+The transformation is only accurately defined for onshore positions of British Islands.
+
+When using OSTNO2, transformations attempted for positions greater than 10km offshore will return an `ErrPointOutsidePolygon` error.
+
+OSTN15 will not return an error for offshore transformations, but precision is severely degraded, so usage is not recommended. However, straying outside the extents of the 700x1250km transformation grid completely will lead to an `ErrPointOutsideTransformation` error.
+
+I want to know more about the transformation
+------------
+The full details can be found in the [developers section](https://www.ordnancesurvey.co.uk/business-and-government/help-and-support/navigation-technology/os-net/formats-for-developers.html) of the Ordnance Survey website.
+
+
+Roadmap
+------------
+-  [ ] Expose geoid regions for ODN heights
+-  [ ] Support transformations on the Irish mainland
+
+License
+------------
+This library is released under the BSD license, as are the transformation models provided by Ordnance Survey. Full details can be found in the LICENSE file.
+
+
+
+

coordinates.go

@@ -19,23 +19,40 @@ const (
 	west  direction = "W"
 )
 
+// ETRS89Coordinate represents a coordinate position in
+// the ETRS89 geodetic datum. Whilst not being identical
+// this can be treated as a GPS coordinate.
 type ETRS89Coordinate struct {
-	Lat, Lon, Height float64
+	// Longitude in decimal degrees
+	Lon float64
+	// Latitude in decimal degrees
+	Lat float64
+	// Height in metres
+	Height float64
 }
 
-type OSGB36Coordinate struct {
-	Easting, Northing, Height float64
-}
-
-func NewETRS89Radians(lat, lon, height float64) *ETRS89Coordinate {
+// NewETRS89Coord creates a new coordinate position in the ETRS89 geodetic datum.
+func NewETRS89Coord(lon, lat, height float64) *ETRS89Coordinate {
 	return &ETRS89Coordinate{
-		Lat:    lat,
 		Lon:    lon,
+		Lat:    lat,
 		Height: height,
 	}
 }
 
-func NewOSGB36(easting, northing, height float64) *OSGB36Coordinate {
+// OSGB36Coordinate represents a coordinate position in
+// the OSGB36/ODN geodetic datum.
+type OSGB36Coordinate struct {
+	// Easting in metres
+	Easting float64
+	// Northing in metres
+	Northing float64
+	// Height in metres
+	Height float64
+}
+
+// NewOSGB36Coord creates a new coordinate position in the OSGB36/ODN geodetic datum.
+func NewOSGB36Coord(easting, northing, height float64) *OSGB36Coordinate {
 	return &OSGB36Coordinate{
 		Easting:  easting,
 		Northing: northing,

ostn_osgm_gb.go

@@ -5,8 +5,12 @@ import (
 	"math"
 )
 
-var ErrPointOutsidePolygon = errors.New("point outside polygon")
-var ErrPointOutsideTransformation = errors.New("point outside transformation limits")
+var (
+	// ErrPointOutsidePolygon indicates the position is too far offshore to be transformed.
+	ErrPointOutsidePolygon = errors.New("point outside polygon")
+	// ErrPointOutsideTransformation indicates the position is completely outside the grid transformation extent
+	ErrPointOutsideTransformation = errors.New("point outside transformation limits")
+)
 
 const (
 	nEastIndices            = 701
@@ -36,8 +40,11 @@ const (
 	Region_OUTSIDE_TRANSFORMATION geoidRegion = 16 // 15
 )
 
+// CoordinateTransformer is used to convert between OSGB36/ODN and ETRS89 geodetic datums
 type CoordinateTransformer interface {
+	// ToNationalGrid coverts a coordinate position from ETRS89 to OSGB36/ODN
 	ToNationalGrid(c *ETRS89Coordinate) (*OSGB36Coordinate, error)
+	// FromNationalGrid coverts a coordinate position from OSGB36/ODN to ETRS89
 	FromNationalGrid(c *OSGB36Coordinate) (*ETRS89Coordinate, error)
 }
 

records.go

@@ -29,7 +29,6 @@ func readRecords(translationVectorFile string) ([]record, error) {
 	}
 
 	r := csv.NewReader(bytes.NewReader(data))
-	log.Printf("Reading data from %s...\n", translationVectorFile)
 	// Read header
 	if _, err := r.Read(); err != nil {
 		return nil, err
@@ -83,7 +82,6 @@ func readRecords(translationVectorFile string) ([]record, error) {
 				geoidRegion:     geoidDatumToRegion(geoidDatum),
 			})
 	}
-	log.Printf("Reading %s data completed...\n", translationVectorFile)
 	return res, nil
 }