nhartland / forma

A Lua toolkit for computational geometry on a grid

forma

2D grid shape generation in Lua

forma is a utility library for the procedural generation and manipulation of shapes on a two dimensional grid or lattice. It came about as part of experiments in making roguelike games. forma is therefore particularly suited (but not limited) to the generation of roguelike environments.

Features

• A spatial-hashing pattern class for fast lookup of active cells.
• Pattern manipulators such as the addition, subtraction, rotation and reflection of patterns.
• Rasterisation algorithms for 2D primitives, e.g lines, circles, squares and Bezier curves.
• A very flexible cellular automata implementation with
  • Synchronous and asynchronous updates
  • Combination of multiple rule sets
• Pattern sampling algorithms including
  • Random (white noise) sampling
  • Perlin noise sampling
  • Poisson-disc sampling
  • Mitchell's best-candidate sampling
• Algorithms for subpattern finding including
  • Flood-fill contiguous segment finding
  • Convex hull finding
  • Pattern edge and surface finding
  • Binary space partitioning
  • Voronoi tessellation / Lloyd's algorithm

Results can be nested to produce complex patterns, and all of these methods are able to use custom distance measures and definitions of the cellular neighbourhood (e.g Moore, von Neumann).

Examples

• Example Gallery

-- Generate a square box to run the CA inside
local domain = primitives.square(80,20)

-- CA initial condition: 800-point random sample of the domain
local ca = subpattern.random(domain, 800)

-- Moore (8-cell) neighbourhood 4-5 rule
local moore = automata.rule(neighbourhood.moore(), "B5678/S45678")

-- Run the CA until converged or 1000 iterations
local ite, converged = 0, false
while converged == false and ite < 1000 do
    ca, converged = automata.iterate(ca, domain, {moore})
    ite = ite+1
end

-- Access a subpattern's cell coordinates for external use
for icell in ca:cells() do
    -- local foo = bar(icell)
    -- or
    -- local foo = bar(icell.x, icell.y)
end

-- Find all 4-contiguous segments of the CA pattern
-- Uses the von-neumann neighbourhood to determine 'connectedness'
-- but any custom neighbourhood can be used.
local segments = subpattern.segments(ca, neighbourhood.von_neumann())

-- Print a representation to io.output
subpattern.print_patterns(domain, segments)

Installation

forma is compatible with Lua 5.1, 5.2, 5.3 and LuaJIT 2.0, 2.1. The library is written in pure Lua, no compilation is required. Including the project is as simple as including the forma directory in your project or Lua path.

The easiest way to do this is via LuaRocks. To install the latest stable version use:

    luarocks install forma

Alternatively you can try the dev branch with:

    luarocks install --server=http://luarocks.org/dev forma

Documentation

Documentation is hosted here.

Generating the documentation requires

• LDoc

Simply running

ldoc --output contents --dir docs .

in the root directory should generate all the required pages.

Testing

Unit tests and coverage reports are provided. The test suite requires

• LuaCov
• luaunit

To run the tests use

./run_tests.sh

forma's Issues

Generate example gallery through GitHub Actions

This is currently a bit tedious and potentially easy to forget to do when releasing a new version.
Should be possible to do this in the same manner as the documentation is now built.

Checks failing with luaunit v3.4

Assertions on pattern equality through assertEquals that worked in v3.3 are failing in v3.4 of luaunit. This is despite the metamethod eq returning true for the failing cases. E.g

assertEquals(pattern1, pattern2) -- Fails
assertTrue(pattern1 == pattern2) -- Succeeds

Maybe luaunit is not properly handling the eq metamethod?

Tests for `pattern.packtile` and `pattern.packtile_centre`

Not currently covered by existing tests

Integrate test suite with LuaRocks 3

LuaRocks 3 now has some in-built test capacity.
It might be useful to include the test harness in the rockspec.