Merge pull request #21 from rhyolight/scale-offset-origin-restructure

More concrete ideas of scale and spacing

DESIGN.md

@@ -38,9 +38,81 @@ Data, either streaming or batched, that contains the state of the HTM system. Sh
 
 * * *
 
-# Proposed API
 
-To see the proposed API, build out the docs as described in the [README](README.md).
+# Configuring an HTM Network for Highbrow
+
+HTM Networks consiste of CorticalColumns, Layers, Neurons, and (sometimes) MiniColumns. HTM Networks can be defined in a configuration file, which is enough information to render the structures in 3D. The configuration is a JSON object that looks like this:
+
+```json
+{
+    name: "simple HtmNetwork",
+    origin: {x:0, y:0, z:0},
+    corticalColumns: [{
+        name: "CorticalColumn 1",
+        layers: [
+            {
+                name: "Layer 1",
+                miniColumns: false,
+                neuronCount: 100,
+                dimensions: {
+                    x: 10, y: 10, z: 1
+                }
+            }
+        ]
+    }]
+}
+```
+
+Each node in this tree represents a Renderable object. The top level is an HtmNetwork. It contains an array of `corticalColumns`. Each cortical column contains an array of `layers`.
+
+Layers must have dimensions. The dimensions of CorticalColumns and HtmNetworks are calculated from the layers.
+
+
+# Objects
+
+## Neuron
+
+Represents a pyramidal neuron. Neurons can be put into different states. Must be created with a `position` corresponding to its XYZ location in the layer cell grid. Neurons are created by their parent Layer objects.
+
+## Layer
+
+A collection of Neurons. They might just be in an array, or structured into MiniColumns (TODO). Layers have X, Y, and Z dimensions. The Y dimension will represent MiniColumns, if they exist. Because there may be less neurons in the structure than the dimension allows, a `neuronCount` must be provided in the layer config. Layer configuration looks like this:
+
+```json
+{
+    name: "layer 1",
+    miniColumns: false,
+    neuronCount: 100,
+    dimensions: {
+        x: 10, y: 10, z: 1
+    }
+}
+```
+
+## CorticalColumn
+
+A collection of Layers. Each Layer will be positioned below the proceeding Layer to align the configuration and the visualization with biological reality (input comes into the bottom, moves upward). Configuration:
+
+```json
+{
+    name: "column 1",
+    layers: [...]
+}
+```
+
+CorticalColumns are created by their parent HtmNetwork, and are assigned an origin point.
+
+## HtmNetwork
+
+An HtmNetwork is a collection of CorticalColumns. It must have an `origin` to be created.
+
+```json
+{
+    name: "one column, two layers",
+    origin: {x: 0, y: 0, z: 0},
+    corticalColumns: [...]
+}
+```
 
 * * *
 

README.md

@@ -2,7 +2,7 @@
 
 > HTM 3D Translation Library
 
-Currently under development, does not actually work yet. See design at [DESIGN](DESIGN.md) for motivation and notes. For more up-to-date architecture, build docs below.
+Currently under development. See design at [DESIGN](DESIGN.md) for motivation and notes. For more up-to-date architecture, build docs below.
 
 ## Install
 
@@ -21,13 +21,13 @@ Currently under development, does not actually work yet. See design at [DESIGN](
 
     npm run build
 
-Installs into `bin/highbrow.bundle.js`.
+Installs into `bin/highbrow-{X.Y.Z}.bundle.js`.
 
 ## Examples
 
 ### WEBGL
 
-There is a simple WEBGL example in [`examples/webgl`](examples/webgl/). This example interfaces with [cell-viz](https://github.com/numenta/cell-viz), an existing platform I've used for HTM cell rendering in THREE.JS. For details, see [`HighbrowLayerVisualization`](https://github.com/numenta/cell-viz/blob/master/src/HighbrowLayerVisualization.js). 
+There is a simple WEBGL example in [`examples/webgl`](examples/webgl/). This example interfaces with [cell-viz](https://github.com/numenta/cell-viz), an existing platform I've used for HTM cell rendering in THREE.JS. For details, see [`HighbrowLayerVisualization`](https://github.com/numenta/cell-viz/blob/master/src/HighbrowLayerVisualization.js).
 
 It currently only models one layer and is still missing key features, but if you open [`examples/webgl/index.html`](examples/webgl/index.html) in a browser and hold `s` to strafe backward you can see the animated cells with global indices and XYZ positions rendered upon them.