Merge pull request #24 from dengwirda/dev

Dev

README.md

@@ -9,7 +9,7 @@
 
 `JIGSAW` is a computational library for unstructured mesh generation and tessellation; designed to generate high-quality triangulations and polyhedral decompositions of general planar, surface and volumetric domains. `JIGSAW` includes refinement-based algorithms for the construction of new meshes, optimisation-driven techniques for the improvement of existing grids, as well as routines to assemble (restricted) Delaunay tessellations, Voronoi complexes and Power diagrams.
 
-This package provides the underlying `C++` source for `JIGSAW`; defining a basic command-line interface and a `C`-format `API`. A <a href="http://www.mathworks.com">`MATLAB`</a> / <a href="http://www.gnu.org/software/octave">`OCTAVE`</a> based scripting interface, including a range of additional facilities for file I/O, mesh visualisation and post-processing operations can be found <a href="https://github.com/dengwirda/jigsaw-matlab">here</a>.
+This package provides the underlying `C++` source for `JIGSAW`; defining a basic command-line interface and a `C`-format `API`. Higher-level scripting interfaces, supporting a range of additional facilities for file I/O, mesh visualisation and post-processing operations are also available, including for <a href="http://www.mathworks.com">`MATLAB`</a> / <a href="http://www.gnu.org/software/octave">`OCTAVE`</a> <a href="https://github.com/dengwirda/jigsaw-matlab">here</a> and for <a href="https://www.python.org/">`PYTHON`</a> <a href="https://github.com/dengwirda/jigsaw-python">here</a>.
 
 `JIGSAW` has been compiled and tested on various `64-bit` `Linux`, `Windows` and `MacOS` based platforms. 
 
@@ -20,8 +20,8 @@ This package provides the underlying `C++` source for `JIGSAW`; defining a basic
       JIGSAW::
       ├── src -- JIGSAW src code
       ├── inc -- JIGSAW header files (for libjigsaw)
-      ├── bin -- put JIGSAW exe binaries here
-      ├── lib -- put JIGSAW lib binaries here
+      ├── bin -- JIGSAW's exe binaries live here
+      ├── lib -- JIGSAW's lib binaries live here
       ├── geo -- geometry definitions and input data
       ├── out -- default folder for JIGSAW output
       └── uni -- unit tests and libjigsaw example programs
@@ -32,62 +32,42 @@ The first step is to compile and configure the code! `JIGSAW` can either be buil
 
 ### `Building from src`
 
-The full `JIGSAW` src can be found in <a href="../master/src/">`../jigsaw/src/`</a>.
+The full `JIGSAW` src can be found in <a href="../master/src/">`../jigsaw/src/`</a>. It has been built using various `C++11` conforming versions of the `g++`, `clang++` and `msvc` compilers.
 
 `JIGSAW` is a `header-only` package - the single main `jigsaw.cpp` file simply `#include`'s the rest of the library directly. `JIGSAW` does not currently dependent on any external packages or libraries.
 
 `JIGSAW` consists of several pieces: `(a)` a set of command-line utilities that read and write mesh data from/to file, and `(b)` a shared library, accessible via a `C`-format `API`.
 
-#### `Using cmake`
+### `Using cmake`
 
 `JIGSAW` can be built using the <a href="https://cmake.org/">`cmake`</a> utility. To build, follow the steps below:
 
     * Ensure you have the cmake utility installed.
     * Clone or download this repository.
     * Navigate to the root `../jigsaw/` directory.
-    * Create a new temporary directory BUILD (to store the cmake build files).
-    * Navigate into the temporary directory.
-    * Execute: cmake -D CMAKE_BUILD_TYPE=BUILD_MODE ..
-    * Execute: make
-    * Execute: make install
-    * Delete the temporary directory.
+    * Make a new temporary directory BUILD.
+    * cd build
+    * cmake .. -D CMAKE_BUILD_TYPE=BUILD_MODE
+    * cmake --build . --config BUILD_MODE --target install
+    * Delete the temporary BUILD directory.
 
