# Options for creating polygonal crown maps

#### Andrew Plowright

#### 2018-04-04

## Issues with mcws

Although the `mcws` function computes crown maps as a raster, many users find that having crowns as polygons is more useful for analytical purposes. Therefore, a `format` argument was added which, when set to `format = "polygons"`, makes the function convert the raster map to a set of polygons. As an added benefit, the function also carries over the attributes of the `treetops` argument into the newly created polygons, i.e.: if an input treetop has a height field associated with it, its corresponding crown polygon will also have that same value. The `SegmentCrown` function also computes the crowns’ horizontal area, which is stored in the output’s crownArea field.

However, the underlying function used to convert rasters to polygons is `rasterToPolygons`, from the raster package. This function is problematic due to its slow processing speed and its tendency to leak memory when applied to multiple datasets.

## Using the GDAL library instead

An alternative option is available for users who have installed OSGeo for Windows. OSGeo4W is a suite of free open source geospatial software, such as GDAL, GRASS and QGIS. In particular, it contains the gdal_polygonize.py GDAL utility, which performs the same function as `rasterToPolygons` but with a much better performance.

John Baumgartner and Francisco Rodriguez-Sanchez developed a script to run the gdal_polygonize.py utility from R. This solution has been integrated into the `mcws` function.

## Installation

First, ensure that the `APfun` library (on which the `ForestTools` is dependant) is up-to-date (it should be version 0.1.1 at a minimum).

    update.packages()

    packageVersion("APfun")

The GDAL utility requires three things to be installed:

- The OSGeo4W Shell
- Python
- The GDAL/OGR Python bindings and scripts

All three can be installed simultaneously by downloading the OSGeo4W installer. Once the installer is downloaded, select either Express Desktop Install or Advanced Install.

Selecting Express Desktop Install is recommended, and will install the standard suite of OSGeo software (including everything needed here). However, to select only the required components for running gdal_polygonize.py utility, follow these steps:

1. Select Advanced Install
2. Go through the next six menus, selecting whichever installation options are appropriate for your system.
3. Once you reach the Select Packages menu, open the Libs dropdown category.

4. Scroll down and select the gdal-python: The GDAL/OGR Python Bindings and Scripts package.

5. Click Next. The next menu will display other packages that must be installed along with gdal-python. Accept these and continue with the installation.

## Usage

Once OSGeo4W has been installed, the only new argument that must be defined when using `mcws` is `OSGeoPath`, the path to the OSGeo4W installation directory. By default, the path for the 64-bit version of OSGeo4W is ‘C:\OSGeo4W64’. Simply add this parameter to `mcws`, and the function will use the GDAL library for computing crown polygons.

This should significantly improve processing speeds and resolve memory leak issues from earlier version.

    library(ForestTools)

    data("kootenayCHM")
    data("kootenayTrees")

    kootenayCrowns <- mcws(kootenayTrees, kootenayCHM, minHeight = 1.5, format = "polygons", OSGeoPath = "C:\\OSGeo4W64")