circleRepelLayout: Arranges circles by iterative pair-wise repulsion within a...
In mbedward/packcircles: Circle Packing

circleRepelLayout

R Documentation

Arranges circles by iterative pair-wise repulsion within a bounding rectangle

Description

This function takes a set of circles, defined by a data frame of initial centre positions and radii, and uses iterative pair-wise repulsion to try to find a non-overlapping arrangement where all circle centres lie inside a bounding rectangle. If no such arrangement can be found within the specified maximum number of iterations, the last attempt is returned.

Usage

circleRepelLayout(
  x,
  xlim,
  ylim,
  xysizecols = c(1, 2, 3),
  sizetype = c("area", "radius"),
  maxiter = 1000,
  wrap = TRUE,
  weights = 1
)

Arguments

`x`	Either a vector of circle sizes (areas or radii) or a matrix or data frame with a column of sizes and, optionally, columns for initial x-y coordinates of circle centres.
`xlim`	The bounds in the X direction; either a vector for [xmin, xmax) or a single value interpreted as [0, xmax). Alternatively, omitting this argument or passing any of `NULL`, a vector of `NA` or an empty vector will result in unbounded movement in the X direction.
`ylim`	The bounds in the Y direction; either a vector for [ymin, ymax) or a single value interpreted as [0, ymax). Alternatively, omitting this argument or passing any of `NULL`, a vector of `NA` or an empty vector will result in unbounded movement in the Y direction.
`xysizecols`	The integer indices or names of the columns in `x` for the centre x-y coordinates and sizes of circles. This argument is ignored if `x` is a vector. If `x` is a matrix or data frame but does not contain initial x-y coordinates, this can be indicated as `xysizecols = c(NA, NA, 1)` for example.
`sizetype`	The type of size values: either `"area"` or `"radius"`. May be abbreviated.
`maxiter`	The maximum number of iterations.
`wrap`	Whether to treat the bounding rectangle as a toroid (default `TRUE`). When this is in effect, a circle leaving the bounds on one side re-enters on the opposite side.
`weights`	An optional vector of numeric weights (0 to 1 inclusive) to apply to the distance each circle moves during pair-repulsion. A weight of 0 prevents any movement. A weight of 1 gives the default movement distance. A single value can be supplied for uniform weights. A vector with length less than the number of circles will be silently extended by repeating the final value. Any values outside the range [0, 1] will be clamped to 0 or 1.

Details

The algorithm is adapted from a demo written in the Processing language by Sean McCullough (this no longer seems to be available online). Each circle in the input data is compared to those following it. If two circles overlap, they are moved apart such that the distance moved by each is proportional to the radius of the other, loosely simulating inertia. So when a small circle is overlapped by a larger circle, the small circle moves furthest. This process is repeated until no more movement takes place (acceptable layout) or the maximum number of iterations is reached (layout failure).

To avoid edge effects, the bounding rectangle can be treated as a toroid by setting the wrap argument to TRUE. With this option, a circle moving outside the bounds re-enters at the opposite side.