Ready for first push to github; some documentation written.

.gitignore

@@ -10,3 +10,7 @@ pom.xml.asc
 /.nrepl-port
 .hgignore
 .hg/
+
+resources/isle_of_man.svg
+
+resources/small_hill.svg

README.md

@@ -4,15 +4,112 @@ A Clojure library designed to assist in computing walkmaps for games.
 
 ## Introduction
 
-This library is written in support of work on [The Great Game](), but is separate because it may be of some use in other settings.
+This library is written in support of work on
+[The Great Game](https://simon-brooke.github.io/the-great-game/codox/), but is
+separate because it may be of some use in other settings.
 
 ## Usage
 
-Doesn't work yet
+What works:
+
+No clojars repo yet, build the jar yourself with
+
+    lein install
+
+Lein dependency:
+
+    [walkmap "0.1.0-SNAPSHOT"]
+
+Using:
+
+    (require '[walkmap.core :refer :all])
+
+### Converting heightmaps to STL
+
+Doesn't work yet, and is not a priority. Use
+[hmm](https://github.com/fogleman/hmm) instead.
+
+### Reading binary STL files
+
+    (decode-binary-stl "path/to/input-file.stl")
+
+Works, seems good.
+
+### Writing ASCII STL files
+
+    (write-ascii-stl "path/to/output-file.ascii.stl" stl-structure)
+
+Works, seems good, agrees with Python implementation except for different
+number of places of decimals printed.
+
+### Converting STL to SVG
+
+    (stl-to-svg stl-structure)
+
+Works for smaller test files. I'm not yet confident it works for arbitrary
+sized STL structures. Returns a [Dali](https://github.com/stathissideris/dali)
+structure representing an SVG drawing, which can be printed with
+
+    (dali.io/render-svg structure)
+
+**NOTE THAT** the SVG data does not contain height information, which the
+STL data does contain. Thus gradient information can only be obtained from
+the STL.
+
+### Converting STL file to SVG or SVG file
+
+    (binary-stl-file-to-svg "path/to/input-file.stl")
+
+Works for smaller test files. I'm not yet confident it works for arbitrary
+sized STL structures. Returns a [Dali](https://github.com/stathissideris/dali)
+structure representing an SVG drawing, as above.
+
+    (binary-stl-file-to-svg "path/to/input-file.stl" "path-to-output-file.svg")
+
+As above, but, as a side effect, writes the SVG to the specified output file.
+Works for smaller test files, as above.
+
+### Merging exclusion maps and reserved area maps
+
+It is intended that it should be possible to merge exclusion maps (maps of
+areas which should be excluded from the traversable area) with maps derived
+from height maps. These exclusion maps will probably be represented as SVG.
+
+This is not yet implemented.
+
+### Merging road maps and river system maps
+
+It is intended that it should be possible to merge road maps (maps of already
+computed routes) with maps derived from height maps. These exclusion maps will
+probably be represented as SVG. This is not yet implemented.
+
+River system maps are conceptually similar to road maps; this too is not yet
+implemented.
+
+### Computing new routes and roads
+
+It is intended that it should be possible, by simulating agents traversing the
+terrain, to compute the courses of new roads/tracks/paths. The routing
+algorithm should implement the following rules.
+
+1. No route may pass through any part of a reserved holding, except the holding which is its origin, if any, and the holding which is its destination (and in any case we won't render paths or roads within holdings, although traversal information may be used to determine whether a holding, or part of it, is paved/cobbled;
+2. No route may pass through any building, with the exception of a city gate;
+3. We don't have bicycles: going uphill costs work, and you don't get that cost back on the down hill. Indeed, downhills are at least as expensive to traverse as flat ground;
+4. Any existing route segment costs only a third as much to traverse as open ground having the same gradient;
+5. A more used route costs less to traverse than a less used route;
+6. There is a significant cost penalty to crossing a watercourse, except at an existing crossing.
+
+This is not yet implemented.
+
+### Writing out computed road maps as SVG
+
+It is intended that, after computing new routes and roads, it should be
+possible to expoer an updated road map as SVG. This is not yet implemented.
+
 
 ## License
 
-Copyright © 2020 FIXME
+Copyright © 2020 Simon Brooke
 
 This program and the accompanying materials are made available under the
 terms of the Eclipse Public License 2.0 which is available at

doc/intro.md

@@ -1,3 +1,122 @@
 # Introduction to walkmap
 
-TODO: write [great documentation](http://jacobian.org/writing/what-to-write/)
+## Introduction
+
+This library is written in support of work on
+[The Great Game](https://simon-brooke.github.io/the-great-game/codox/), but is
+separate because it may be of some use in other settings.
+
+## Usage
+
+What works:
+
+No clojars repo yet, build the jar yourself with
+
+    lein install
+
+Lein dependency:
+
+    [walkmap "0.1.0-SNAPSHOT"]
+
+Using:
+
+    (require '[walkmap.core :refer :all])
+
+### Converting heightmaps to STL
+
+Doesn't work yet, and is not a priority. Use
+[hmm](https://github.com/fogleman/hmm) instead.
+
+### Reading binary STL files
+
+    (decode-binary-stl "path/to/input-file.stl")
+
+Works, seems good.
+
+### Writing ASCII STL files
+
+    (write-ascii-stl "path/to/output-file.ascii.stl" stl-structure)
+
+Works, seems good, agrees with Python implementation except for different
+number of places of decimals printed.
+
+### Converting STL to SVG
+
+    (stl-to-svg stl-structure)
+
+Works for smaller test files. I'm not yet confident it works for arbitrary
+sized STL structures. Returns a [Dali](https://github.com/stathissideris/dali)
+structure representing an SVG drawing, which can be printed with
+
+    (dali.io/render-svg structure)
+
+**NOTE THAT** the SVG data does not contain height information, which the
+STL data does contain. Thus gradient information can only be obtained from
+the STL.
+
+### Converting STL file to SVG or SVG file
+
+    (binary-stl-file-to-svg "path/to/input-file.stl")
+
+Works for smaller test files. I'm not yet confident it works for arbitrary
+sized STL structures. Returns a [Dali](https://github.com/stathissideris/dali)
+structure representing an SVG drawing, as above.
+
+    (binary-stl-file-to-svg "path/to/input-file.stl" "path-to-output-file.svg")
+
+As above, but, as a side effect, writes the SVG to the specified output file.
+Works for smaller test files, as above.
+
+### Merging exclusion maps and reserved area maps
+
+It is intended that it should be possible to merge exclusion maps (maps of
+areas which should be excluded from the traversable area) with maps derived
+from height maps. These exclusion maps will probably be represented as SVG.
+
+This is not yet implemented.
+
+### Merging road maps and river system maps
+
+It is intended that it should be possible to merge road maps (maps of already
+computed routes) with maps derived from height maps. These exclusion maps will
+probably be represented as SVG. This is not yet implemented.
+
+River system maps are conceptually similar to road maps; this too is not yet
+implemented.
+
+### Computing new routes and roads
+
+It is intended that it should be possible, by simulating agents traversing the
+terrain, to compute the courses of new roads/tracks/paths. The routing
+algorithm should implement the following rules.
+
+1. No route may pass through any part of a reserved holding, except the holding which is its origin, if any, and the holding which is its destination (and in any case we won't render paths or roads within holdings, although traversal information may be used to determine whether a holding, or part of it, is paved/cobbled;
+2. No route may pass through any building, with the exception of a city gate;
+3. We don't have bicycles: going uphill costs work, and you don't get that cost back on the down hill. Indeed, downhills are at least as expensive to traverse as flat ground;
+4. Any existing route segment costs only a third as much to traverse as open ground having the same gradient;
+5. A more used route costs less to traverse than a less used route;
+6. There is a significant cost penalty to crossing a watercourse, except at an existing crossing.
+
+This is not yet implemented.
+
+### Writing out computed road maps as SVG
+
+It is intended that, after computing new routes and roads, it should be
+possible to expoer an updated road map as SVG. This is not yet implemented.
+
+
+## License
+
+Copyright © 2020 Simon Brooke
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0.
+
+This Source Code may also be made available under the following Secondary
+Licenses when the conditions for such availability set forth in the Eclipse
+Public License, v. 2.0 are satisfied: GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or (at your
+option) any later version, with the GNU Classpath Exception which is available
+at https://www.gnu.org/software/classpath/license.html.
+

docs/codox/css/default.css

@@ -0,0 +1,551 @@
+body {
+    font-family: Helvetica, Arial, sans-serif;
+    font-size: 15px;
+}
+
+pre, code {
+    font-family: Monaco, DejaVu Sans Mono, Consolas, monospace;
+    font-size: 9pt;
+    margin: 15px 0;
+}
+
+h1 {
+    font-weight: normal;
+    font-size: 29px;
+    margin: 10px 0 2px 0;
+    padding: 0;
+}
+
+h2 {
+    font-weight: normal;
+    font-size: 25px;
+}
+
+h5.license {
+    margin: 9px 0 22px 0;
+    color: #555;
+    font-weight: normal;
+    font-size: 12px;
+    font-style: italic;
+}
+
+.document h1, .namespace-index h1 {
+    font-size: 32px;
+    margin-top: 12px;
+}
+
+#header, #content, .sidebar {
+    position: fixed;
+}
+
+#header {
+    top: 0;
+    left: 0;
+    right: 0;
+    height: 22px;
+    color: #f5f5f5;
+    padding: 5px 7px;
+}
+
+#content {
+    top: 32px;
+    right: 0;
+    bottom: 0;
+    overflow: auto;
+    background: #fff;
+    color: #333;
+    padding: 0 18px;
+}
+
+.sidebar {
+    position: fixed;
+    top: 32px;
+    bottom: 0;
+    overflow: auto;
+}
+
+.sidebar.primary {
+    background: #e2e2e2;
+    border-right: solid 1px #cccccc;
+    left: 0;
+    width: 250px;
+}
+
+.sidebar.secondary {
+    background: #f2f2f2;
+    border-right: solid 1px #d7d7d7;
+    left: 251px;
+    width: 200px;
+}
+
+#content.namespace-index, #content.document {
+    left: 251px;
+}
+
+#content.namespace-docs {
+    left: 452px;
+}
+
+#content.document {
+    padding-bottom: 10%;
+}
+
+#header {
+    background: #3f3f3f;
+    box-shadow: 0 0 8px rgba(0, 0, 0, 0.4);
+    z-index: 100;
+}
+
+#header h1 {
+    margin: 0;
+    padding: 0;
+    font-size: 18px;
+    font-weight: lighter;
+    text-shadow: -1px -1px 0px #333;
+}
+
+#header h1 .project-version {
+    font-weight: normal;
+}
+
+.project-version {
+    padding-left: 0.15em;
+}
+
+#header a, .sidebar a {
+    display: block;
+    text-decoration: none;
+}
+
+#header a {
+    color: #f5f5f5;
+}
+
+.sidebar a {
+    color: #333;
+}
+
+#header h2 {
+    float: right;
+    font-size: 9pt;
+    font-weight: normal;
+    margin: 4px 3px;
+    padding: 0;
+    color: #bbb;
+}
+
+#header h2 a {
+    display: inline;
+}
+
+.sidebar h3 {
+    margin: 0;
+    padding: 10px 13px 0 13px;
+    font-size: 19px;
+    font-weight: lighter;
+}
+
+.sidebar h3 a {
+    color: #444;
+}
+
+.sidebar h3.no-link {
+    color: #636363;
+}
+
+.sidebar ul {
+    padding: 7px 0 6px 0;
+    margin: 0;
+}
+
+.sidebar ul.index-link {
+    padding-bottom: 4px;
+}
+
+.sidebar li {
+    display: block;
+    vertical-align: middle;
+}
+
+.sidebar li a, .sidebar li .no-link {
+    border-left: 3px solid transparent;
+    padding: 0 10px;
+    white-space: nowrap;
+}
+
+.sidebar li .no-link {
+    display: block;
+    color: #777;
+    font-style: italic;
+}
+
+.sidebar li .inner {
+    display: inline-block;
+    padding-top: 7px;
+    height: 24px;
+}
+
+.sidebar li a, .sidebar li .tree {
+    height: 31px;
+}
+
+.depth-1 .inner { padding-left: 2px; }
+.depth-2 .inner { padding-left: 6px; }
+.depth-3 .inner { padding-left: 20px; }
+.depth-4 .inner { padding-left: 34px; }
+.depth-5 .inner { padding-left: 48px; }
+.depth-6 .inner { padding-left: 62px; }
+
+.sidebar li .tree {
+    display: block;
+    float: left;
+    position: relative;
+    top: -10px;
+    margin: 0 4px 0 0;
+    padding: 0;
+}
+
+.sidebar li.depth-1 .tree {
+    display: none;
+}
+
+.sidebar li .tree .top, .sidebar li .tree .bottom {
+    display: block;
+    margin: 0;
+    padding: 0;
+    width: 7px;
+}
+
+.sidebar li .tree .top {
+    border-left: 1px solid #aaa;
+    border-bottom: 1px solid #aaa;
+    height: 19px;
+}
+
+.sidebar li .tree .bottom {
+    height: 22px;
+}
+
+.sidebar li.branch .tree .bottom {
+    border-left: 1px solid #aaa;
+}
+
+.sidebar.primary li.current a {
+    border-left: 3px solid #a33;
+    color: #a33;
+}
+
+.sidebar.secondary li.current a {
+    border-left: 3px solid #33a;
+    color: #33a;
+}
+
+.namespace-index h2 {
+    margin: 30px 0 0 0;
+}
+
+.namespace-index h3 {
+    font-size: 16px;
+    font-weight: bold;
+    margin-bottom: 0;
+}
+
+.namespace-index .topics {
+    padding-left: 30px;
+    margin: 11px 0 0 0;
+}
+
+.namespace-index .topics li {
+    padding: 5px 0;
+}
+
+.namespace-docs h3 {
+    font-size: 18px;
+    font-weight: bold;
+}
+
+.public h3 {
+    margin: 0;
+    float: left;
+}
+
+.usage {
+    clear: both;
+}
+
+.public {
+    margin: 0;
+    border-top: 1px solid #e0e0e0;
+    padding-top: 14px;
+    padding-bottom: 6px;
+}
+
+.public:last-child {
+    margin-bottom: 20%;
+}
+
+.members .public:last-child {
+    margin-bottom: 0;
+}
+
+.members {
+    margin: 15px 0;
+}
+
+.members h4 {
+    color: #555;
+    font-weight: normal;
+    font-variant: small-caps;
+    margin: 0 0 5px 0;
+}
+
+.members .inner {
+    padding-top: 5px;
+    padding-left: 12px;
+    margin-top: 2px;
+    margin-left: 7px;
+    border-left: 1px solid #bbb;
+}
+
+#content .members .inner h3 {
+    font-size: 12pt;
+}
+
+.members .public {
+    border-top: none;
+    margin-top: 0;
+    padding-top: 6px;
+    padding-bottom: 0;
+}
+
+.members .public:first-child {
+    padding-top: 0;
+}
+
+h4.type,
+h4.dynamic,
+h4.added,
+h4.deprecated {
+    float: left;
+    margin: 3px 10px 15px 0;
+    font-size: 15px;
+    font-weight: bold;
+    font-variant: small-caps;
+}
+
+.public h4.type,
+.public h4.dynamic,
+.public h4.added,
+.public h4.deprecated {
+    font-size: 13px;
+    font-weight: bold;
+    margin: 3px 0 0 10px;
+}
+
+.members h4.type,
+.members h4.added,
+.members h4.deprecated {
+    margin-top: 1px;
+}
+
+h4.type {
+    color: #717171;
+}
+
+h4.dynamic {
+    color: #9933aa;
+}
+
+h4.added {
+    color: #508820;
+}
+
+h4.deprecated {
+    color: #880000;
+}
+
+.namespace {
+    margin-bottom: 30px;
+}
+
+.namespace:last-child {
+    margin-bottom: 10%;
+}
+
+.index {
+    padding: 0;
+    font-size: 80%;
+    margin: 15px 0;
+    line-height: 16px;
+}
+
+.index * {
+    display: inline;
+}
+
+.index p {
+    padding-right: 3px;
+}
+
+.index li {
+    padding-right: 5px;
+}
+
+.index ul {
+    padding-left: 0;
+}
+
+.type-sig {
+    clear: both;
+    color: #088;
+}
+
+.type-sig pre {
+    padding-top: 10px;
+    margin: 0;
+}
+
+.usage code {
+    display: block;
+    color: #008;
+    margin: 2px 0;
+}
+
+.usage code:first-child {
+    padding-top: 10px;
+}
+
+p {
+    margin: 15px 0;
+}
+
+.public p:first-child, .public pre.plaintext {
+    margin-top: 12px;
+}
+
+.doc {
+    margin: 0 0 26px 0;
+    clear: both;
+}
+
+.public .doc {
+    margin: 0;
+}
+
+.namespace-index .doc {
+    margin-bottom: 20px;
+}
+
+.namespace-index .namespace .doc {
+    margin-bottom: 10px;
+}
+
+.markdown p, .markdown li, .markdown dt, .markdown dd, .markdown td {
+    line-height: 22px;
+}
+
+.markdown li {
+    padding: 2px 0;
+}
+
+.markdown h2 {
+    font-weight: normal;
+    font-size: 25px;
+    margin: 30px 0 10px 0;
+}
+
+.markdown h3 {
+    font-weight: normal;
+    font-size: 20px;
+    margin: 30px 0 0 0;
+}
+
+.markdown h4 {
+    font-size: 15px;
+    margin: 22px 0 -4px 0;
+}
+
+.doc, .public, .namespace .index {
+    max-width: 680px;
+    overflow-x: visible;
+}
+
+.markdown pre > code {
+    display: block;
+    padding: 10px;
+}
+
+.markdown pre > code, .src-link a {
+    border: 1px solid #e4e4e4;
+    border-radius: 2px;
+}
+
+.markdown code:not(.hljs), .src-link a {
+    background: #f6f6f6;
+}
+
+pre.deps {
+    display: inline-block;
+    margin: 0 10px;
+    border: 1px solid #e4e4e4;
+    border-radius: 2px;
+    padding: 10px;
+    background-color: #f6f6f6;
+}
+
+.markdown hr {
+    border-style: solid;
+    border-top: none;
+    color: #ccc;
+}
+
+.doc ul, .doc ol {
+    padding-left: 30px;
+}
+
+.doc table {
+    border-collapse: collapse;
+    margin: 0 10px;
+}
+
+.doc table td, .doc table th {
+    border: 1px solid #dddddd;
+    padding: 4px 6px;
+}
+
+.doc table th {
+    background: #f2f2f2;
+}
+
+.doc dl {
+    margin: 0 10px 20px 10px;
+}
+
+.doc dl dt {
+    font-weight: bold;
+    margin: 0;
+    padding: 3px 0;
+    border-bottom: 1px solid #ddd;
+}
+
+.doc dl dd {
+    padding: 5px 0;
+    margin: 0 0 5px 10px;
+}
+
+.doc abbr {
+    border-bottom: 1px dotted #333;
+    font-variant: none;
+    cursor: help;
+}
+
+.src-link {
+    margin-bottom: 15px;
+}
+
+.src-link a {
+    font-size: 70%;
+    padding: 1px 4px;
+    text-decoration: none;
+    color: #5555bb;
+}

