AreaCon

About AreaCon.

AreaCon is a free open source C++ library for performing area-constrained partitioning operations on convex, 2D polygonal regions. It is intended primarily for use in robot and mobile sensor network applications in which the workspace is to be divided among the available agents in an optimal way. AreaCon allows the user to specify the final weighted area of each of the resultant regions, thus providing a natural load-balancing that is useful in a variety of static and dynamic coverage applications, as well as a variety of applications that involve optimal division of workload. Specifically, given a prior density defined over a polygonal region of interest, AreaCon provides a numerical implementation of a theoretically rigorous, bio-inspired algorithm that systematically divides the region into a set of disjoint, convex, and centroidal regions with pre-specified areas. The entire library consists of a single compilation unit (one .hpp and one .cpp file), which has dependence on a single free and open source third party library (the Polygon Clipper Library). It can therefore be seamlessly integrated into more complex planning codes that require simple load-balancing steps without the weight of a larger computational geometry library.

AreaCon v.1 provides the following on planar, convex polygonal environments:

Area-constrained partitioning over arbitrary density functions

Centroid computation

A variety of useful geometric structures and associated functions

Note that although AreaCon only provides explicit support for convex polygonal environments, it supports arbitrary density functions. Therefore, the library can also be used for partitioning on a much larger class of planar environments by strategically defining regions of zero density. Exact or arbitrary precision arithmetic is avoided for additional robustness in numerical implementation. However, functionality is still somewhat sensitive to a variety of algorithmic parameters (step-sizes, stopping-criteria, integration parameters, etc.). If these parameters are chosen poorly or the scale of the underlying density varies wildly, the library can and will return errors. Despite this, if parameters are chosen properly the library will produce high-quality results for a number of environments and densities. In addition, reasonable results can be obtained for most "regular" workspaces using the provided default parametric values.

Basic Usage

To use AreaCon in your C++ program:

Download the AreaCon library using the links at the top of the page.

Unzip and extract the files,

Place an #include "areacon.hpp" directive at the beginning of your program, and

Link your code with "areacon.cpp" and "clipper.cpp" when compiling.

You can now use AreaCon in your program!

AreaCon can be used in a variety of different ways. However, general calls to AreaCon for use in area-constrained partitioning will usually follow these basic steps:

Define the region to be partitioned, the number of regions to be used, and the desired areas of the resultant regions

That's all there is to it! Note that AreaCon can also be used for a variety of other basic geometric operations, e.g., finding centroids. Detailed source code documentation is included in pdf form with the AreaCon download, or can be found here. Some useful tips and troubleshooting advice can be found on the FAQ page, and more detailed discussion about the functionality of AreaCon can be found on the Wiki.
I am very interested to learn what type of projects have utilized AreaCon, so please feel free to contact me and let me know!

Quick Start Example

In-depth discussions about usage including how to create polygons, define prior density functions, choose algorithmic parameters, and initialize partition objects, as well as some helpful numerical examples can be found on the Wiki. However, as a quick-start guide that will illustrate generic usage, we offer the following example.

Partitioning Over a Uniform Prior: Consider a polygonal region with vertices (0,0), (5,0), (10,5), (10,10), (0,10) and uniform density. Suppose we wanted to partition the region into 3 disjoint sub-regions with relative (weighted) areas 0.2, 0.5, and 0.3. To perform this operation using AreaCon, simply run the following code:

That's it!! The resulting partition and generators are then stored in Example_Partition.Covering and Example_Partition.Centers, respectively, and can be accessed using the Partition::GetCovering and Partition::GetCenters functions. A plot of the result is shown below:

Authors and Contributors

The AreaCon library's core components were written and developed by Jeffrey R. Peters (@jrpeters), with helpful insight from a variety of people including Amit Surana, William Sisson, Alexander Shilov, Grant Taylor, Terry Turpin, Rush Patel, and Francesco Bullo. The algorithms used by area-con are based primarily off of work by Rush Patel, Paolo Frasca, and Francesco Bullo (see References).

To report a bug, suggest a fix, or contribute to AreaCon, please do so via the GitHub page. Contributors are also encouraged to edit the project's Wiki , so as to build as comprehensive of a documentation as possible. Note that contributions can include usage examples or code-snippets that may be useful to other users.

Any issues, questions, or comments can also be sent directly to me via email, but please check the FAQ page and the Wiki first to make sure that the issue hasn't already been addressed. I also welcome any general comments or suggestions on how to improve the code, so feel free to pass those along.

Acknowledgments

AreaCon was originally developed as a part of a research effort sponsored by the U.S. Army Research Office and the Regents of the University of California, through Contract Number W911NF-09-D-0001 for the Institute for
Collaborative Biotechnologies, and that the content of the information does not necessarily reflect the position or the policy of the Government or the Regents of the University of California, and no official endorsement should be inferred.