Browse Source

Update README and add screenshots

Tyler Hallada 4 years ago
parent
commit
24e5b17c63

+ 88 - 3
README.md

@@ -1,6 +1,6 @@
1
-Generates the shapes and then serializes them to a JSON file with a list of 
2
-vertices (`positions`) and a list of triangle faces (`cells`) that index into 
3
-the list of vertices. Suitable for input into [Three.js's 
1
+Generates the shapes and then serializes them to a file with a list of vertices 
2
+(`positions`) and a list of triangle faces (`cells`) that index into the list of 
3
+vertices. Suitable for input into [Three.js's 
4 4
 BufferGeometry](https://threejs.org/docs/#api/en/core/BufferGeometry) or 
5 5
 [regl](https://github.com/regl-project/regl/blob/gh-pages/example/camera.js).
6 6
 
@@ -15,3 +15,88 @@ When rendering hexspheres of detail level 5 and higher and icosahedrons of
15 15
 detail level of 7 and higher in WebGL, make sure to enable the 
16 16
 [`OES_element_index_uint`](https://developer.mozilla.org/en-US/docs/Web/API/OES_element_index_uint) 
17 17
 extension since the number of vertices might overflow the normal int index.
18
+
19
+The program can also add color to each face by assigning each vertex a color, 
20
+but this comes at the cost of duplicating the shared vertices in the base model 
21
+so each face has a unique set of vertices, greatly increasing the size of the 
22
+mesh.
23
+
24
+## Screenshots
25
+
26
+To generate a detailed hexsphere, it starts with base icosahedron:
27
+
28
+![icosahedron](img/icosahedron_colored_1.png)
29
+
30
+Subdivides it's sides into a more detailed icosahedron:
31
+
32
+![subdivided icosahedron](img/icosahedron_colored_3.png)
33
+
34
+Then, truncates every point in the icosahedron into hexagons and 12 pentagons:
35
+
36
+![hexsphere detail 3](img/hexsphere_colored_3.png)
37
+
38
+Up to any detail level:
39
+
40
+![hexsphere detail 7](img/hexsphere_colored_7.png)
41
+
42
+## Install
43
+
44
+To install, checkout the repo and then run `cargo install icosahedron`.
45
+
46
+## Usage
47
+
48
+Run it with the following options:
49
+
50
+```
51
+icosahedron 1.0
52
+Tyler Hallada <tyler@hallada.net>
53
+Generates 3D icosahedra meshes
54
+
55
+USAGE:
56
+    icosahedron [FLAGS] [OPTIONS] [OUTPUT]
57
+
58
+FLAGS:
59
+    -c, --colored      Assigns a random color to every face (increases vertices count).
60
+    -h, --help         Prints help information
61
+    -t, --truncated    Generate truncated icosahedra (hexspheres).
62
+    -V, --version      Prints version information
63
+
64
+OPTIONS:
65
+    -d, --detail <detail>    Maximum detail level to generate. Each level multiplies the number of triangles by 4.
66
+                             [default: 7]
67
+    -f, --format <format>    Format to write the files in. [default: Bin]  [possible values: Json, Bin]
68
+    -r, --radius <radius>    Radius of the polyhedron, [default: 1.0]
69
+
70
+ARGS:
71
+    <OUTPUT>    Directory to write the output files to. [default: output/]
72
+```
73
+
74
+## Output Format
75
+
76
+Outputs in either JSON or custom binary format. The binary format (all little 
77
+endian) is laid out as:
78
+
79
+1. 1 32 bit unsigned integer specifying the number of vertices (`V`)
80
+2. 1 32 bit unsigned integer specifying the number of triangles (`T`)
81
+3. `V` * 3 number of 32 bit floats for every vertex's x, y, and z coordinate
82
+4. `V` * 3 number of 32 bit floats for the normals of every vertex
83
+5. `V` * 3 number of 32 bit floats for the color of every vertex component
84
+6. `T` * 3 number of 32 bit unsigned integers for the 3 indices into the vertex 
85
+   array that make every triangle
86
+
87
+An example of reading the binary format in JavaScript:
88
+
89
+```javascript
90
+fetch(binaryFile)
91
+  .then(response => response.arrayBuffer())
92
+  .then(buffer => {
93
+    let reader = new DataView(buffer);
94
+    let numVertices = reader.getUint32(0, true);
95
+    let numCells = reader.getUint32(4, true);
96
+    let shape = {
97
+      positions: new Float32Array(buffer, 8, numVertices * 3),
98
+      normals: new Float32Array(buffer, numVertices * 12 + 8, numVertices * 3),
99
+      colors: new Float32Array(buffer, numVertices * 24 + 8, numVertices * 3),
100
+      cells: new Uint32Array(buffer, numVertices * 36 + 8, numCells * 3),
101
+    })
102
+```

BIN
img/hexsphere_colored_3.png


BIN
img/hexsphere_colored_7.png


BIN
img/icosahedron_colored_1.png


BIN
img/icosahedron_colored_3.png