---
title: "PROJ"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{PROJ}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---



## What is PROJ?

Generic map projection transformations on raw data.

We use the [PROJ library](https://proj.org/) 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](https://www.ogc.org/) 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](https://proj.org/) 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.


```r
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](https://epsg.org/home.html) (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](https://CRAN.r-project.org/package=reproj) 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.