From 223bf1ce772b370773ad6e82b8e4df0a55095b33 Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Sun, 24 May 2020 16:05:04 +0100 Subject: [PATCH] Geometry isn't working at all, but my head is spinning! --- README.md | 29 ++++++++-------- doc/intro.md | 32 ++++++++---------- docs/codox/index.html | 2 +- docs/codox/intro.html | 29 ++++++++-------- docs/codox/walkmap.core.html | 4 +-- docs/codox/walkmap.edge.html | 3 ++ docs/codox/walkmap.geometry.html | 3 ++ docs/codox/walkmap.path.html | 4 +++ docs/codox/walkmap.polygon.html | 3 ++ docs/codox/walkmap.stl.html | 5 +++ docs/codox/walkmap.svg.html | 3 ++ docs/codox/walkmap.vertex.html | 5 +++ project.clj | 1 + src/walkmap/core.clj | 1 - src/walkmap/edge.clj | 37 +++++++++++++++++++++ src/walkmap/geometry.clj | 57 ++++++++++++++++++++++++++++++++ src/walkmap/path.clj | 3 +- src/walkmap/polygon.clj | 19 ++--------- src/walkmap/stl.clj | 2 +- src/walkmap/svg.clj | 5 +-- src/walkmap/vertex.clj | 40 ++++++++++++++++++++++ 21 files changed, 212 insertions(+), 75 deletions(-) create mode 100644 docs/codox/walkmap.edge.html create mode 100644 docs/codox/walkmap.geometry.html create mode 100644 docs/codox/walkmap.path.html create mode 100644 docs/codox/walkmap.polygon.html create mode 100644 docs/codox/walkmap.stl.html create mode 100644 docs/codox/walkmap.svg.html create mode 100644 docs/codox/walkmap.vertex.html create mode 100644 src/walkmap/edge.clj create mode 100644 src/walkmap/geometry.clj create mode 100644 src/walkmap/vertex.clj diff --git a/README.md b/README.md index 1aaf0d4..96fdac5 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ A Clojure library designed to assist in computing walkmaps for games. ## Introduction This library is written in support of work on -[The Great Game](https://simon-brooke.github.io/the-great-game/codox/), but is +[The Great Game](https://simon-brooke.github.io/the-great-game/codox/Pathmaking.html), but is separate because it may be of some use in other settings. ## Usage @@ -20,10 +20,6 @@ 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 @@ -31,12 +27,14 @@ Doesn't work yet, and is not a priority. Use ### Reading binary STL files + (require '[walkmap.stl :refer [decode-binary-stl]]) (decode-binary-stl "path/to/input-file.stl") Works, seems good. ### Writing ASCII STL files + (require '[walkmap.stl :refer [write-ascii-stl]]) (write-ascii-stl "path/to/output-file.ascii.stl" stl-structure) Works, seems good, agrees with Python implementation except for different @@ -44,13 +42,11 @@ number of places of decimals printed. ### Converting STL to SVG - (stl-to-svg stl-structure) + (require '[walkmap.svg :refer [stl->svg]]) + (stl->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) +Works, seems good. Returns a [hiccup](https://github.com/weavejester/hiccup) +representation of the SVG. **NOTE THAT** the SVG data does not contain height information, which the STL data does contain. Thus gradient information can only be obtained from @@ -58,13 +54,14 @@ the STL. ### Converting STL file to SVG or SVG file - (binary-stl-file-to-svg "path/to/input-file.stl") + (require '[walkmap.core :refer [binary-stl-file->svg]]) + (binary-stl-file->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. +Works, seems good. Returns a [hiccup](https://github.com/weavejester/hiccup) +representation of the SVG. - (binary-stl-file-to-svg "path/to/input-file.stl" "path-to-output-file.svg") + (require '[walkmap.core :refer [binary-stl-file->svg]]) + (binary-stl-file->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. diff --git a/doc/intro.md b/doc/intro.md index fee4c18..3820a3f 100644 --- a/doc/intro.md +++ b/doc/intro.md @@ -1,9 +1,7 @@ # Introduction to walkmap -## Introduction - This library is written in support of work on -[The Great Game](https://simon-brooke.github.io/the-great-game/codox/), but is +[The Great Game](https://simon-brooke.github.io/the-great-game/codox/Pathmaking.html), but is separate because it may be of some use in other settings. ## Usage @@ -18,10 +16,6 @@ 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 @@ -29,12 +23,14 @@ Doesn't work yet, and is not a priority. Use ### Reading binary STL files + (require '[walkmap.stl :refer [decode-binary-stl]]) (decode-binary-stl "path/to/input-file.stl") Works, seems good. ### Writing ASCII STL files + (require '[walkmap.stl :refer [write-ascii-stl]]) (write-ascii-stl "path/to/output-file.ascii.stl" stl-structure) Works, seems good, agrees with Python implementation except for different @@ -42,13 +38,11 @@ number of places of decimals printed. ### Converting STL to SVG - (stl-to-svg stl-structure) + (require '[walkmap.svg :refer [stl->svg]]) + (stl->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) +Works, seems good. Returns a [hiccup](https://github.com/weavejester/hiccup) +representation of the SVG. **NOTE THAT** the SVG data does not contain height information, which the STL data does contain. Thus gradient information can only be obtained from @@ -56,13 +50,14 @@ the STL. ### Converting STL file to SVG or SVG file - (binary-stl-file-to-svg "path/to/input-file.stl") + (require '[walkmap.core :refer [binary-stl-file->svg]]) + (binary-stl-file->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. +Works, seems good. Returns a [hiccup](https://github.com/weavejester/hiccup) +representation of the SVG. - (binary-stl-file-to-svg "path/to/input-file.stl" "path-to-output-file.svg") + (require '[walkmap.core :refer [binary-stl-file->svg]]) + (binary-stl-file->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. @@ -119,4 +114,3 @@ 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. - diff --git a/docs/codox/index.html b/docs/codox/index.html index c5b3e1c..cbfce57 100644 --- a/docs/codox/index.html +++ b/docs/codox/index.html @@ -1,3 +1,3 @@ -Walkmap 0.1.0-SNAPSHOT

