---
title: "Code Details"
author: "Derek Friend"
date: "Last compiled on `r format(Sys.time(), '%B %d, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{quadtree-code}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Vignette content

This vignette gives a brief overview of the code structure of the `quadtree` package.

## Implementation details

The bulk of the code is written in C++ and interfaced with R via 'Rcpp'.

The overall design philosophy was to keep the core C++ code completely independent from the R code (i.e. no 'Rcpp'-related code in the core C++ files.) This results in a three-tiered organization of the code - core C++ code, 'Rcpp' C++ code, and  R code.

### Core C++ code

This consists of the following files (only the .h files are listed to avoid redundancy, but each of these files has a corresponding .cpp file):

* Matrix.h - Defines the `Matrix` class implementing basic matrix functionality
* Node.h - Defines the `Node` class, which are the nodes of the quadtree
* Point.h - Defines a simple `Point` class
* PointUtilities.h - Defines a namespace containing functions for performing  calculations with `Point` objects
* Quadtree.h - Defines the `Quadtree` class, which can be seen as a wrapper that provides a link to the interconnected nodes that make up the quadtree
* LcpFinder.h - Defines the `LcpFinder` class, which is used for finding least-cost paths using a quadtree as a cost surface

As mentioned before, these files are completely independent of R and can be built and run independently of R.

### 'Rcpp' C++ code

These files are called 'wrappers' - essentially they each contain an instance of the relevant object and provide additional 'Rcpp'-related functions that can be accessed from R. These essentially provide the "bridge" that allows the functionality in the core C++ files to be accessed from R.

* NodeWrapper.h - wrapper class for `Node`. This class is exposed to R as `CppNode`.
* QuadtreeWrapper.h - wrapper class for `Quadtree`. This class is exposed to R as `CppQuadtree`.
* LcpFinderWrapper.h - wrapper class for `LcpFinder`. This class is exposed to R as `CppLcpFinder`.
* R_Interface.h - defines a namespace that currently contains only a single function, which converts an 'Rcpp' matrix to the `Matrix` class I created. This function is separate from the other files because it is a general-purpose function and thus didn't fit in any of the wrapper classes.
* load_modules.cpp - contains code that exposes the wrapper classes to R using 'Rcpp' modules.

### R code

Almost all of the core functionality of the quadtree package is contained in the C++ code, and the R code serves primarily as an interface for working with the C++ quadtree data structure. A `Quadtree` S4 class is defined which consists only of one slot, which contains a `CppQuadtree` object. The methods for this class are often quite simple, merely consisting of calling one of the methods on the `CppQuadtree` object. Similarly, the `LcpFinder` class contains a `CppLcpFinder` object. Using this approach has a few benefits. First, wrapping the C++ class in an S4 class allows the quadtree functionality to be accessed in a way that is much more consistent with typical R syntax, which will hopefully be more intuitive to R users. Second, it allows for me to add R code to validate and make any necessary modifications to parameters before calling the C++ methods - this helps make the functions more robust. This also allows me to take advantage of existing R functionality (for example, resampling a raster from the 'raster' package).

I won't discuss each R file/function here - see the the function help files for details on each R function.