docs/codox/css/highlight.css

@@ -0,0 +1,97 @@
+/*
+github.com style (c) Vasily Polovnyov <vast@whiteants.net>
+*/
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 0.5em;
+  color: #333;
+  background: #f8f8f8;
+}
+
+.hljs-comment,
+.hljs-quote {
+  color: #998;
+  font-style: italic;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-subst {
+  color: #333;
+  font-weight: bold;
+}
+
+.hljs-number,
+.hljs-literal,
+.hljs-variable,
+.hljs-template-variable,
+.hljs-tag .hljs-attr {
+  color: #008080;
+}
+
+.hljs-string,
+.hljs-doctag {
+  color: #d14;
+}
+
+.hljs-title,
+.hljs-section,
+.hljs-selector-id {
+  color: #900;
+  font-weight: bold;
+}
+
+.hljs-subst {
+  font-weight: normal;
+}
+
+.hljs-type,
+.hljs-class .hljs-title {
+  color: #458;
+  font-weight: bold;
+}
+
+.hljs-tag,
+.hljs-name,
+.hljs-attribute {
+  color: #000080;
+  font-weight: normal;
+}
+
+.hljs-regexp,
+.hljs-link {
+  color: #009926;
+}
+
+.hljs-symbol,
+.hljs-bullet {
+  color: #990073;
+}
+
+.hljs-built_in,
+.hljs-builtin-name {
+  color: #0086b3;
+}
+
+.hljs-meta {
+  color: #999;
+  font-weight: bold;
+}
+
+.hljs-deletion {
+  background: #fdd;
+}
+
+.hljs-addition {
+  background: #dfd;
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: bold;
+}

docs/codox/index.html

@@ -0,0 +1,3 @@
+<!DOCTYPE html PUBLIC ""
+    "">
+<html><head><meta charset="UTF-8" /><title>Walkmap 0.1.0-SNAPSHOT</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Walkmap</span> <span class="project-version">0.1.0-SNAPSHOT</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 current"><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="intro.html"><div class="inner"><span>Introduction to walkmap</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1 "><a href="walkmap.core.html"><div class="inner"><span>walkmap.core</span></div></a></li></ul></div><div class="namespace-index" id="content"><h1><span class="project-title"><span class="project-name">Walkmap</span> <span class="project-version">0.1.0-SNAPSHOT</span></span></h1><h5 class="license">Released under the <a href="https://www.eclipse.org/legal/epl-2.0/">EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0</a></h5><div class="doc"><p>A Clojure library designed to assist in computing walkmaps for games.</p></div><h2>Installation</h2><p>To install, add the following dependency to your project or build file:</p><pre class="deps">[walkmap "0.1.0-SNAPSHOT"]</pre><h2>Topics</h2><ul class="topics"><li><a href="intro.html">Introduction to walkmap</a></li></ul><h2>Namespaces</h2><div class="namespace"><h3><a href="walkmap.core.html">walkmap.core</a></h3><div class="doc"><div class="markdown"><p>At this stage, primarily utility functions dealing with stereolithography (STL) files. Not a stable API yet!</p></div></div><div class="index"><p>Public variables and functions:</p><ul><li> <a href="walkmap.core.html#var-binary-stl">binary-stl</a> </li><li> <a href="walkmap.core.html#var-binary-stl-file-to-svg">binary-stl-file-to-svg</a> </li><li> <a href="walkmap.core.html#var-binary-stl-to-ascii">binary-stl-to-ascii</a> </li><li> <a href="walkmap.core.html#var-decode-binary-stl">decode-binary-stl</a> </li><li> <a href="walkmap.core.html#var-facet">facet</a> </li><li> <a href="walkmap.core.html#var-stl-to-svg">stl-to-svg</a> </li><li> <a href="walkmap.core.html#var-vect">vect</a> </li><li> <a href="walkmap.core.html#var-write-ascii-stl">write-ascii-stl</a> </li></ul></div></div></div></body></html>

docs/codox/intro.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html PUBLIC ""
+    "">
+<html><head><meta charset="UTF-8" /><title>Introduction to walkmap</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Walkmap</span> <span class="project-version">0.1.0-SNAPSHOT</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1  current"><a href="intro.html"><div class="inner"><span>Introduction to walkmap</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1 "><a href="walkmap.core.html"><div class="inner"><span>walkmap.core</span></div></a></li></ul></div><div class="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#introduction-to-walkmap" name="introduction-to-walkmap"></a>Introduction to walkmap</h1>
+<h2><a href="#introduction" name="introduction"></a>Introduction</h2>
+<p>This library is written in support of work on <a href="https://simon-brooke.github.io/the-great-game/codox/">The Great Game</a>, but is separate because it may be of some use in other settings.</p>
+<h2><a href="#usage" name="usage"></a>Usage</h2>
+<p>What works:</p>
+<p>No clojars repo yet, build the jar yourself with</p>
+<pre><code>lein install
+</code></pre>
+<p>Lein dependency:</p>
+<pre><code>[walkmap "0.1.0-SNAPSHOT"]
+</code></pre>
+<p>Using:</p>
+<pre><code>(require '[walkmap.core :refer :all])
+</code></pre>
+<h3><a href="#converting-heightmaps-to-stl" name="converting-heightmaps-to-stl"></a>Converting heightmaps to STL</h3>
+<p>Doesn’t work yet, and is not a priority. Use <a href="https://github.com/fogleman/hmm">hmm</a> instead.</p>
+<h3><a href="#reading-binary-stl-files" name="reading-binary-stl-files"></a>Reading binary STL files</h3>
+<pre><code>(decode-binary-stl "path/to/input-file.stl")
+</code></pre>
+<p>Works, seems good.</p>
+<h3><a href="#writing-ascii-stl-files" name="writing-ascii-stl-files"></a>Writing ASCII STL files</h3>
+<pre><code>(write-ascii-stl "path/to/output-file.ascii.stl" stl-structure)
+</code></pre>
+<p>Works, seems good, agrees with Python implementation except for different number of places of decimals printed.</p>
+<h3><a href="#converting-stl-to-svg" name="converting-stl-to-svg"></a>Converting STL to SVG</h3>
+<pre><code>(stl-to-svg stl-structure)
+</code></pre>
+<p>Works for smaller test files. I’m not yet confident it works for arbitrary sized STL structures. Returns a <a href="https://github.com/stathissideris/dali">Dali</a> structure representing an SVG drawing, which can be printed with</p>
+<pre><code>(dali.io/render-svg structure)
+</code></pre>
+<p><strong>NOTE THAT</strong> the SVG data does not contain height information, which the STL data does contain. Thus gradient information can only be obtained from the STL.</p>
+<h3><a href="#converting-stl-file-to-svg-or-svg-file" name="converting-stl-file-to-svg-or-svg-file"></a>Converting STL file to SVG or SVG file</h3>
+<pre><code>(binary-stl-file-to-svg "path/to/input-file.stl")
+</code></pre>
+<p>Works for smaller test files. I’m not yet confident it works for arbitrary sized STL structures. Returns a <a href="https://github.com/stathissideris/dali">Dali</a> structure representing an SVG drawing, as above.</p>
+<pre><code>(binary-stl-file-to-svg "path/to/input-file.stl" "path-to-output-file.svg")
+</code></pre>
+<p>As above, but, as a side effect, writes the SVG to the specified output file. Works for smaller test files, as above.</p>
+<h3><a href="#merging-exclusion-maps-and-reserved-area-maps" name="merging-exclusion-maps-and-reserved-area-maps"></a>Merging exclusion maps and reserved area maps</h3>
+<p>It is intended that it should be possible to merge exclusion maps (maps of areas which should be excluded from the traversable area) with maps derived from height maps. These exclusion maps will probably be represented as SVG.</p>
+<p>This is not yet implemented.</p>
+<h3><a href="#merging-road-maps-and-river-system-maps" name="merging-road-maps-and-river-system-maps"></a>Merging road maps and river system maps</h3>
+<p>It is intended that it should be possible to merge road maps (maps of already computed routes) with maps derived from height maps. These exclusion maps will probably be represented as SVG. This is not yet implemented.</p>
+<p>River system maps are conceptually similar to road maps; this too is not yet implemented.</p>
+<h3><a href="#computing-new-routes-and-roads" name="computing-new-routes-and-roads"></a>Computing new routes and roads</h3>
+<p>It is intended that it should be possible, by simulating agents traversing the terrain, to compute the courses of new roads/tracks/paths. The routing algorithm should implement the following rules.</p>
+<ol>
+  <li>No route may pass through any part of a reserved holding, except the holding which is its origin, if any, and the holding which is its destination (and in any case we won’t render paths or roads within holdings, although traversal information may be used to determine whether a holding, or part of it, is paved/cobbled;</li>
+  <li>No route may pass through any building, with the exception of a city gate;</li>
+  <li>We don’t have bicycles: going uphill costs work, and you don’t get that cost back on the down hill. Indeed, downhills are at least as expensive to traverse as flat ground;</li>
+  <li>Any existing route segment costs only a third as much to traverse as open ground having the same gradient;</li>
+  <li>A more used route costs less to traverse than a less used route;</li>
+  <li>There is a significant cost penalty to crossing a watercourse, except at an existing crossing.</li>
+</ol>
+<p>This is not yet implemented.</p>
+<h3><a href="#writing-out-computed-road-maps-as-svg" name="writing-out-computed-road-maps-as-svg"></a>Writing out computed road maps as SVG</h3>
+<p>It is intended that, after computing new routes and roads, it should be possible to expoer an updated road map as SVG. This is not yet implemented.</p>
+<h2><a href="#license" name="license"></a>License</h2>
+<p>Copyright © 2020 Simon Brooke</p>
+<p>This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at <a href="http://www.eclipse.org/legal/epl-2.0">http://www.eclipse.org/legal/epl-2.0</a>.</p>
+<p>This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at <a href="https://www.gnu.org/software/classpath/license.html">https://www.gnu.org/software/classpath/license.html</a>.</p></div></div></div></body></html>

docs/codox/js/page_effects.js

@@ -0,0 +1,112 @@
+function visibleInParent(element) {
+    var position = $(element).position().top
+    return position > -50 && position < ($(element).offsetParent().height() - 50)
+}
+
+function hasFragment(link, fragment) {
+    return $(link).attr("href").indexOf("#" + fragment) != -1
+}
+
+function findLinkByFragment(elements, fragment) {
+    return $(elements).filter(function(i, e) { return hasFragment(e, fragment)}).first()
+}
+
+function scrollToCurrentVarLink(elements) {
+    var elements = $(elements);
+    var parent   = elements.offsetParent();
+
+    if (elements.length == 0) return;
+
+    var top    = elements.first().position().top;
+    var bottom = elements.last().position().top + elements.last().height();
+
+    if (top >= 0 && bottom <= parent.height()) return;
+
+    if (top < 0) {
+        parent.scrollTop(parent.scrollTop() + top);
+    }
+    else if (bottom > parent.height()) {
+        parent.scrollTop(parent.scrollTop() + bottom - parent.height());
+    }
+}
+
+function setCurrentVarLink() {
+    $('.secondary a').parent().removeClass('current')
+    $('.anchor').
+        filter(function(index) { return visibleInParent(this) }).
+        each(function(index, element) {
+            findLinkByFragment(".secondary a", element.id).
+                parent().
+                addClass('current')
+        });
+    scrollToCurrentVarLink('.secondary .current');
+}
+
+var hasStorage = (function() { try { return localStorage.getItem } catch(e) {} }())
+
+function scrollPositionId(element) {
+    var directory = window.location.href.replace(/[^\/]+\.html$/, '')
+    return 'scroll::' + $(element).attr('id') + '::' + directory
+}
+
+function storeScrollPosition(element) {
+    if (!hasStorage) return;
+    localStorage.setItem(scrollPositionId(element) + "::x", $(element).scrollLeft())
+    localStorage.setItem(scrollPositionId(element) + "::y", $(element).scrollTop())
+}
+
+function recallScrollPosition(element) {
+    if (!hasStorage) return;
+    $(element).scrollLeft(localStorage.getItem(scrollPositionId(element) + "::x"))
+    $(element).scrollTop(localStorage.getItem(scrollPositionId(element) + "::y"))
+}
+
+function persistScrollPosition(element) {
+    recallScrollPosition(element)
+    $(element).scroll(function() { storeScrollPosition(element) })
+}
+
+function sidebarContentWidth(element) {
+    var widths = $(element).find('.inner').map(function() { return $(this).innerWidth() })
+    return Math.max.apply(Math, widths)
+}
+
+function calculateSize(width, snap, margin, minimum) {
+    if (width == 0) {
+        return 0
+    }
+    else {
+        return Math.max(minimum, (Math.ceil(width / snap) * snap) + (margin * 2))
+    }
+}
+
+function resizeSidebars() {
+    var primaryWidth   = sidebarContentWidth('.primary')
+    var secondaryWidth = 0
+
+    if ($('.secondary').length != 0) {
+        secondaryWidth = sidebarContentWidth('.secondary')
+    }
+
+    // snap to grid
+    primaryWidth   = calculateSize(primaryWidth, 32, 13, 160)
+    secondaryWidth = calculateSize(secondaryWidth, 32, 13, 160)
+
+    $('.primary').css('width', primaryWidth)
+    $('.secondary').css('width', secondaryWidth).css('left', primaryWidth + 1)
+
+    if (secondaryWidth > 0) {
+        $('#content').css('left', primaryWidth + secondaryWidth + 2)
+    }
+    else {
+        $('#content').css('left', primaryWidth + 1)
+    }
+}
+
+$(window).ready(resizeSidebars)
+$(window).ready(setCurrentVarLink)
+$(window).ready(function() { persistScrollPosition('.primary')})
+$(window).ready(function() {
+    $('#content').scroll(setCurrentVarLink)
+    $(window).resize(setCurrentVarLink)
+})

docs/codox/walkmap.core.html

@@ -0,0 +1,4 @@
+<!DOCTYPE html PUBLIC ""
+    "">
+<html><head><meta charset="UTF-8" /><title>walkmap.core documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Walkmap</span> <span class="project-version">0.1.0-SNAPSHOT</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="intro.html"><div class="inner"><span>Introduction to walkmap</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1 current"><a href="walkmap.core.html"><div class="inner"><span>walkmap.core</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="walkmap.core.html#var-binary-stl"><div class="inner"><span>binary-stl</span></div></a></li><li class="depth-1"><a href="walkmap.core.html#var-binary-stl-file-to-svg"><div class="inner"><span>binary-stl-file-to-svg</span></div></a></li><li class="depth-1"><a href="walkmap.core.html#var-binary-stl-to-ascii"><div class="inner"><span>binary-stl-to-ascii</span></div></a></li><li class="depth-1"><a href="walkmap.core.html#var-decode-binary-stl"><div class="inner"><span>decode-binary-stl</span></div></a></li><li class="depth-1"><a href="walkmap.core.html#var-facet"><div class="inner"><span>facet</span></div></a></li><li class="depth-1"><a href="walkmap.core.html#var-stl-to-svg"><div class="inner"><span>stl-to-svg</span></div></a></li><li class="depth-1"><a href="walkmap.core.html#var-vect"><div class="inner"><span>vect</span></div></a></li><li class="depth-1"><a href="walkmap.core.html#var-write-ascii-stl"><div class="inner"><span>write-ascii-stl</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">walkmap.core</h1><div class="doc"><div class="markdown"><p>At this stage, primarily utility functions dealing with stereolithography (STL) files. Not a stable API yet!</p></div></div><div class="public anchor" id="var-binary-stl"><h3>binary-stl</h3><div class="usage"></div><div class="doc"><div class="markdown"><p>A codec for binary STL files</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L27">view source</a></div></div><div class="public anchor" id="var-binary-stl-file-to-svg"><h3>binary-stl-file-to-svg</h3><div class="usage"><code>(binary-stl-file-to-svg in-filename)</code><code>(binary-stl-file-to-svg in-filename out-filename)</code></div><div class="doc"><div class="markdown"><p>Given only an <code>in-filename</code>, parse the indicated file, expected to be binary STL, and return an equivalent SVG structure. Given both <code>in-filename</code> and <code>out-filename</code>, as side-effect write the SVG to the indicated output file.</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L145">view source</a></div></div><div class="public anchor" id="var-binary-stl-to-ascii"><h3>binary-stl-to-ascii</h3><div class="usage"><code>(binary-stl-to-ascii in-filename)</code><code>(binary-stl-to-ascii in-filename out-filename)</code></div><div class="doc"><div class="markdown"><p>Convert the binary STL file indicated by <code>in-filename</code>, and write it to <code>out-filename</code>, if specified; otherwise, to a file with the same basename as <code>in-filename</code> but the extension <code>.ascii.stl</code>.</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L83">view source</a></div></div><div class="public anchor" id="var-decode-binary-stl"><h3>decode-binary-stl</h3><div class="usage"><code>(decode-binary-stl filename)</code></div><div class="doc"><div class="markdown"><p>Parse a binary STL file from this <code>filename</code> and return an STL structure representing its contents.</p>
+<p><strong>NOTE</strong> that we’ve no way of verifying that the input file is binary STL data, if it is not this will run but will return garbage.</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L34">view source</a></div></div><div class="public anchor" id="var-facet"><h3>facet</h3><div class="usage"></div><div class="doc"><div class="markdown"><p>A codec for a vector within a binary STL file.</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L20">view source</a></div></div><div class="public anchor" id="var-stl-to-svg"><h3>stl-to-svg</h3><div class="usage"><code>(stl-to-svg stl)</code></div><div class="doc"><div class="markdown"><p>Convert this in-memory <code>stl</code> structure, as read by <code>decode-binary-stl</code>, into an in-memory (Dali) SVG structure, and return it.</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L110">view source</a></div></div><div class="public anchor" id="var-vect"><h3>vect</h3><div class="usage"></div><div class="doc"><div class="markdown"><p>A codec for vectors within a binary STL file.</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L13">view source</a></div></div><div class="public anchor" id="var-write-ascii-stl"><h3>write-ascii-stl</h3><div class="usage"><code>(write-ascii-stl filename stl)</code><code>(write-ascii-stl filename stl solidname)</code></div><div class="doc"><div class="markdown"><p>Write an <code>stl</code> structure as read by <code>decode-binary-stl</code> to this <code>filename</code> as ASCII encoded STL.</p></div></div><div class="src-link"><a href="https://github.com/simon-brooke/walkmap/blob/master/src/walkmap/core.clj#L57">view source</a></div></div></div></body></html>

src/walkmap/core.clj

@@ -1,4 +1,6 @@
 (ns walkmap.core
+  "At this stage, primarily utility functions dealing with stereolithography
+  (STL) files. Not a stable API yet!"
   (:require [clojure.java.io :as io :refer [file output-stream input-stream]]
             [clojure.string :as s]
             [dali.io :as svg]
@@ -9,25 +11,32 @@
            java.io.DataInput))
 
 (def vect
+  "A codec for vectors within a binary STL file."
   (b/ordered-map
     :x :float-le
     :y :float-le
     :z :float-le))
 
 (def facet
+  "A codec for a vector within a binary STL file."
   (b/ordered-map
     :normal vect
     :vertices [vect vect vect]
     :abc :ushort-le))
 
 (def binary-stl
+  "A codec for binary STL files"
   (b/ordered-map
    :header (b/string "ISO-8859-1" :length 80) ;; for the time being we neither know nor care what's in this.
    :count :uint-le
    :facets (b/repeated facet)))
 
 (defn decode-binary-stl
-  "Parse a binary STL file from this `filename`."
+  "Parse a binary STL file from this `filename` and return an STL structure
+  representing its contents.
+
+  **NOTE** that we've no way of verifying that the input file is binary STL
+  data, if it is not this will run but will return garbage."
   [filename]
   (let [in (io/input-stream filename)]
     (b/decode binary-stl in)))
@@ -72,6 +81,9 @@
        "\n"))))
 
 (defn binary-stl-to-ascii
+  "Convert the binary STL file indicated by `in-filename`, and write it to
+  `out-filename`, if specified; otherwise, to a file with the same basename
+  as `in-filename` but the extension `.ascii.stl`."
   ([in-filename]
    (let [[_ ext] (fs/split-ext in-filename)]
      (binary-stl-to-ascii
@@ -88,17 +100,13 @@
   ([in-filename out-filename]
    (write-ascii-stl out-filename (decode-binary-stl in-filename))))
 
-(def stl (decode-binary-stl "resources/small_hill.stl"))
+(defn- facet-to-svg-poly
-
-(defn facet-to-svg-poly
   [facet]
   (vec
     (cons
       :polygon
       (map #(vec (list (:x %) (:y %))) (:vertices facet)))))
 
-(facet-to-svg-poly (first (:facets stl)))
-
 (defn stl-to-svg
   "Convert this in-memory `stl` structure, as read by `decode-binary-stl`, into
   an in-memory (Dali) SVG structure, and return it."
@@ -147,5 +155,10 @@
        out-filename)
      s)))
 
-(map facet-to-svg-poly (:facets stl))
+;; (def stl (decode-binary-stl "resources/small_hill.stl"))
-(svg/render-svg (stl-to-svg stl) "frobox.svg")
+
+;; (facet-to-svg-poly (first (:facets stl)))
+
+;; (map facet-to-svg-poly (:facets stl))
+;; (svg/render-svg (stl-to-svg stl) "frobox.svg")
+(binary-stl-file-to-svg "resources/small_hill.stl" "resources/small_hill.svg")