Project

Topics

Namespaces

Walkmap 0.1.0-SNAPSHOT

Released under the EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0

A Clojure library designed to assist in computing walkmaps for games.

Installation

To install, add the following dependency to your project or build file:

[walkmap "0.1.0-SNAPSHOT"]

Topics

Namespaces

walkmap.core

At this stage, primarily utility functions dealing with stereolithography (STL) files. Not a stable API yet!

Public variables and functions:

\ No newline at end of file +Walkmap 0.1.0-SNAPSHOT

Project

Topics

Namespaces

Walkmap 0.1.0-SNAPSHOT

Released under the EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0

A Clojure library designed to assist in computing walkmaps for games.

Installation

To install, add the following dependency to your project or build file:

[walkmap "0.1.0-SNAPSHOT"]

Topics

Namespaces

walkmap.core

At this stage, primarily utility functions dealing with stereolithography (STL) files. Not a stable API yet!

Public variables and functions:

walkmap.edge

Essentially the specification for things we shall consider to be an edge. An edge is a line segment having just a start and an end, with no intervening nodes.

Public variables and functions:

walkmap.geometry

TODO: write docs

Public variables and functions:

walkmap.path

Essentially the specification for things we shall consider to be path.

Public variables and functions:

walkmap.polygon

Essentially the specification for things we shall consider to be polygons.

Public variables and functions:

walkmap.stl

Utility functions dealing with stereolithography (STL) files. Not a stable API yet!

Public variables and functions:

walkmap.svg

Utility functions for writing stereolithography (STL) files (and possibly, later, other geometry files of interest to us) as scalable vector graphics (SVG).

Public variables and functions:

walkmap.vertex

Essentially the specification for things we shall consider to be vertices.

Public variables and functions:

\ No newline at end of file diff --git a/docs/codox/intro.html b/docs/codox/intro.html index ef6d6d5..e19fc96 100644 --- a/docs/codox/intro.html +++ b/docs/codox/intro.html @@ -1,8 +1,7 @@ -Introduction to walkmap

Project

Topics

Namespaces

Introduction to walkmap

-

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.

+Introduction to walkmap

Project

Topics

Namespaces

Introduction to walkmap

