This vignette gives a brief overview of the code structure of the
quadtree package.
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.
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 class implementing basic
matrix functionalityNode class, which are the nodes of
the quadtreePoint classPoint objectsQuadtree class, which can be
seen as a wrapper that provides a link to the interconnected nodes that
make up the quadtreeLcpFinder class, which is
used for finding least-cost paths using a quadtree as a cost
surfaceAs mentioned before, these files are completely independent of R and can be built and run independently of R.
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.
Node. This class is
exposed to R as CppNode.Quadtree. This
class is exposed to R as CppQuadtree.LcpFinder. This
class is exposed to R as CppLcpFinder.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.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.