Proj is a selective and on-going port of the venerable PROJ.4 project to the Go language.
We do not intend to port all of PROJ.4: there is stuff in PROJ.4 that we'll probably never have a sufficient justification for bringing over. Likewise, we do not intend to do a verbatim port of the original code: naively translated C code doesn't make for maintainable (or idiomatic) Go code.
To install the packages, preparatory to using them in your own code:
go get -U github.com/go-spatial/proj
To copy the repo, preparatory to doing development:
git clone https://github.com/go-spatial/proj go test ./...
See below for API usage instructions.
In no particular order, these are the conditions we're imposing on ourselves:
- We are going to use the PROJ 5.0.1 release as our starting point.
- We will look to the
proj4js
project for suggestions as to what PROJ4 code does and does not need to be ported, and how. - We will consider numerical results returned by PROJ.4 to be "truth" (within appropriate tolerances).
- We will try to port the "mathy" parts with close to a 1:1 correspondence, so as to avoid inadvertently damaging the algoirthms.
- The "infrastructure" parts, however, such as proj string parsing and the coordinate system classes -- I'm looking at you,
PJ
-- will be generally rewritten in idiomatic Go. - The
proj
command-line app will not be fully ported. Instead, we will provide a much simpler tool. - All code will pass muster with the various Go linting and formatting tools.
- Unit tests will be implemented for pretty much everything, using the "side-by-side"
_test
package style. Even without testing all error return paths, but we expect to reach about 80% coverage. - We will not port PROJ.4's new
gie
test harness directly; we will do a rewrite of a subset of it's features instead. The Go version fogie
should nonetheless be able to parse all of PROJ.4's supplied.gie
files. - Go-style source code documentation will be provided.
- A set of small, clean usage examples will be provided.
There are two APIs at present, helpfully known as "the conversion API" and "the core API".
This API is intended to be a dead-simple way to do a 2D projection from 4326. That is:
You Have: a point which uses two float64
numbers to represent lon/lat degrees in an epsg:4326
coordinate reference system
You Want: a point which uses two float64
numbers to represent meters in a projected coordinate system such as "web mercator" (epsg:3857
).
If that's what you need to do, then just do this:
var lonlat = []float64{77.625583, 38.833846}
xy, err := proj.Convert(proj.EPSG3395, lonlat)
if err != nil {
panic(err)
}
fmt.Printf("%.2f, %.2f\n", xy[0], xy[1])
Note that the lonlat
array can contain more than two elements, so that you can project a whole set of points at once.
This API is stable and unlikely to change much. If the projected EPSG code you need is not supported, just let us know.
Beneath the Conversion API, in the core
package, lies the real API. With this API, you can provide a proj string (+proj=utm +zone=32...
) and get back in return a coordinate system object and access to functions that perform forward and inverse operations (transformations or conversions).
The Core API is a work in progress. Only a subset of the full PROJ.4 operations are currently supported, and the structs and interfaces can be expected to evolve as we climb the hill to support more proj string keys, more projections, grid shifts, .def
files, and so on.
For examples of how to sue the Core API, see the implementation of proj.Convert
(in Convert.go
) or the sample app in cmd/proj
.
The proj repo contains these packages (directories):
proj
(top-level): the Conversion APIproj/cmd/proj
: the simpleproj
command-line toolproj/core
: the Core API, representing coordinate systems and conversion operationsproj/gie
: a naive implementation of the PROJ.4gie
tool, plus the full set of PROJ.4 test case filesproj/merror
: a little error packageproj/mlog
: a little logging packageproj/operations
: the actual coordinate operations; these routines tend to be closest to the original C codeproj/support
: misc structs and functions in support of thecore
package
Most of the packages have _test.go
files that demonstrate how the various types and functions are (intended to be) used.
We need to support grid shifts, turn on more proj string keys, make the Ellipse and Datum types be more independent, port a zillion different projection formulae, the icky operation typing needs to be rethought, and on and on. Such future work on proj
will likely be driven by what coordinate systems and operations people need to be supported: someone will provide a proj string that leads to successful numerical outputs in PROJ.4 but dies in proj.
We welcome your participation! See CONTRIBUTING.md
and/or contact [email protected]
if you'd like to help out on the project.