@insynergie/circlepacker

circlepacker
===

npm install circlepacker

what is it
---

!circlepacker demo

a typescript port of https://github.com/snorpey/circlepacker with the
webworker removed

how to use it
---

the easiest way to use this library is to create a CirclePacker instance and call its methods.

_please note_: circlepacker does not handle the rendering of circles. in merely calculates the circle positions.

reference
===

CirclePacker(options)

addCircles(circles), addCircle(circle), setBounds(bounds), setTarget(position), setCenteringPasses(number), setCollisionPasses(number), setDamping(number), update(), dragStart(circleId), drag(circleId, position), dragEnd(circleId), destroy()

CirclePacker(options)
---

returns a new circlepacker instance. it accepts the following options:

`javascript
var packerOptions = {
// the point that the circles should be attracted to
// REQUIRED
target: { x: 50, y: 50 },

// the bounds of the area we want to draw the circles in
// REQUIRED
bounds: { width: 100, height: 100 },

// the initial position and sizes of our circles
// it is possible to add more circles later
// each circle should have a unique id, a position and a radius
// REQUIRED
circles: [
{ id: 'circle1', radius: 34, position: { x: 32, y: 54 } },
{ id: 'circle2', radius: 64, position: { x: 24, y: 42 } },
{ id: 'circle3', radius: 53, position: { x: 23, y: 21 } }
],

// true: continuous animation loop
// false: one-time animation
// OPTIONAL. default: true
continuousMode: true,

// correctness of collision calculations.
// higher number means means longer time to calculate
// OPTIONAL
// default = 3
collisionPasses: 3,

// number of centering animations per frame.
// higher number means faster movement and longer time to calculate
// OPTIONAL
// default = 1
centeringPasses: 2,

// callback function for when movement started
// can get called multiple times
// OPTIONAL
onMoveStart: function () { },

// callback function for updated circle positions
onMove: function ( updatedCirclePositions ) {
// draw logic here...
},

// callback function for when movement ended
// can get called multiple times
// OPTIONAL
onMoveEnd: function () { }
};

var packer = new CirclePacker( packerOptions );
`

back to reference

addCircles(circles)
---

add an array of new circles. each _circle_ should have a unique id, a position and a radius.

`javascript
packer.addCircles( [
{ id: 'circle4', radius: 21, position: { x: 12, y: 27 } },
{ id: 'circle5', radius: 64, position: { x: 14, y: 42 } }
] );
`

back to reference

addCircle(circle)
---

add a single new circle. a _circle_ should have a unique id, a position and a radius.

`javascript
packer.addCircles( { id: 'circle6', radius: 21, position: { x: 12, y: 27 } } );
`

back to reference

setBounds(bounds)
---

update bounds. a _bounds_ object should have a width and a height.

`javascript
packer.setBounds( { width: 200, height: 300 } );
`

back to reference

setTarget(position)
---

updates the target position. a _position_ object should have x and y values.

`javascript
packer.setTarget( { x: 21, y: 29 } );
`

back to reference

setCenteringPasses(number)
---

updates number of centering passed. should an integer >= 1. high values can impact performance.

`javascript
packer.setCenteringPasses( 3 );
`

back to reference

setCollisionPasses(number)
---

updates number of collision passed. should an integer >= 1. high values can impact performance.

`javascript
packer.setCollisionPasses( 3 );
`

back to reference

setDamping(number)
---

set damping. this affects the movement speed of the circles. value should be a float between 0 and 1. the _default_ value is _0.025_

`javascript
packer.setDamping( 0.01 );
`

back to reference

update()
---

starts calculation. useful if continuousMode was set to false.

`javascript
packer.update();
`

back to reference

dragStart(circleId)
---

indicate that we're about to start dragging this circle. this is usually called in a mousedown or a touchstart event handler.

`javascript
packer.dragStart( 'circle2' );
`

back to reference

drag(circleId, position)
---

update position of dragges circle. a _position_ object should have x and y values. this is usually called in a mousemove or a touchmove event handler.

`javascript
packer.drag( 'circle2', { x: 30, y: 45 } );
`

back to reference

dragEnd(circleId)
---

indicate that we're done dragging this circle. . this is usually called in an mouseup or a touchend event handler.

`javascript
packer.dragEnd( 'circle2' );
`

back to reference

destroy()
---

tell circlepacker instance we're done and won't be needing it again. it terminates the webworker. useful for lifecycle hooks in single page web apps.

`javascript
packer.destroy();
``

back to reference

license
===

mit

credits
===

Mario Gonzalez <mariogonzalez@gmail.com>
Georg Fischer <snorpey@gmail.com>

large parts of the circle packing algirithm are based on the CirclePackingJS repo by @onedayitwillmake (mit licensed)