-This process will build a series of executables and the shared library: `jigsaw` itself - the main command-line meshing utility, `tripod` - `JIGSAW`'s tessellation infrastructure, as well as `libjigsaw` - `JIGSAW`'s shared `API`. `BUILD_MODE` can be used to select different compiler configurations and should be either `RELEASE` or `DEBUG`. 
+This process will build a series of executables and shared libraries: `jigsaw` itself - the main command-line meshing utility, `tripod` - `JIGSAW`'s tessellation infrastructure, as well as `libjigsaw` - `JIGSAW`'s shared `API`. `BUILD_MODE` can be used to select different compiler configurations and should generally either be `Release` or `Debug`. 
 
 See `example.jig` for documentation on calling the command-line executables, and the headers in <a href="../master/inc/">`../jigsaw/inc/`</a> for details on the `API`.
 
-#### `Using g++ / llvm`
-
-`JIGSAW` has been successfully built using various versions of the `g++` and `llvm` compilers. The build process is a simple one-liner (from <a href="../master/src/">`../jigsaw/src/`</a>):
-````
-g++ -std=c++11 -pedantic -Wall -O3 -flto -D NDEBUG
--D __cmd_jigsaw jigsaw.cpp -o ../bin/jigsaw
-````
-will build the main `jigsaw` command-line executable,
-````
-g++ -std=c++11 -pedantic -Wall -O3 -flto -D NDEBUG
--D __cmd_tripod jigsaw.cpp -o ../bin/tripod
-````
-will build the `tripod` command-line utility (`JIGSAW`'s tessellation infrastructure) and,
-````
-g++ -std=c++11 -pedantic -Wall -O3 -flto -fPIC -D NDEBUG
--D __lib_jigsaw jigsaw.cpp -shared -o ../lib/libjigsaw.so
-````
-will build `JIGSAW` as a shared library (`libjigsaw`).
-
-### `Install via conda`
+### `Using conda`
 
 `JIGSAW` is also available as a `conda` environment. To install and use, follow the steps below:
 
-	* Ensure you have conda installed. If not, consider miniconda as a lightweight option.
-	* Add conda-forge as a channel: conda config --add channels conda-forge
-	* Create a jigsaw environment: conda create -n jigsaw jigsaw
+    * Ensure you have conda installed. If not, consider miniconda as a lightweight option.
+    * Add conda-forge as a channel: conda config --add channels conda-forge
+    * Create a jigsaw environment: conda create -n jigsaw jigsaw
 
 Each time you want to use `JIGSAW` simply activate the environment using: `conda activate jigsaw`
 
 Once activated, the various `JIGSAW` command-line utilities will be available in your run path, `JIGSAW`'s shared library (`libjigsaw`) will be available in your library path and its include files in your include path.
 
-### `CMD-LINE Examples`
+### `CMD-line Examples`
 
 After compiling the code, try running the following command-line example to get started:
 ````
@@ -101,23 +81,22 @@ On LNX platforms:
 ````
 In this example, a high-quality tetrahedral mesh is generated for the 'stanford-bunny' geometry and the result written to file. The input geometry is specified as a triangulated surface, and is read from `../jigsaw/geo/bunny.msh`. The volume and surface mesh outputs are written to `../jigsaw/out/bunny.msh`. See the `example.jig` text-file for a description of `JIGSAW`'s configuration options. 
 
-A repository of additional surface models generated using `JIGSAW` can be found <a href="https://github.com/dengwirda/jigsaw-models">here</a>.
+A repository of additional surface models generated using `JIGSAW` can be found <a href="https://github.com/dengwirda/jigsaw-models">here</a>. A description of the `*.jig` and `*.msh` input file formats can be found in the <a href="https://github.com/dengwirda/jigsaw/wiki">wiki</a>.
 
-### `LIBJIGSAW Scripts`
+### `libJIGSAW Scripts`
 
 A set of unit-tests and `libjigsaw` example programs are contained in <a href="../master/uni/">`../jigsaw/uni/`</a>. The `JIGSAW-API` is documented via the header files in <a href="../master/inc/">`../jigsaw/inc/`</a>. 
 
 The unit-tests can be built using the <a href="https://cmake.org/">`cmake`</a> utility. To build, follow the steps below:
 
     * Navigate to the `../jigsaw/uni/` directory.
-    * Create a new temporary directory BUILD (to store the cmake build files).
-    * Navigate into the temporary directory.
-    * Execute: cmake -D CMAKE_BUILD_TYPE=BUILD_MODE ..
-    * Execute: make
-    * Execute: make install
-    * Delete the temporary directory.
-
-This process will build the unit-tests as a series of executables in <a href="../master/uni/">`../jigsaw/uni/`</a>. `BUILD_MODE` is a compiler configuration flag: either `RELEASE` or `DEBUG`.
+    * Make a new temporary directory BUILD.
+    * cd build
+    * cmake .. -D CMAKE_BUILD_TYPE=BUILD_MODE
+    * cmake --build . --config BUILD_MODE --target install
+    * Delete the temporary BUILD directory.
+
+This process will build the unit-tests as a series of executables in <a href="../master/uni/">`../jigsaw/uni/`</a>. `BUILD_MODE` is a compiler configuration flag: either `Release` or `Debug`.
 
 ### `License`
 

example.jig

@@ -31,8 +31,6 @@
 
 #   ---> GEOM_FILE - 'GEOMNAME.MSH', a string containing the 
 #       name of the geometry file (is required at input). 
-#       See SAVEMSH for additional details regarding the cr-
-#       eation of *.MSH files.
 #
 
     GEOM_FILE = geo/bunny.msh
@@ -99,15 +97,15 @@
 
 #   ---> GEOM_ETA1 - {default=45deg} 1-dim. feature-angle, 
 #       features are located between any neighbouring 
-#       "edges" that subtend angles less than ETA1 deg.
+#       edges that subtend angles less than ETA1 degrees.
 #
 
 #   GEOM_ETA1 = 60
 
 
 #   ---> GEOM_ETA2 - {default=45deg} 2-dim. feature angle, 
 #       features are located between any neighbouring 
-#       "faces" that subtend angles less than ETA2 deg.
+#       faces that subtend angles less than ETA2 degrees.
 #
 
 #   GEOM_ETA2 = 60
@@ -122,13 +120,15 @@
 #       name of the mesh-size file (is required at input).
 #       The mesh-size function is specified as a general pi-
 #       ecewise linear function, defined at the vertices of
-#       an unstructured triangulation. See SAVEMSH for addi-
-#       tional details.
+#       an unstructured triangulation or on a structured 
+#       grid.
 #
 
+#   HFUN_FILE = *.msh
+
 
 #   ---> HFUN_SCAL - {default='relative'} scaling type for 
-#       mesh-size fuction. HFUN_SCAL='relative' interprets 
+#       mesh-size function. HFUN_SCAL='relative' interprets 
 #       mesh-size values as percentages of the (mean) length 
 #       of the axis-aligned bounding-box (AABB) associated 
 #       with the geometry. HFUN_SCAL='absolute' interprets 
@@ -167,7 +167,7 @@
 #   MESH_DIMS = 2
 
 
-#   ---> MESH_KERN - {default='delfront'} meshing kernal,
+#   ---> MESH_KERN - {default='delfront'} meshing kernel,
 #       choice of the standard Delaunay-refinement algorithm 
 #       (KERN='delaunay') or the Frontal-Delaunay method 
 #       (KERN='delfront').
@@ -287,7 +287,7 @@
 #   ---> MESH_VOL3 - {default=0.00} min. volume-length ratio 
 #       for 3-tria elements. 3-tria elements are refined 
 #       until the volume-length ratio exceeds VOL3. Can be 
-#       used to supress "sliver" elements.
+#       used to suppress "sliver" elements.
 #
 
 #   MESH_VOL3 = 0.10