Merge pull request #10 from nhartland/dev

v0.3

CHANGELOG.md

@@ -2,10 +2,10 @@
 ---
 - Initial release
 
-0.2b
----------
+0.2
+---
 
-### Features
+# Features
 - Implemented a 'mask' subpattern that masks out cells according to a provided
   function
 - Added Voronoi relaxation via Lloyd's algorithm
@@ -16,23 +16,47 @@
 - Added a Poisson-disc sampling subpattern
 - Added Mitchell's Best-Candidate sampling (approximate Poisson-Disc)
 
-### Bugfix
+# Bugfix
 - Fixed bug with subpattern.enclosed which would generate more than one enclosed
   point for a primitive.circle
-- Fixed default initialisation of RNG in automata.async_iterate
+- Fixed default initialisation of RNG in `automata.async_iterate`
 
-### Misc
+# Misc
 - Improved circle raster (no longer repeats points)
 - Integrated all tests into a single test script, and added luacov coverage
 - Converted subpattern.random to take as an argument a fixed integer number of
   desired samples rather than a fraction of the domain size.
 - Removed special handling of '-0' coordinate in cell: No longer required with
   integer spatial hash in patterns.
-- Made pattern coordinate limits explicit in MAX_COORDINATE
+- Made pattern coordinate limits explicit in `MAX_COORDINATE`
 - Changed internal structure of `pattern`, from a list of cells to a list of
   coordinate hashes
 - Various optimisations
 - Removed some (confusing) functionality from `cell`, namely addition and
   multiplication with a number value.
 - Added isoline drawing example
-- Renamed pretty_print to print_patterns
+- Renamed `pretty_print` to `print_patterns`
+
+0.3
+---
+
+# Features
+- Pattern rotation operator
+- Shuffled version of `cell_coordinates` iterator
+- Generalised pattern prototype constructor to allow `NxM` matrices 
+
+# Bugfix
+- Fixed lazy initialisation through 'require ("forma")'
+- Corrected assert error message in pattern subtraction
+
+# Misc
+- Improved pattern documentation
+- Greatly expanded test coverage
+- Slightly streamlined corridors example
+- Much faster `subpattern.floodfill`
+- Much faster construction of neighbourhoods
+- Slightly faster pattern surface/enlarge/reflect
+- Slightly faster `subpattern.random`
+- Slightly faster convergence check for `automata.iterate`
+- Harmonised coordinate handling between pattern prototype and tostring
+

README.md

@@ -20,8 +20,7 @@ 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 addition, subtraction and reflection for the
-  generation of symmetrical patterns.
+- **Pattern manipulators** such as the addition, subtraction, rotation and reflection of patterns.
 - **Rasterisation algorithms** for 2D primitives, e.g lines, circles, squares.
 - A very flexible **cellular automata** implementation with
     - Synchronous and asynchronous updates