+

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.

Usage

What works:

No clojars repo yet, build the jar yourself with

@@ -11,31 +10,31 @@

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 instead.

Reading binary STL files

-
(decode-binary-stl "path/to/input-file.stl")
+
(require '[walkmap.stl :refer [decode-binary-stl]])
+(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)
+
(require '[walkmap.stl :refer [write-ascii-stl]])
+(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 structure representing an SVG drawing, which can be printed with

-
(dali.io/render-svg structure)
+
(require '[walkmap.svg :refer [stl->svg]])
+(stl->svg stl-structure)
 

+
Works, seems good. Returns a hiccup representation of the SVG.

 
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")
+
(require '[walkmap.core :refer [binary-stl-file->svg]])
+(binary-stl-file->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 structure representing an SVG drawing, as above.

-
(binary-stl-file-to-svg "path/to/input-file.stl" "path-to-output-file.svg")
+
Works, seems good. Returns a hiccup representation of the SVG.

+
(require '[walkmap.core :refer [binary-stl-file->svg]])
+(binary-stl-file->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

diff --git a/docs/codox/walkmap.core.html b/docs/codox/walkmap.core.html
index 89f8064..1ce46d2 100644
--- a/docs/codox/walkmap.core.html
+++ b/docs/codox/walkmap.core.html
@@ -1,4 +1,4 @@
 
-walkmap.core documentation
Project
Topics
Namespaces
Public Vars
walkmap.core
At this stage, primarily utility functions dealing with stereolithography (STL) files. Not a stable API yet!
binary-stl
A codec for binary STL files
view source
binary-stl-file-to-svg
(binary-stl-file-to-svg in-filename)(binary-stl-file-to-svg in-filename out-filename)
Given only an in-filename, parse the indicated file, expected to be binary STL, and return an equivalent SVG structure. Given both in-filename and out-filename, as side-effect write the SVG to the indicated output file.
view source
binary-stl-to-ascii
(binary-stl-to-ascii in-filename)(binary-stl-to-ascii in-filename out-filename)
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.
view source
decode-binary-stl
(decode-binary-stl 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.
view source
facet
A codec for a vector within a binary STL file.
view source
stl-to-svg
(stl-to-svg stl)
Convert this in-memory stl structure, as read by decode-binary-stl, into an in-memory (Dali) SVG structure, and return it.
view source
vect
A codec for vectors within a binary STL file.
view source
write-ascii-stl
(write-ascii-stl filename stl)(write-ascii-stl filename stl solidname)
Write an stl structure as read by decode-binary-stl to this filename as ASCII encoded STL.
view source

\ No newline at end of file
+walkmap.core documentation
Project
Topics
Namespaces
Public Vars
walkmap.core
At this stage, primarily utility functions dealing with stereolithography (STL) files. Not a stable API yet!
*sea-level*
dynamic
The sea level on heightmaps we’re currently handling. If characters are to be able to swin in the sea, we must model the sea bottom, so we need heightmaps which cover at least the continental shelf. However, the sea bottom is not walkable territory and can be culled from walkmaps.

+
Note must be a floating point number. (= 0 0.0) returns false!
view source
binary-stl-file->svg
(binary-stl-file->svg in-filename)(binary-stl-file->svg in-filename out-filename)
Given only an in-filename, parse the indicated file, expected to be binary STL, and return an equivalent SVG structure. Given both in-filename and out-filename, as side-effect write the SVG to the indicated output file.
view source
cull-ocean-facets
(cull-ocean-facets stl)
Ye cannae walk on water. Remove all facets from this stl structure which are at sea level.
view source
ocean?
(ocean? facet)
Of a facet, is the altitude of every vertice equal to *sea-level*?
view source

\ No newline at end of file
diff --git a/docs/codox/walkmap.edge.html b/docs/codox/walkmap.edge.html
new file mode 100644
index 0000000..49fe8ac
--- /dev/null
+++ b/docs/codox/walkmap.edge.html
@@ -0,0 +1,3 @@
+
+walkmap.edge documentation
Project
Topics
Namespaces
Public Vars
walkmap.edge
Essentially the specification for things we shall consider to be an edge. An edge is a line segment having just a start and an end, with no intervening nodes.
edge?
(edge? o)
True if o satisfies the conditions for a path. A path shall be a map having the keys :start and :end, such that the values of each of those keys shall be a vertex.
view source
path->edges
(path->edges o)
if o is a path, a polygon, or a sequence of vertices, return a sequence of edges representing that path, polygon or sequence.
view source

\ No newline at end of file
diff --git a/docs/codox/walkmap.geometry.html b/docs/codox/walkmap.geometry.html
new file mode 100644
index 0000000..fbb6833
--- /dev/null
+++ b/docs/codox/walkmap.geometry.html
@@ -0,0 +1,3 @@
+
+walkmap.geometry documentation
Project
Topics
Namespaces
Public Vars
walkmap.geometry
TODO: write docs
collinear?
(collinear? v1 v2 v3)
True if these vertices v1, v2, v3 are colinear; false otherwise.
view source
on?
(on? e v)
True if the vertex v is on the edge e.
view source

\ No newline at end of file
diff --git a/docs/codox/walkmap.path.html b/docs/codox/walkmap.path.html
new file mode 100644
index 0000000..95180b3
--- /dev/null
+++ b/docs/codox/walkmap.path.html
@@ -0,0 +1,4 @@
+
+walkmap.path documentation
Project
Topics
Namespaces
Public Vars
walkmap.path
Essentially the specification for things we shall consider to be path.
path?
(path? o)
True if o satisfies the conditions for a path. A path shall be a map having the key :nodes, whose value shall be a sequence of vertices as defined in walkmap.polygon.
view source
polygon->path
(polygon->path o)
If o is a polygon, return an equivalent path. What’s different about a path is that in polygons there is an implicit edge between the first vertex and the last. In paths, there isn’t, so we need to add that edge explicitly.

+
If o is not a polygon, will throw an exception.
view source

\ No newline at end of file
diff --git a/docs/codox/walkmap.polygon.html b/docs/codox/walkmap.polygon.html
new file mode 100644
index 0000000..b829023
--- /dev/null
+++ b/docs/codox/walkmap.polygon.html
@@ -0,0 +1,3 @@
+
+walkmap.polygon documentation
Project
Topics
Namespaces
Public Vars
walkmap.polygon
Essentially the specification for things we shall consider to be polygons.
polygon?
(polygon? o)
True if o satisfies the conditions for a polygon. A polygon shall be a map which has a value for the key :vertices, where that value is a sequence of vertices.
view source

\ No newline at end of file
diff --git a/docs/codox/walkmap.stl.html b/docs/codox/walkmap.stl.html
new file mode 100644
index 0000000..eb281c8
--- /dev/null
+++ b/docs/codox/walkmap.stl.html
@@ -0,0 +1,5 @@
+
+walkmap.stl documentation
Project
Topics
Namespaces
Public Vars
walkmap.stl
Utility functions dealing with stereolithography (STL) files. Not a stable API yet!
binary-stl
A codec for binary STL files
view source
binary-stl-to-ascii
(binary-stl-to-ascii in-filename)(binary-stl-to-ascii in-filename out-filename)
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.
view source
decode-binary-stl
(decode-binary-stl 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.
view source
facet
A codec for a facet (triangle) within a binary STL file.
view source
stl->ascii
(stl->ascii stl)(stl->ascii stl solidname)
Return as a string an ASCII rendering of the stl structure.
view source
stl?
(stl? o)(stl? o verify-count?)
True if o is recogniseable as an STL structure. An STL structure must have a key :facets, whose value must be a sequence of polygons; and may have a key :header whose value should be a string, and/or a key :count, whose value should be a positive integer.

+
If verify-count? is passed and is not false, verify that the value of the :count header is equal to the number of facets.
view source
vect
A codec for vectors within a binary STL file.
view source
write-ascii-stl
(write-ascii-stl filename stl)(write-ascii-stl filename stl solidname)
Write an stl structure as read by decode-binary-stl to this filename as ASCII encoded STL.
view source

\ No newline at end of file
diff --git a/docs/codox/walkmap.svg.html b/docs/codox/walkmap.svg.html
new file mode 100644
index 0000000..22e1c10
--- /dev/null
+++ b/docs/codox/walkmap.svg.html
@@ -0,0 +1,3 @@
+
+walkmap.svg documentation
Project
Topics
Namespaces
Public Vars
walkmap.svg
Utility functions for writing stereolithography (STL) files (and possibly, later, other geometry files of interest to us) as scalable vector graphics (SVG).
stl->svg
(stl->svg stl)
Convert this in-memory stl structure, as read by decode-binary-stl, into an in-memory (Dali) SVG structure, and return it.
view source

\ No newline at end of file
diff --git a/docs/codox/walkmap.vertex.html b/docs/codox/walkmap.vertex.html
new file mode 100644
index 0000000..1bbf6d9
--- /dev/null
+++ b/docs/codox/walkmap.vertex.html
@@ -0,0 +1,5 @@
+
+walkmap.vertex documentation
Project
Topics
Namespaces
Public Vars
walkmap.vertex
Essentially the specification for things we shall consider to be vertices.
ensure2d
(ensure2d o)
If o is a vertex, set its :z value to zero; else throw an exception.
view source
ensure3d
(ensure3d o)(ensure3d o dflt)
Given a vertex o, if o has a :z value, just return o; otherwise return a vertex like o but having thie dflt value as the value of its :z key, or zero as the value of its :z key if dflt is not specified.

+
If o is not a vertex, throws an exception.
view source
vertex?
(vertex? o)
True if o satisfies the conditions for a vertex. That is, essentially, that it must rerpresent a two- or three- dimensional vector. A vertex is shall be a map having at least the keys :x and :y, where the value of those keys is a number. If the key :z is also present, its value must also be a number.

+
The name vector? was not used as that would clash with a function of that name in clojure.core whose semantics are entirely different.
view source

\ No newline at end of file
diff --git a/project.clj b/project.clj
index cac934e..0ae73cc 100644
--- a/project.clj
+++ b/project.clj
@@ -6,6 +6,7 @@
           :source-uri "https://github.com/simon-brooke/walkmap/blob/master/{filepath}#L{line}"}
   :dependencies [[org.clojure/clojure "1.8.0"]
                  [org.clojure/math.numeric-tower "0.0.4"]
+                 [org.clojure/math.combinatorics "0.1.6"]
                  [com.taoensso/timbre "4.10.0"]
                  [dali "0.7.4"]
                  [hiccup "1.0.5"]
diff --git a/src/walkmap/core.clj b/src/walkmap/core.clj
index 32b96d8..09fcc30 100644
--- a/src/walkmap/core.clj
+++ b/src/walkmap/core.clj
@@ -39,7 +39,6 @@
    (stl->svg (cull-ocean-facets (decode-binary-stl in-filename))))
   ([in-filename out-filename]
    (let [s (binary-stl-file->svg in-filename)]
-     ;; (svg/render-svg s out-filename)
      (spit out-filename (html s))
      s)))
 
diff --git a/src/walkmap/edge.clj b/src/walkmap/edge.clj
new file mode 100644
index 0000000..b77547d
--- /dev/null
+++ b/src/walkmap/edge.clj
@@ -0,0 +1,37 @@
+(ns walkmap.edge
+  "Essentially the specification for things we shall consider to be an edge.
+  An edge is a line segment having just a start and an end, with no intervening
+  nodes."
+  (:require [walkmap.path :refer [path? polygon->path]]
+            [walkmap.polygon :refer [polygon?]]
+            [walkmap.vertex :refer [vertex?]]))
+
+(defn edge?
+  "True if `o` satisfies the conditions for a path. A path shall be a map
+  having the keys `:start` and `:end`, such that the values of each of those
+  keys shall be a vertex."
+  [o]
+  (and
+    (map? o)
+    (vertex? (:start o))
+    (vertex? (:end o))))
+
+(defn path->edges
+  "if `o` is a path, a polygon, or a sequence of vertices, return a sequence of
+  edges representing that path, polygon or sequence."
+  [o]
+  (cond
+    (seq? o)
+    (when
+      (and
+        (vertex? (first o))
+        (vertex? (first (rest o))))
+      (cons
+        {:start (first o)
+         :end (first (rest o))}
+        (path->edges (rest o))))
+    (path? o)
+    (path->edges (:nodes o))
+    (polygon? o)
+    (path->edges (polygon->path o))))
+
diff --git a/src/walkmap/geometry.clj b/src/walkmap/geometry.clj
new file mode 100644
index 0000000..61baf32
--- /dev/null
+++ b/src/walkmap/geometry.clj
@@ -0,0 +1,57 @@
+(ns walkmap.geometry
+  (:require [clojure.math.combinatorics :as combo]
+            [clojure.math.numeric-tower :as m]
+            [walkmap.edge :as edge]
+            [walkmap.path :refer [path? polygon->path]]
+            [walkmap.polygon :refer [polygon?]]
+            [walkmap.vertex :as vertex]))
+
+(defn collinear?
+  "True if these vertices `v1`, `v2`, `v3` are colinear; false otherwise."
+  ;; This is failing...
+  ;; see http://www.ambrsoft.com/TrigoCalc/Line3D/LineColinear.htm
+  [v1 v2 v3]
+  (let [a (m/sqrt (+ (- (:x v2) (:x v1)) (- (:y v2) (:y v1)) (- (:z v2) (:z v1))))
+        b (m/sqrt (+ (- (:x v3) (:x v1)) (- (:y v3) (:y v1)) (- (:z v3) (:z v1))))
+        c (m/sqrt (+ (- (:x v3) (:x v2)) (- (:y v3) (:y v2)) (- (:z v3) (:z v2))))]
+    (not
+      (and
+        (> (+ a b) c)
+        (> (+ a c) b)
+        (> (+ b c) a)))))
+
+;; (collinear? {:x 0 :y 0 :z 0} {:x 1 :y 1 :z 1} {:x 7 :y 7 :z 7})
+;; (collinear? {:x 0 :y 0 :z 0} {:x 1 :y 2 :z 1} {:x 7 :y 7 :z 7})
+;; (collinear? {:x 0 :y 0 :z 0} {:x 0 :y 2 :z 0} {:x 0 :y 3 :z 0})
+
+;; (def v1 {:x 0 :y 0 :z 0})
+;; (def v2  {:x 0 :y 2 :z 0})
+;; (def v3 {:x 0 :y 7 :z 0})
+
+;; (def a (m/sqrt (+ (- (:x v2) (:x v1)) (- (:y v2) (:y v1)) (- (:z v2) (:z v1)))))
+;; a
+;; (def b (m/sqrt (+ (- (:x v3) (:x v1)) (- (:y v3) (:y v1)) (- (:z v3) (:z v1)))))
+;; b
+;; (def c (m/sqrt (+ (- (:x v3) (:x v2)) (- (:y v3) (:y v2)) (- (:z v3) (:z v2)))))
+;; c
+
+;; (> (+ b c) a)
+;; (> (+ a c) b)
+;; (> (+ a c) c)
+
+(defn on?
+  "True if the vertex `v` is on the edge `e`."
+  [e v]
+  (let [p (vertex/ensure3d (:start e))
+        q (vertex/ensure3d v)
+        r (vertex/ensure3d (:end e))]
+    (and
+      (collinear? p q r)
+      (<= (:x q) (max (:x p) (:x r)))
+      (>= (:x q) (min (:x p) (:x r)))
+      (<= (:y q) (max (:y p) (:y r)))
+      (>= (:y q) (min (:y p) (:y r)))
+      (<= (:z q) (max (:z p) (:z r)))
+      (>= (:z q) (min (:z p) (:z r))))))
+
+
diff --git a/src/walkmap/path.clj b/src/walkmap/path.clj
index 03af49e..f7b2649 100644
--- a/src/walkmap/path.clj
+++ b/src/walkmap/path.clj
@@ -1,6 +1,7 @@
 (ns walkmap.path
   "Essentially the specification for things we shall consider to be path."
-  (:require [walkmap.polygon :refer [polygon? vertex?]]))
+  (:require [walkmap.polygon :refer [polygon?]]
+            [walkmap.vertex :refer [vertex?]]))
 
 (defn path?
   "True if `o` satisfies the conditions for a path. A path shall be a map
diff --git a/src/walkmap/polygon.clj b/src/walkmap/polygon.clj
index d000994..71b3728 100644
--- a/src/walkmap/polygon.clj
+++ b/src/walkmap/polygon.clj
@@ -1,21 +1,6 @@
 (ns walkmap.polygon
-  "Essentially the specification for things we shall consider to be polygons.")
-
-(defn vertex?
-  "True if `o` satisfies the conditions for a vertex. That is, essentially,
-  that it must rerpresent a two- or three- dimensional vector. A vertex is
-  shall be a map having at least the keys `:x` and `:y`, where the value of
-  those keys is a number. If the key `:z` is also present, its value must also
-  be a number.
-
-  The name  `vector?` was not used as that would clash with a function of that
-  name in `clojure.core` whose semantics are entirely different."
-  [o]
-  (and
-    (map? o)
-    (number? (:x o))
-    (number? (:y o))
-    (or (nil? (:z o)) (number? (:z o)))))
+  "Essentially the specification for things we shall consider to be polygons."
+  (:require [walkmap.vertex :refer [vertex?]]))
 
 (defn polygon?
   "True if `o` satisfies the conditions for a polygon. A polygon shall be a
diff --git a/src/walkmap/stl.clj b/src/walkmap/stl.clj
index e6926d2..e9c8789 100644
--- a/src/walkmap/stl.clj
+++ b/src/walkmap/stl.clj
@@ -1,7 +1,7 @@
 (ns walkmap.stl
   "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]
+            [clojure.string :as s]
             [me.raynes.fs :as fs]
             [org.clojars.smee.binary.core :as b]
             [taoensso.timbre :as l :refer [info error spy]]
diff --git a/src/walkmap/svg.clj b/src/walkmap/svg.clj
index f656027..c2a2e38 100644
--- a/src/walkmap/svg.clj
+++ b/src/walkmap/svg.clj
@@ -1,10 +1,11 @@
-(ns walkmap.stl
+(ns walkmap.svg
   "Utility functions for writing stereolithography (STL) files (and possibly,
   later, other geometry files of interest to us) as scalable vector graphics
   (SVG)."
   (:require [clojure.string :as s]
             [taoensso.timbre :as l :refer [info error spy]]
-            [walkmap.polygon :refer [polygon? vertex?]]))
+            [walkmap.polygon :refer [polygon?]]
+            [walkmap.vertex :refer [vertex?]]))
 
 (defn- facet->svg-poly
   [facet]
diff --git a/src/walkmap/vertex.clj b/src/walkmap/vertex.clj
new file mode 100644
index 0000000..78064ee
--- /dev/null
+++ b/src/walkmap/vertex.clj
@@ -0,0 +1,40 @@
+(ns walkmap.vertex
+  "Essentially the specification for things we shall consider to be vertices.")
+
+(defn vertex?
+  "True if `o` satisfies the conditions for a vertex. That is, essentially,
+  that it must rerpresent a two- or three- dimensional vector. A vertex is
+  shall be a map having at least the keys `:x` and `:y`, where the value of
+  those keys is a number. If the key `:z` is also present, its value must also
+  be a number.
+
+  The name  `vector?` was not used as that would clash with a function of that
+  name in `clojure.core` whose semantics are entirely different."
+  [o]
+  (and
+    (map? o)
+    (number? (:x o))
+    (number? (:y o))
+    (or (nil? (:z o)) (number? (:z o)))))
+
+(defn ensure3d
+  "Given a vertex `o`, if `o` has a `:z` value, just return `o`; otherwise
+  return a vertex like `o` but having thie `dflt` value as the value of its
+  `:z` key, or zero as the value of its `:z` key if `dflt` is not specified.
+
+  If `o` is not a vertex, throws an exception."
+  ([o]
+   (ensure3d o 0.0))
+  ([o dflt]
+   (cond
+     (not (vertex? o)) (throw (Exception. "Not a vertex!"))
+     (:z o) o
+     :else (assoc o :z dflt))))
+
+(defn ensure2d
+  "If `o` is a vertex, set its `:z` value to zero; else throw an exception."
+  [o]
+  (if
+    (vertex? o)
+    (assoc o :z 0.0)
+    (throw (Exception. "Not a vertex!"))))