@mtillmann/circlepacker

!CirclePacker

Simple circle-packing library based on Ken Goulding's gist and Kevin Dorff's png2svgcircles:

- removes jquery dependency
- uses modern javascript/typescript
- provides esm and umd builds
- helper functions for reading and writing images
- passes through original colors
- fix misc issues with original code

Usage

Install: npm install @mtillmann/circlepacker

Typically you'd use one of the from-functions to create an instance and then use one of the as-methods to render the circles to the format you need:

``javascript
import { fromCircle } from "@mtillmann/circlepacker";
document.body.appendChild((await fromCircle(200, 'red')).asSVG());
//or
fromCircle(200, 'red').then((instance) => {
document.body.appendChild(instance.asSVG());
})
`

The basic concept is to create an instance of CirclePacker and call the pack method with an ImageData object and the width of the image. The pack method will generate and return a list of packed circles for the given ImageData object.

The CirclePacker provides several helpers that return renderings of the packed circles.

> The pack-method always needs the width of the source image as the second argument to work correctly!

$3


`javascript
import { CirclePacker } from "@mtillmann/circlepacker";

const instance = new CirclePacker();
await instance.pack(imageData, imageWidth);
`


$3


`html

`

$3

`html


`

$3

When using node, you need to install canvas (npm install canvas@next), then either pass the CanvasRenderingContext2D object to the fromContext2D-function, use the fromCanvas-function or a CirclePacker-instance's pack method.

`javascript
import { fromCanvas, CirclePacker } from "@mtillmann/circlepacker";
import { createCanvas } from "canvas"

const canvas = createCanvas(200, 200)
const ctx = canvas.getContext('2d')
ctx.fillStyle = 'red'
ctx.fillRect(0, 0, 200, 200)

console.log((await fromCanvas(canvas)).asSVGString());
`
In node basically only asSVGString and asArray work. To create bitmaps, use
asArray to get the circles, then draw them with the canvas library.




$3


Options can be passed to the class constructor and to any of the from* functions as the last argument. The following options are available:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| spacing | number | 1 | Spacing of the circles |
| numCircles | number | 1000 | Number of circles to draw |
| minRadius | number | 1 | Minimum radius of the circles |
| maxRadius | number | 10 | Maximum radius of the circles |
| higherAccuracy | boolean | false | Use higher accuracy for circle packing |
| colors | string\|Array | 'auto' | If 'auto', the input ImageData's colors are used. If an array of colors is given, the given colors are used randomly |
| minAlpha | number | 1 | Minimum alpha value of input pixels to be considered. If the alpha value of a pixel is below this value, it is ignored |
| useMainThread | boolean | false | Use main thread for circle packing - disables Web Worker where available |
| reuseWorker | boolean | true | When set to false, the Worker instances are terminated after use |

$3

Export options can be passed to most of as* methods. The following options are available:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| scale | number | globalThis.devicePixelRatio || 1 | Scale of the output image - only useful for canvas and image renders. Default value prevents blurry images |
| quality | number | 1 | Quality float of the desired image format. Only works when Image is rendered. |
| format | string | 1 | Desired Format of rendered image |




Input Helpers

All input helpers are async functions that return a CirclePacker instance.

$3

Creates instance from blob data with given options.

$3

Creates instance from canvas element.

$3

Draws a circle with given radius and color, then creates instance from it.

$3

Creates instance from canvas context.

$3

Creates instance from image element.

$3

Creates an instance from given image data. Alias for new CirclePacker(imageData, imageWidth, options).render(imageData, imageWidth).

$3

Draws a rectangle with given width, height and color, then creates instance from it.

$3

Draws a square with given edge length and color, then creates instance from it.

$3

Fetches image from given url, then creates instance from it.

Output Helpers

Output helpers exist on the instance and can be called after the pack` method has been called.

$3

Returns a canvas element with the circles drawn on it.

$3

Returns an ImageData object with the circles drawn on it.

$3

Returns a blob of the image with the circles drawn on it. Supports Format and Quality options.

$3

Returns a blob url of the image with the circles drawn on it. Supports Format and Quality options.

$3

Returns a data url of the image with the circles drawn on it. Supports Format and Quality options.

$3

Returns an SVG node with the circles drawn on it.

$3

Returns an SVG string with the circles drawn on it.

$3

Returns an array of circle objects, basically a getter for the internal placedCircles array.