Update documentation

docs/hsc/lua/geometry/blade.md

@@ -71,7 +71,7 @@ See [Blade fields](#blade-fields) for a full list.
 
 ### Vector methods
 
-Vectors support all the same methods as general [blades](#blade-methods). Additionally, they have the following method:
+Vectors have all the same methods as general [blades](#blade-methods). Additionally, they have the following method:
 
 - `:cross(other)` returns the 3D cross product between the vector and another vector `other`, ignoring components other than XYZ
 

docs/hsc/lua/geometry/hyperplane.md

@@ -1,11 +1,9 @@
 # Hyperplane
 
-A hyperplane is an oriented flat $(d-1)$-dimensional surface in $d$-dimensional space. The orientation of a hyperplane is determined by its normal vector; to flip a hyperplane's orientation, negate its normal vector.
+A **hyperplane** is an oriented flat $(d-1)$-dimensional surface in $d$-dimensional space. The orientation of a hyperplane is determined by its normal vector; to flip a hyperplane's orientation, negate its normal vector.
 
 Hyperplanes are also constructed automatically by functions that require them, so you can often omit the call to the constructor `plane()`.
 
-A **hyperplane** is an oriented flat $(d-1)$-dimensional surface in $d$-dimensional space.
-
 Hyperplanes cannot be mutated once [constructed](#constructors). To modify a hyperplane, you must construct a new hyperplane and then replace the old one.
 
 !!! info "The examples on this page assume 3D, but the same API works in other dimensions."
@@ -55,9 +53,18 @@ Hyperplanes have the following fields:
 - `.normal` is the (normalized) normal vector of the hyperplane
 - `.distance` is the minimum distance of the hyperplane from the origin
 - `.blade` is the [blade](blade.md) representing the hyperplane
+- `.region` is the [region](region.md) of space bounded on the side of the hyperplane facing away from the normal vector
 
 ## Methods
 
+Hyperplanes have the following methods:
+
+- [`:signed_distance()`](#hyperplanesigned_distance)
+
+### `hyperplane:signed_distance()`
+
+`hyperplane:signed_distance()` returns the signed distance of a point to a hyperplane. It takes one argument: a point. The distance returned is zero if the point is on the hyperplane, positive if the point is in the direction of the hyperplane's normal vector, or negative if the point is in the opposite direction.
+
 ## Operations
 
 Hyperplanes support the following operations:

docs/hsc/lua/geometry/orbit.md

@@ -16,10 +16,13 @@ Calling the `:orbit()` method on a [symmetry] with one or more [transformable] o
 - `.symmetry` is the symmetry used to construct the orbit
 - `.init` is a sequential table containing the elements used to construct the orbit
 - `.names` is a sequential table containing names assigned to elements using [`:named()`](#orbitnamed)
-- `.displays` is a sequential table containing display names assigned to elements using [`:named()`](#orbitnamed)
 
 ## Methods
 
+### `orbit:intersection()`
+
+See [`orbit:intersection()`](region.md#orbitintersection).
+
 ### `orbit:iter()`
 
 `orbit:iter()` returns a new identical orbit that can be used for iteration. Once an orbit has been iterated over in a `for` loop, it cannot be used again. See [Iteration](#iteration).
@@ -63,7 +66,11 @@ local named_orbit = sym:orbit(sym.oox.unit):named({
 })
 ```
 
-You should never write one of these tables by hand. There are many of them bundled with the default Lua files in Hyperspeedcube, and there will soon be a user interface for generating them.
+You should never write one of these tables by hand. There are many of them bundled with the default Lua files in Hyperspeedcube, and you can generate new ones using the **Developer Tools** window in Hyperspeedcube.
+
+### `orbit:union()`
+
+See [`orbit:union()`](region.md#orbitunion).
 
 ## Operations
 

docs/hsc/lua/geometry/region.md

@@ -0,0 +1,76 @@
+# Region
+
+A **region** is a subset of a [space](space.md) bounded by [hyperplanes](hyperplane.md). They are most commonly used to identify pieces.
+
+## Constructors
+
+### `axis()`
+
+Calling an axis as a function returns a region. It can be called in any of several ways:
+
+- **Single layer.** Calling an axis with a single layer index constructs a region bounding that layer.
+- **Two layers.** Calling an axis with two layer indices constructs a region bounding that layer range.
+- **Layer list.** Calling an axis with a sequential table of layer indices constructs a region bounding the union of all of those layers.
+- **Layer mask string.** Calling an axis with a layer mask string constructs a region bounding the union of the layers specified by the string. If the string is a single asterisk `*` then all layers are included.
+
+```lua title="Examples using axis()"
+-- Add 2 axes, each with 5 layers.
+self.axes:add(vec('x'), {1/2, 1/4, 0, -1/2, -1/4})
+self.axes:add(vec('y'), {1/2, 1/4, 0, -1/2, -1/4})
+self.axes:autoname()
+
+local region1 = self.axes.A(1) -- first layer of axis A
+local region2 = self.axes.B('*') -- all 3 layers of axis B
+local region3 = self.axes.B(1, 3) -- layers 1 to 3 of axis B
+local region4 = self.axes.A({1, 3, 5}) -- layers 1, 3, and 5 of axis A
+local region5 = self.axes.A('1..-2') -- layers 1 to 4 of axis A
+```
+
+### `hyperplane.region`
+
+`hyperplane.region` returns the region bounded by a hyperplane, on the side its normal vector is pointing _away_ from.
+
+```lua title="Examples of hyperplane.region"
+local region1 = plane('x').region -- X <= 1
+local region2 = plane('x').flip.region -- X >= 1
+local region3 = ~plane('x').region -- X >= 1
+```
+
+### `orbit:intersection()`
+
+`orbit:intersection()` returns the intersection of all regions in an orbit. Each element of the orbit must be a single region. Names are ignored.
+
+```lua title="Examples of orbit:intersection()"
+-- region inside a unit cube
+local region1 = cd'bc3':orbit(plane('x').region):intersection()
+```
+
+### `orbit:union()`
+
+`orbit:union()` returns the union of all regions in an orbit. Each element of the orbit must be a single region. Names are ignored.
+
+```lua title="Examples of orbit:union()"
+-- region outside a unit cube
+local region1 = cd'bc3':orbit(plane('x').flip.region):union()
+```
+
+## Fields
+
+Regions have no fields.
+
+## Methods
+
+Regions have the following methods:
+
+- `:contains(point)` returns whether the region contains a point
+
+## Operations
+
+Regions support the following operations:
+
+- `region & region` (intersection)
+- `region | region` (union)
+- `region ~ region` (symmetric difference)
+- `~region` (complement)
+- `type(region)` returns `'region'`
+- `tostring(region)`

mkdocs.yml

@@ -86,12 +86,13 @@ nav:
       - hsc/lua/puzzle-library.md
       - hsc/lua/color-system-library.md
       - Geometry:
+        - hsc/lua/geometry/space.md
         - hsc/lua/geometry/blade.md
         - hsc/lua/geometry/hyperplane.md
         - hsc/lua/geometry/transform.md
         - hsc/lua/geometry/symmetry.md
         - hsc/lua/geometry/orbit.md
-        - hsc/lua/geometry/space.md
+        - hsc/lua/geometry/region.md
       - Puzzle construction:
         - hsc/lua/puzzle-construction/puzzle.md
         - hsc/lua/puzzle-construction/colors.md