@@ -89,7 +88,7 @@ The easiest way to do this is via LuaRocks:
     luarocks install forma
 ```
 
-## Generating documentation
+## Documentation
 
 Documentation is hosted [here](https://nhartland.github.io/forma/).
 

config.ld

@@ -4,9 +4,11 @@ description = 'A 2D grid shape generation package'
 kind_names={topic='Readme'}
 format = 'markdown' 
 readme = 'README.md'
-examples = 'examples'
 not_luadoc = true
 
+examples = {'examples',
+             exclude = {'examples/README.md', 'examples/gallery.lua'}}
+
 file = {
         './forma/cell.lua',
         './forma/pattern.lua',

docs/contents.html

@@ -145,7 +145,7 @@ <h2>Examples</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/async_automata.lua.html

@@ -107,7 +107,7 @@ <h2>async_automata.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/binary_space_partition.lua.html

@@ -81,7 +81,7 @@ <h2>binary_space_partition.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/bubbles.lua.html

@@ -91,7 +91,7 @@ <h2>bubbles.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/cellular_automata.lua.html

@@ -94,7 +94,7 @@ <h2>cellular_automata.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/corridors.lua.html

@@ -70,40 +70,36 @@ <h2>corridors.lua</h2>
 </span><span class="comment">-- demonstrated. A asynchronous cellular automata with a complicated ruleset
 </span><span class="comment">-- generates an interesting 'corridor' like pattern.
 </span>
-<span class="keyword">local</span> pattern       = <span class="global">require</span>(<span class="string">'forma.pattern'</span>)
 <span class="keyword">local</span> primitives    = <span class="global">require</span>(<span class="string">'forma.primitives'</span>)
 <span class="keyword">local</span> automata      = <span class="global">require</span>(<span class="string">'forma.automata'</span>)
 <span class="keyword">local</span> subpattern    = <span class="global">require</span>(<span class="string">'forma.subpattern'</span>)
 <span class="keyword">local</span> neighbourhood = <span class="global">require</span>(<span class="string">'forma.neighbourhood'</span>)
 
-<span class="keyword">local</span> sq = primitives.square(<span class="number">80</span>,<span class="number">20</span>)
-<span class="keyword">local</span> seed = sq:rcell()
+<span class="comment">-- Generate a domain, and an initial state ca with one random seed cell
+</span><span class="keyword">local</span> domain = primitives.square(<span class="number">80</span>,<span class="number">20</span>)
+<span class="keyword">local</span> ca = subpattern.random(domain, <span class="number">1</span>)
 
-<span class="keyword">local</span> tp = pattern.new()
-tp:insert(seed.x, seed.y)
-
-<span class="comment">-- Complicated ruleset (leaving diag2 out provides a denser pattern)
+<span class="comment">-- Complicated ruleset, try leaving out or adding more rules
 </span><span class="keyword">local</span> moore = automata.rule(neighbourhood.moore(),      <span class="string">"B12/S012345678"</span>)
-<span class="keyword">local</span> diag  = automata.rule(neighbourhood.diagonal(),   <span class="string">"B0123/S01234"</span>)
-<span class="keyword">local</span> diag2 = automata.rule(neighbourhood.diagonal_2(), <span class="string">"B01/S01234"</span>)
+<span class="keyword">local</span> diag  = automata.rule(neighbourhood.diagonal_2(), <span class="string">"B01/S01234"</span>)
 <span class="keyword">local</span> vn    = automata.rule(neighbourhood.von_neumann(),<span class="string">"B12/S01234"</span>)
-<span class="keyword">local</span> ruleset = {diag2, diag, vn, moore}
+<span class="keyword">local</span> ruleset = {vn, moore, diag}
 
 <span class="keyword">repeat</span>
     <span class="keyword">local</span> converged
-    tp, converged = automata.async_iterate(tp, sq, ruleset)
+    ca, converged = automata.async_iterate(ca, domain, ruleset)
 <span class="keyword">until</span> converged
 
 <span class="keyword">local</span> nbh = neighbourhood.von_neumann()
-<span class="keyword">local</span> segments = subpattern.neighbourhood_categories(tp, nbh)
-subpattern.print_patterns(tp, segments, nbh:category_label())</pre>
+<span class="keyword">local</span> segments = subpattern.neighbourhood_categories(ca, nbh)
+subpattern.print_patterns(domain, segments, nbh:category_label())</pre>
 
 
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/isolines.lua.html

@@ -102,7 +102,7 @@ <h2>isolines.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/maxrectangle.lua.html

@@ -85,7 +85,7 @@ <h2>maxrectangle.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/readme.lua.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>forma Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>forma</h1>
+
+<ul>
+  <li><a href="../contents.html">Index</a></li>
+</ul>
+
+
+
+<h2>Examples</h2>
+<ul class="nowrap">
+  <li><a href="../examples/async_automata.lua.html">async_automata.lua</a></li>
+  <li><a href="../examples/binary_space_partition.lua.html">binary_space_partition.lua</a></li>
+  <li><a href="../examples/bubbles.lua.html">bubbles.lua</a></li>
+  <li><a href="../examples/cellular_automata.lua.html">cellular_automata.lua</a></li>
+  <li><a href="../examples/corridors.lua.html">corridors.lua</a></li>
+  <li><a href="../examples/isolines.lua.html">isolines.lua</a></li>
+  <li><a href="../examples/maxrectangle.lua.html">maxrectangle.lua</a></li>
+  <li><strong>readme.lua</strong></li>
+  <li><a href="../examples/sampling.lua.html">sampling.lua</a></li>
+  <li><a href="../examples/voronoi.lua.html">voronoi.lua</a></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../modules/forma.cell.html">forma.cell</a></li>
+  <li><a href="../modules/forma.pattern.html">forma.pattern</a></li>
+  <li><a href="../modules/forma.primitives.html">forma.primitives</a></li>
+  <li><a href="../modules/forma.subpattern.html">forma.subpattern</a></li>
+  <li><a href="../modules/forma.automata.html">forma.automata</a></li>
+  <li><a href="../modules/forma.neighbourhood.html">forma.neighbourhood</a></li>
+</ul>
+<h2>Readme</h2>
+<ul class="nowrap">
+  <li><a href="../readme/README.md.html">README</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+    <h2>readme.lua</h2>
+<pre>
+<span class="comment">-- Readme example
+</span><span class="comment">-- This generates the example used in the readme. Runs a 4-5 rule CA for 'cave
+</span><span class="comment">-- generation and then computes the contiguous sub-patterns and prints them.
+</span>
+<span class="comment">-- Load forma modules, lazy init is also available, i.e
+</span><span class="comment">-- require('forma')
+</span><span class="keyword">local</span> primitives    = <span class="global">require</span>(<span class="string">'forma.primitives'</span>)
+<span class="keyword">local</span> subpattern    = <span class="global">require</span>(<span class="string">'forma.subpattern'</span>)
+<span class="keyword">local</span> automata      = <span class="global">require</span>(<span class="string">'forma.automata'</span>)
+<span class="keyword">local</span> neighbourhood = <span class="global">require</span>(<span class="string">'forma.neighbourhood'</span>)
+
+<span class="comment">-- Generate a square box to run the CA inside
+</span><span class="keyword">local</span> domain = primitives.square(<span class="number">80</span>,<span class="number">20</span>)
+
+<span class="comment">-- CA initial condition: 800-point random sample of the domain
+</span><span class="keyword">local</span> ca = subpattern.random(domain, <span class="number">800</span>)
+
+<span class="comment">-- Moore (8-cell) neighbourhood 4-5 rule
+</span><span class="keyword">local</span> moore = automata.rule(neighbourhood.moore(), <span class="string">"B5678/S45678"</span>)
+
+<span class="comment">-- Run the CA until converged or 1000 iterations
+</span><span class="keyword">local</span> ite, converged = <span class="number">0</span>, <span class="keyword">false</span>
+<span class="keyword">while</span> converged == <span class="keyword">false</span> <span class="keyword">and</span> ite &lt; <span class="number">1000</span> <span class="keyword">do</span>
+    ca, converged = automata.iterate(ca, domain, {moore})
+    ite = ite+<span class="number">1</span>
+<span class="keyword">end</span>
+
+<span class="comment">-- Access a subpattern's cell coordinates for external use
+</span><span class="keyword">for</span> icell <span class="keyword">in</span> ca:cells() <span class="keyword">do</span>
+    <span class="comment">-- local foo = bar(icell)
+</span>    <span class="comment">-- or
+</span>    <span class="comment">-- local foo = bar(icell.x, icell.y)
+</span><span class="keyword">end</span>
+
+<span class="comment">-- Find all 4-contiguous segments of the CA pattern
+</span><span class="comment">-- Uses the von-neumann neighbourhood to determine 'connectedness'
+</span><span class="comment">-- but any custom neighbourhood can be used)
+</span><span class="keyword">local</span> segments = subpattern.segments(ca, neighbourhood.von_neumann())
+
+<span class="comment">-- Print a representation to io.output
+</span>subpattern.print_patterns(domain, segments)</pre>
+
+
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>

docs/examples/sampling.lua.html

@@ -93,7 +93,7 @@ <h2>sampling.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/examples/voronoi.lua.html

@@ -85,7 +85,7 @@ <h2>voronoi.lua</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/forma.automata.html

@@ -277,7 +277,7 @@ <h3>Usage:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/forma.cell.html

@@ -471,7 +471,7 @@ <h3>Usage:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2018-07-14 16:06:25 </i>
+<i style="float:right;">Last updated 2018-08-08 18:12:10 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>