# 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 don’t enter into the coordinate order debacle of the OGC for longitude, latitude. Projection strings are able to carry this information, and passing in the right data is the responsibility of the user.

## 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
- 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 package should just work, 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 - we don’t know yet, in the past CRAN makes this work for new packages.

## How to use PROJ?

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

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

    library(PROJ)
    proj_trans_generic(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_
    #> numeric(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.

To find out if your system supports PROJ 6 (or higher) use the function `ok_proj6()`.

    ok_proj6()
    #> [1] TRUE