https://github.com/duhaime/lloyd

Constrained Lloyd Iteration for distributing 2D points
https://github.com/duhaime/lloyd

data-visualization geometric-algorithms lloyd-iteration scatterplot

Last synced: 2 months ago
JSON representation

Constrained Lloyd Iteration for distributing 2D points

• Host: GitHub
• URL: https://github.com/duhaime/lloyd
• Owner: duhaime
• License: mit
• Created: 2018-09-29T18:07:34.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2021-06-08T01:06:34.000Z (over 3 years ago)
• Last Synced: 2024-09-18T06:51:07.396Z (3 months ago)
• Topics: data-visualization, geometric-algorithms, lloyd-iteration, scatterplot
• Language: Jupyter Notebook
• Homepage:
• Size: 3.25 MB
• Stars: 44
• Watchers: 3
• Forks: 4
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Lloyd's Algorithm

This package offers a Python implementation of Lloyd's algorithm, which can be used to distribute points in space. Using this algorithm, one can slightly rearrange points within a two-dimensional space in order to minimize the number of overlapping points while retaining the overall point distribution, which can greatly improve the usability of data visualizations.

## Background

[Lloyd iteration](https://en.wikipedia.org/wiki/Lloyd%27s_algorithm) is an algorithm for distributing points in a space. During each iteration, the algorithm builds a Voronoi diagram that places each point into a distinct cell, then centers each point within its cell. By running several iterations of the algorithm, one can distribute points more and more uniformly in space. The image below shows how Lloyd's algorithm distributes points in space:



## Usage

This package can be installed with pip:

```bash

pip install lloyd

```

After installing the package, one can transform the positions of points within a two-dimensional numpy array by building a model, calling the `lloyd.relax()` method on that model, then calling `lloyd.get_points()` to get the projected point positions:

```python

from lloyd import Field

import numpy as np

# generate 2000 observations with 2 dimensions

points = np.random.rand(2000, 2)

# create a lloyd model on which one can perform iterations

field = Field(points)

# run one iteration of Lloyd relaxation on the field of points

field.relax()

# get the resulting point positions

new_positions = field.get_points()

```

`new_positions` will then be a numpy array with the same shape as `points`, only the positions of each point will be shifted slightly so as to minimize the number of overlapping points. To continue pushing points farther from one another, one can simply call the `.relax()` method on the lloyd model.

## Visualizing Voronoi Maps

For examples of how to visualize the Voronoi maps created during each iteration of the model, see the attached notebook.

## Constrained Lloyd Iteration

Lloyd iteration is an unconstrained algorithm. During each iteration, Lloyd's algorithm constructs a new Voronoi diagram and then centers each point within its cell. This means that points near the convex hull (the outside boundary) of a distribution tend towards infinity as one continues to run Lloyd iterations.

To solve this problem, this module implements internal constraints that ensure points remain within the input point domain after the model iterates. This ensures points near the convex hull do not disappear into the abyss as one continues running iterations.