Skip to content

Commit cab8b4e

Browse files
ArtifactFormsArtifactForms
authored
Update README.md
1 parent d9d0ea0 commit cab8b4e

File tree

1 file changed

+300
-2
lines changed

1 file changed

+300
-2
lines changed

‎README.md‎

Lines changed: 300 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,305 @@
1-
# Readme
2-
31
[![Java CI with Maven](https://github.com/ArtifactForms/MeshLibCore/actions/workflows/maven.yml/badge.svg)](https://github.com/ArtifactForms/MeshLibCore/actions/workflows/maven.yml)
42
[![CodeQL Advanced](https://github.com/ArtifactForms/MeshLibCore/actions/workflows/codeql.yml/badge.svg)](https://github.com/ArtifactForms/MeshLibCore/actions/workflows/codeql.yml)
53
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/5d913b2c5d064bee83780eefee17f400)](https://app.codacy.com/gh/ArtifactForms/MeshLibCore/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
64
[![Maintainability](https://api.codeclimate.com/v1/badges/c860a89479fdedd6be77/maintainability)](https://codeclimate.com/github/ArtifactForms/MeshLibCore/maintainability)
75
[![Maven Package](https://github.com/ArtifactForms/MeshLibCore/actions/workflows/maven-publish.yml/badge.svg)](https://github.com/ArtifactForms/MeshLibCore/actions/workflows/maven-publish.yml)
6+
7+
# Artifact Forms
8+
9+
A _JAVA_ library to construct and manipulate geometry in Three-dimensional space.
10+
11+
## Background / Intension
12+
13+
This library is a hobby project started around 2015/2016 with the intension to learn more about
14+
creating and manipulating geometry in Three-dimensional space.
15+
I could build up on some small knowledge I gathered through my internship several years before.
16+
At this time I worked together with university students from the field of product design.
17+
This was also the time I got in touch with a programming language called 'Processing' for the first time. And I was hooked from day one.
18+
Processing is a language created with the intension to help people to learn programming in a visual context.
19+
If you are interested to find out more went to
20+
[processing.org](https://processing.org). But processing is not absolutely necessary, cause the core of the library is decoupled from the processing
21+
environment. Nevertheless processing provides a convenient way to display constructed meshes through it's rendering pipeline. Under the hood processing makes use of _JAVA_, _JAVA2D_ and _OPENGL_.
22+
23+
## Status Quo
24+
25+
At the current stage I mainly work on the user documentation. Over the years I learned new things about code structure and architecture, so codewise a lot of refactoring is going on to keep the project clean. And from time to time small additions are made. Meanwhile all the processing specific and rendering stuff lives in it's own repository. So this is another project to went on with.
26+
27+
Overall the code base is more a playground for working with _legacy code_. I try to love, work and live with legacy code.
28+
It offers the possibility to learn and try new testing approaches. Building tests around existing code for refactroing purposes is quite an interesting and useful field. And in my opinion indispensable.
29+
30+
## Future
31+
32+
There are a lot of corresponding topics out there. So my wishlist of things to learn and implement is unspeakably large.
33+
Some are already listed under 'Planed features'.
34+
35+
## Showcase
36+
37+
The following images are showing the library in action.
38+
39+
![](MeshLibCoreClean2022/documentation/images/lib_showcase_1.png)
40+
Subdivision is so beautiful and satisfying too look at.
41+
42+
![](MeshLibCoreClean2022/documentation/images/lib_showcase_2.png)
43+
bend bend bend mesh...
44+
45+
![](MeshLibCoreClean2022/documentation/images/lib_showcase_3.png)
46+
Throwing some conway operations on a cube seed.
47+
48+
## Features
49+
50+
Will be added soon...
51+
52+
## Core elements
53+
54+
- Mesh3D
55+
- Face3D
56+
- Edge3D
57+
- [Creators](#creators)
58+
- Modifiers
59+
60+
## Coordinate System
61+
62+
The library is build up on a left-handed coordinate system.
63+
The decision was justified by using the 'Processing' rendering pipeline in the first place.
64+
But the core library is highly decoupled from the 'Processing' environment.
65+
So the library could be used independently.
66+
67+
## Mesh3D
68+
69+
The following example shows how to work with the base mesh class. For this purpose we want to create a simple quad. The quad has four vertices, one for each
70+
corner. To make things a bit more explanatory we compose the quad out of two triangular faces. **Important:** This is just an example to illustrate the base concepts. The library already provides a convenient way to construct primitives and more complex shapes. But we dive into this at a later point. For now
71+
let's keep things simple. But also keep in mind that it might be useful to construct shapes by yourself in some cases.
72+
73+
```
74+
(-1, 0, -1) (1, 0, -1)
75+
o--------------o
76+
| . |
77+
| . |
78+
| . |
79+
| . |
80+
| . |
81+
o--------------o
82+
(-1, 0, 1) (1, 0, 1)
83+
```
84+
85+
### Mesh3D Object
86+
87+
The base class for all shapes is `mesh.Mesh3D`.
88+
89+
```java
90+
import mesh.Mesh3D;
91+
92+
Mesh3D mesh = new Mesh3D();
93+
```
94+
95+
### Vertex Coordinates
96+
97+
Next we determine the shape's coordinates in Three-Dimensional space. In this case the shape lies flat on the xz plane, so each y-coordinate is 0.0f.
98+
99+
```java
100+
mesh.add(new Vector3f(1, 0, -1));
101+
mesh.add(new Vector3f(1, 0, 1);
102+
mesh.add(new Vector3f(-1, 0, 1);
103+
mesh.add(new Vector3f(-1, 0, -1);
104+
```
105+
106+
Alternatively use `addVertex(x, y, z)`
107+
108+
```java
109+
mesh.addVertex(1, 0, -1);
110+
mesh.addVertex(1, 0, 1);
111+
mesh.addVertex(-1, 0, 1);
112+
mesh.addVertex(-1, 0, -1);
113+
```
114+
115+
### Construct Faces
116+
117+
The added vertices are now at an indexed position within the mesh.
118+
119+
```
120+
3 0
121+
o--------------o
122+
| . |
123+
| . |
124+
| . |
125+
| . |
126+
| . |
127+
o--------------o
128+
2 1
129+
```
130+
131+
Knowing the index of each vertex makes adding faces a piece of cake. We only have to take care of the winding order. In this case the winding order
132+
is counter-clockwise with all face normals pointing up towards negative y.
133+
134+
```java
135+
mesh.addFace(0, 1, 3);
136+
mesh.addFace(1, 2, 3);
137+
```
138+
139+
![](MeshLibCoreClean2022/documentation/images/quad_example.png)
140+
141+
### Modify the mesh
142+
143+
Now we have a mesh constisting of four vertices and two triangular faces. This could be retrieved by using:
144+
145+
```java
146+
int vertexCount = mesh.getVertexCount();
147+
int faceCount = mesh.getFaceCount();
148+
```
149+
150+
We can modify the present mesh by using so called _Modifiers_. Each modifier derives from the root interface `IMeshModifier`.
151+
152+
```java
153+
package mesh.modifier;
154+
155+
import mesh.Mesh3D;
156+
157+
public interface IMeshModifier {
158+
159+
public Mesh3D modify(Mesh3D mesh);
160+
161+
}
162+
```
163+
164+
Let's say we would like to give our mesh some thickness.
165+
To achieve this we use the _SolidifyModifier_.
166+
167+
```java
168+
SolidifyModifier modifier = new SolidifyModifier();
169+
modifier.setThickness(0.5f);
170+
modifier.modify(mesh);
171+
```
172+
173+
## Creators
174+
175+
The library provides a variety of so called mesh 'Creators' to construct various shapes the convenient way.
176+
More precisely the 'Factory Method' / 'Builder' pattern was applied for this purpose. A mesh creator works like a classis builder.
177+
The creator differs mainly in two points from a classic builder. We also provide getters and chaining was left out.
178+
In the meantime the library contains 100+ different mesh creators divided in various categories.
179+
Get a first impression and overview here: [Mesh Creators](https://github.com/ArtifactForms/MeshLibCoreClean2022/blob/master/MeshLibCoreClean2022/documentation/documentation.md).
180+
Each creator derives from the 'IMeshCreator' interface. The following code example shows the mentioned root interface for all mesh creators.
181+
182+
```java
183+
package mesh.creator;
184+
185+
import mesh.Mesh3D;
186+
187+
public interface IMeshCreator {
188+
189+
public Mesh3D create();
190+
191+
}
192+
```
193+
194+
To get a little more specific we can plug the quad example code into a custom creator to illustrate the overall concept.
195+
Let's have a look at our example code again.
196+
197+
```java
198+
import mesh.Mesh3D;
199+
import mesh.creator.IMeshCreator;
200+
201+
Mesh3D mesh = new Mesh3d();
202+
mesh.addVertex(1, 0, -1);
203+
mesh.addVertex(1, 0, 1);
204+
mesh.addVertex(-1, 0, 1);
205+
mesh.addVertex(-1, 0, -1);
206+
mesh.addFace(0, 1, 3);
207+
mesh.addFace(1, 2, 3);
208+
```
209+
210+
First we move our example code into the factory method of a custom mesh creator class and simply return the mesh.
211+
212+
```java
213+
import mesh.Mesh3D;
214+
import mesh.creator.IMeshCreator;
215+
216+
public class MyQuadCreator implements IMeshCreator {
217+
218+
public Mesh3D create() {
219+
Mesh3D mesh = new Mesh3d();
220+
mesh.addVertex(1, 0, -1);
221+
mesh.addVertex(1, 0, 1);
222+
mesh.addVertex(-1, 0, 1);
223+
mesh.addVertex(-1, 0, -1);
224+
mesh.addFace(0, 1, 3);
225+
mesh.addFace(1, 2, 3);
226+
return mesh;
227+
}
228+
229+
}
230+
```
231+
232+
Let's assume we want to generalize the code a bit further. We introduce a parameter for the vertex coordinates named _halfSize_.
233+
234+
```java
235+
import mesh.Mesh3D;
236+
237+
public class MyQuadCreator implements IMeshCreator {
238+
239+
private float halfSize;
240+
private Mesh3D mesh;
241+
242+
public Mesh3D create() {
243+
initializeMesh();
244+
createVertices();
245+
createFaces();
246+
return mesh;
247+
}
248+
249+
private void initializeMesh() {
250+
mesh = new Mesh3D();
251+
}
252+
253+
private void createVertices() {
254+
addVertex(halfSize, 0, -halfSize);
255+
addVertex(halfSize, 0, halfSize);
256+
addVertex(-halfSize, 0, halfSize);
257+
addVertex(-halfSize, 0, -halfSize);
258+
}
259+
260+
private void createFaces() {
261+
addFace(0, 1, 3);
262+
addFace(1, 2, 3);
263+
}
264+
265+
private void addVertex(float x, float y, float z) {
266+
mesh.addVertex(x, y, z);
267+
}
268+
269+
private void addFace(int... indices) {
270+
mesh.add(new Face3D(indices));
271+
}
272+
273+
public void setSize(float size) {
274+
halfSize = size / 2.0f;
275+
}
276+
277+
public float getSize() {
278+
return halfSize * 2;
279+
}
280+
281+
}
282+
```
283+
284+
Now we can use our creator the following way:
285+
286+
```java
287+
Mesh3D mesh;
288+
MyQuadCreator creator = new MyQuadCreator();
289+
creator.setSize(4);
290+
mesh = creator.create();
291+
```
292+
293+
This explains the overall concept of mesh creators pretty well. You should now have an idea how to use existing creators and implement your own custom ones.
294+
See also: [Mesh Creators](https://github.com/ArtifactForms/MeshLibCoreClean2022/blob/master/MeshLibCoreClean2022/documentation/documentation.md)
295+
296+
## Planed features
297+
298+
- Convex Hull
299+
- Poisson-Disc Sampling
300+
- Marching Cubes
301+
302+
## Licence
303+
304+
[MIT](https://github.com/ArtifactForms/MeshLibCore/blob/master/LICENSE) License Copyright (c) 2022 Simon Dietz
305+

0 commit comments

Comments
 (0)