# PROJ

## What is PROJ?

Generic map projection transformations on raw data.

We use the PROJ library to perform projection transformations on raw data. We can use a matrix or data frame of 2, 3, or 4 columns and these are assumed (if present) to be “x”, “y”, “z”, and “t” (time: modern transformations allow a temporal component as the shape of the earth and our models of it do change over time).

The transformation idiom used is 1) provide raw coordinates; 2) specify their source projection; 3) specify their target projection.

We enter into the coordinate order debacle of the OGC for longitude, latitude by precluding other options. We use longitude, latitude order.

## Why PROJ?

This package was created to leverage the modern transformation capabilities of PROJ itself from version 6 and above. There’s no other package in R that allows generic transformations directly from the PROJ library, and this package provides that along with these goals:

- no other dependencies (PROJ library is it, and R)
- allow geocentric transformations, and 3D and 4D transformations generally.
- provide no interpretation or restrictions on source or target projection specification
- do not require special formats, we use numeric vectors in matrix or data frame form

## What systems are supported?

- Windows - on CRAN the PROJ is available as a binary package, PROJ 6 (or higher) is bundled in with the binary package.
- Linux - the PROJ package will use your system PROJ library, it must be version 6 (or higher).
- Mac - on CRAN there are binaries, PROJ 6.3.1 since mid 2020

Binaries means that the package comes with everything it needs, you don’t need to install PROJ library in the system. If you do install PROJ library yourself, say with brew on MacOS, then the from-source install should also just work. There’s no need to specify the location of file folders, as long as proj itself is working and available.

## How to use PROJ?

Get the package installed, load it and use the function `proj_trans()`.

If you don’t have system PROJ version 6 (or higher) the function will fail.

    library(PROJ)
    proj_trans(cbind(c(0, 147), c(0, -42)), z_ = 0, target = "+proj=laea +datum=WGS84", source = "WGS84")
    #> $x_
    #> [1]       0 5969744
    #>
    #> $y_
    #> [1]        0 -9803200
    #>
    #> $z_
    #> [1] 0 0
    #>
    #> $t_
    #> [1] 0 0

Note that we always assume input of `cbind(longitude, latitude)` and can optionally provide a vector of `z_` as well as `t_`. We cannot provide a 3 or 4 column matrix, z and t must be provided separately as named arguments.

Note that various forms of projection string are supported, we can use PROJ.4 style (as per target above), bare names from EPSG (as per source above), full-blown WKT2 strings, or ‘auth:code’ forms such as “epsg:3857”. (Note that “+init=…” forms cannot be used in 6 or above).

The goal is for the reproj package to wrap this package. In time that will be the easiest way to run coordinate transformations with PROJ for versions 4, 5, 6, 7 or above.