updated README + documentation

README.md

@@ -33,32 +33,62 @@ integrators are used to integrate acceleration and velocity to calculate the new
 
 ## anatomy of a particle
 
-![](./resources/teilchen-tutorial-01.png)
+![](./resources/teilchen-tutorial-particles-01.png)
 
-![](./resources/teilchen-tutorial-02.png)
+![](./resources/teilchen-tutorial-particles-02.png)
 
-![](./resources/teilchen-tutorial-03.png)
+![](./resources/teilchen-tutorial-particles-03.png)
 
-![](./resources/teilchen-tutorial-04.png)
+![](./resources/teilchen-tutorial-particles-04.png)
 
 ## moving a particle ( with forces )
 
-![](./resources/teilchen-tutorial-05.png)
+![](./resources/teilchen-tutorial-particles-05.png)
 
-![](./resources/teilchen-tutorial-06.png)
+![](./resources/teilchen-tutorial-particles-06.png)
 
-![](./resources/teilchen-tutorial-07.png)
+![](./resources/teilchen-tutorial-particles-07.png)
 
-![](./resources/teilchen-tutorial-08.png)
+![](./resources/teilchen-tutorial-particles-08.png)
 
-![](./resources/teilchen-tutorial-09.png)
+![](./resources/teilchen-tutorial-particles-09.png)
 
-![](./resources/teilchen-tutorial-10.png)
+![](./resources/teilchen-tutorial-particles-10.png)
 
-![](./resources/teilchen-tutorial-11.png)
+![](./resources/teilchen-tutorial-particles-11.png)
 
-![](./resources/teilchen-tutorial-12.png)
+![](./resources/teilchen-tutorial-particles-12.png)
 
 ## reference
 
 generated [reference](http://dennisppaul.github.io/teilchen/) of the library
+
+## vectors
+
+although explaining vectors ( and linear algebra ) is beyond the scope of this library, it can be very helpful to understand the basics of vector operations. the following slides aim to explain a few basics:
+
+![](./resources/teilchen-tutorial-vectors-01.png)
+
+![](./resources/teilchen-tutorial-vectors-02.png)
+
+![](./resources/teilchen-tutorial-vectors-03.png)
+
+![](./resources/teilchen-tutorial-vectors-04.png)
+
+![](./resources/teilchen-tutorial-vectors-05.png)
+
+![](./resources/teilchen-tutorial-vectors-06.png)
+
+![](./resources/teilchen-tutorial-vectors-07.png)
+
+![](./resources/teilchen-tutorial-vectors-08.png)
+
+![](./resources/teilchen-tutorial-vectors-09.png)
+
+![](./resources/teilchen-tutorial-vectors-10.png)
+
+![](./resources/teilchen-tutorial-vectors-11.png)
+
+![](./resources/teilchen-tutorial-vectors-12.png)
+
+![](./resources/teilchen-tutorial-vectors-13.png)

REVISIONS.md → RELEASE_NOTES.md

@@ -1,7 +1,5 @@
 # teilchen / revisions
 
-## v0.5 (pre-release)
-
 ## v0.4 (20200616)
 
 - particles, contraints and forces can now be marked `dead` and are automatically disposed when calling `Physics.step()` or `Physics.purge()`

docs/index-files/index-16.html

@@ -123,8 +123,7 @@ <h2 class="title">R</h2>
 <dd>&nbsp;</dd>
 <dt><span class="memberNameLink"><a href="../teilchen/util/Util.html#randomize(processing.core.PVector)">randomize(PVector)</a></span> - Static method in class teilchen.util.<a href="../teilchen/util/Util.html" title="class in teilchen.util">Util</a></dt>
 <dd>
-<div class="block">Sets a position randomly distributed inside a sphere of unit radius
- centered at the origin.</div>
+<div class="block">Sets a position randomly distributed inside a sphere of unit radius centered at the origin.</div>
 </dd>
 <dt><span class="memberNameLink"><a href="../teilchen/force/VectorField.html#randomize_forces(float)">randomize_forces(float)</a></span> - Method in class teilchen.force.<a href="../teilchen/force/VectorField.html" title="class in teilchen.force">VectorField</a></dt>
 <dd>&nbsp;</dd>

docs/index-files/index-7.html

@@ -107,8 +107,7 @@ <h2 class="title">G</h2>
 <dd>&nbsp;</dd>
 <dt><span class="memberNameLink"><a href="../teilchen/util/Random.html#getFloat(float,float)">getFloat(float, float)</a></span> - Method in class teilchen.util.<a href="../teilchen/util/Random.html" title="class in teilchen.util">Random</a></dt>
 <dd>
-<div class="block">return a random float value from theStart to theEnd, excluding both
- values.</div>
+<div class="block">return a random float value from theStart to theEnd, excluding both values.</div>
 </dd>
 <dt><span class="memberNameLink"><a href="../teilchen/util/Random.html#getInt()">getInt()</a></span> - Method in class teilchen.util.<a href="../teilchen/util/Random.html" title="class in teilchen.util">Random</a></dt>
 <dd>&nbsp;</dd>

docs/overview-summary.html

@@ -2,7 +2,7 @@
 <!-- NewPage -->
 <html lang="en">
 <head>
-<!-- Generated by javadoc (11.0.10) on Wed Jan 27 11:48:07 CET 2021 -->
+<!-- Generated by javadoc (11.0.10) on Thu Apr 28 17:31:10 CEST 2022 -->
 <title>Generated Documentation (Untitled)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <script type="text/javascript">window.location.replace('index.html')</script>

docs/teilchen/util/DrawLib.html

@@ -464,7 +464,7 @@ <h4>draw</h4>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>g</code> - PGraphics</dd>
-<dd><code>theWorldAxisAlignedBoundingBox</code> - WorldAxisAlignedBoundingBox</dd>
+<dd><code>pWorldAxisAlignedBoundingBox</code> - WorldAxisAlignedBoundingBox</dd>
 <dd><code>pColor</code> - int</dd>
 </dl>
 </li>
@@ -488,8 +488,8 @@ <h4>draw</h4>
 <dd><code>a</code> - PVector</dd>
 <dd><code>b</code> - PVector</dd>
 <dd><code>c</code> - PVector</dd>
-<dd><code>theTriangleColor</code> - int</dd>
-<dd><code>theNormalColor</code> - int</dd>
+<dd><code>pTriangleColor</code> - int</dd>
+<dd><code>pNormalColor</code> - int</dd>
 </dl>
 </li>
 </ul>

docs/teilchen/util/Intersection.html

@@ -474,9 +474,9 @@ <h4>intersectLinePlane</h4>
 <div class="block">intersect line with plane ( grabbed from Xith )</div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
-<dd><code>thePlane</code> - Plane3f</dd>
-<dd><code>theRay</code> - Ray3f</dd>
-<dd><code>theIntersectionPoint</code> - PVector</dd>
+<dd><code>pPlane</code> - Plane3f</dd>
+<dd><code>pRay</code> - Ray3f</dd>
+<dd><code>pIntersectionPoint</code> - PVector</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>float</dd>
 </dl>

docs/teilchen/util/Random.html

@@ -137,9 +137,8 @@ <h2 title="Class Random" class="title">Class Random</h2>
 extends java.lang.Object
 implements java.io.Serializable</pre>
 <div class="block">generate random numbers.
-
- note that if different types are requested the random generator moves on
- anyway.</div>
+ <p>
+ note that if different types are requested the random generator moves on anyway.</div>
 <dl>
 <dt><span class="seeLabel">See Also:</span></dt>
 <dd><a href="../../serialized-form.html#teilchen.util.Random">Serialized Form</a></dd>
@@ -205,8 +204,7 @@ <h3>Method Summary</h3>
 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getFloat(float,float)">getFloat</a></span>&#8203;(float&nbsp;pStart,
         float&nbsp;pEnd)</code></th>
 <td class="colLast">
-<div class="block">return a random float value from theStart to theEnd, excluding both
- values.</div>
+<div class="block">return a random float value from theStart to theEnd, excluding both values.</div>
 </td>
 </tr>
 <tr id="i3" class="rowColor">
@@ -336,8 +334,8 @@ <h4>getInt</h4>
 <div class="block">return a random int value from theStart to theEnd, including both values.</div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
-<dd><code>theStart</code> - int</dd>
-<dd><code>theEnd</code> - int</dd>
+<dd><code>pStart</code> - int</dd>
+<dd><code>pEnd</code> - int</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>int</dd>
 </dl>
@@ -360,12 +358,11 @@ <h4>getInt</h4>
 <h4>getFloat</h4>
 <pre class="methodSignature">public&nbsp;float&nbsp;getFloat&#8203;(float&nbsp;pStart,
                       float&nbsp;pEnd)</pre>
-<div class="block">return a random float value from theStart to theEnd, excluding both
- values.</div>
+<div class="block">return a random float value from theStart to theEnd, excluding both values.</div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
-<dd><code>theStart</code> - float</dd>
-<dd><code>theEnd</code> - float</dd>
+<dd><code>pStart</code> - float</dd>
+<dd><code>pEnd</code> - float</dd>
 <dt><span class="returnLabel">Returns:</span></dt>
 <dd>float</dd>
 </dl>

docs/teilchen/util/Util.html

@@ -387,8 +387,7 @@ <h3>Method Summary</h3>
 <td class="colFirst"><code>static void</code></td>
 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#randomize(processing.core.PVector)">randomize</a></span>&#8203;(processing.core.PVector&nbsp;p)</code></th>
 <td class="colLast">
-<div class="block">Sets a position randomly distributed inside a sphere of unit radius
- centered at the origin.</div>
+<div class="block">Sets a position randomly distributed inside a sphere of unit radius centered at the origin.</div>
 </td>
 </tr>
 <tr id="i33" class="rowColor">
@@ -597,7 +596,7 @@ <h4>calculateNormal</h4>
 <dd><code>pointA</code> - point A</dd>
 <dd><code>pointB</code> - point B</dd>
 <dd><code>pointC</code> - point C</dd>
-<dd><code>theResultNormal</code> - normal</dd>
+<dd><code>pResultNormal</code> - normal</dd>
 </dl>
 </li>
 </ul>
@@ -612,9 +611,9 @@ <h4>calculateNormal</h4>
                                    processing.core.PVector&nbsp;pResultNormal)</pre>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
-<dd><code>theVectorAB</code> - vector AB</dd>
-<dd><code>theVectorBC</code> - vector BC</dd>
-<dd><code>theResultNormal</code> - normal</dd>
+<dd><code>pVectorAB</code> - vector AB</dd>
+<dd><code>pVectorBC</code> - vector BC</dd>
+<dd><code>pResultNormal</code> - normal</dd>
 </dl>
 </li>
 </ul>
@@ -625,9 +624,8 @@ <h4>calculateNormal</h4>
 <li class="blockList">
 <h4>randomize</h4>
 <pre class="methodSignature">public static&nbsp;void&nbsp;randomize&#8203;(processing.core.PVector&nbsp;p)</pre>
-<div class="block">Sets a position randomly distributed inside a sphere of unit radius
- centered at the origin. Orientation will be random and length will range
- between 0 and 1</div>
+<div class="block">Sets a position randomly distributed inside a sphere of unit radius centered at the origin. Orientation will be
+ random and length will range between 0 and 1</div>
 <dl>
 <dt><span class="paramLabel">Parameters:</span></dt>
 <dd><code>p</code> - randomized vector</dd>

src/teilchen/util/DrawLib.java

@@ -49,9 +49,9 @@ public static void drawAttractor(final PGraphics g,
     /**
      * draw attractors.
      *
-     * @param g           PGraphics
+     * @param g          PGraphics
      * @param mAttractor Attractor
-     * @param pColor      int
+     * @param pColor     int
      */
     public static void draw(final PGraphics g, final Attractor mAttractor, int pColor) {
         g.sphereDetail(6);
@@ -187,9 +187,9 @@ public static void draw(final PGraphics g,
     /**
      * draw buunding box.
      *
-     * @param g                              PGraphics
-     * @param theWorldAxisAlignedBoundingBox WorldAxisAlignedBoundingBox
-     * @param pColor                         int
+     * @param g                            PGraphics
+     * @param pWorldAxisAlignedBoundingBox WorldAxisAlignedBoundingBox
+     * @param pColor                       int
      */
     public static void draw(final PGraphics g,
                             final WorldAxisAlignedBoundingBox pWorldAxisAlignedBoundingBox,
@@ -208,12 +208,12 @@ public static void draw(final PGraphics g,
     /**
      * draw a triangle with a normal
      *
-     * @param g                PGraphics
-     * @param a                PVector
-     * @param b                PVector
-     * @param c                PVector
-     * @param theTriangleColor int
-     * @param theNormalColor   int
+     * @param g              PGraphics
+     * @param a              PVector
+     * @param b              PVector
+     * @param c              PVector
+     * @param pTriangleColor int
+     * @param pNormalColor   int
      */
     public static void draw(final PGraphics g,
                             final PVector a, final PVector b, final PVector c,
@@ -249,19 +249,19 @@ public static void cross2(final PGraphics g,
                               final PVector pPosition,
                               float pSize) {
         g.line(
-                pPosition.x + pSize,
-                pPosition.y + pSize,
-                pPosition.z,
-                pPosition.x - pSize,
-                pPosition.y - pSize,
-                pPosition.z);
+        pPosition.x + pSize,
+        pPosition.y + pSize,
+        pPosition.z,
+        pPosition.x - pSize,
+        pPosition.y - pSize,
+        pPosition.z);
         g.line(
-                pPosition.x + pSize,
-                pPosition.y - pSize,
-                pPosition.z,
-                pPosition.x - pSize,
-                pPosition.y + pSize,
-                pPosition.z);
+        pPosition.x + pSize,
+        pPosition.y - pSize,
+        pPosition.z,
+        pPosition.x - pSize,
+        pPosition.y + pSize,
+        pPosition.z);
     }
 
     public static void cross3(final PGraphics g,

src/teilchen/util/Intersection.java

@@ -248,9 +248,9 @@ public static boolean intersectRayTriangle(final PVector pRayOrigin,
     /**
      * intersect line with plane ( grabbed from Xith )
      *
-     * @param thePlane             Plane3f
-     * @param theRay               Ray3f
-     * @param theIntersectionPoint PVector
+     * @param pPlane             Plane3f
+     * @param pRay               Ray3f
+     * @param pIntersectionPoint PVector
      * @return float
      */
     public static float intersectLinePlane(final Ray3f pRay,
@@ -415,7 +415,8 @@ public static boolean RaySphere(PVector pP1, PVector pP2, PVector pSphereCenter,
         dp.y = pP2.y - pP1.y;
         dp.z = pP2.z - pP1.z;
         a = dp.x * dp.x + dp.y * dp.y + dp.z * dp.z;
-        b = 2 * (dp.x * (pP1.x - pSphereCenter.x) + dp.y * (pP1.y - pSphereCenter.y) + dp.z * (pP1.z - pSphereCenter.z));
+        b =
+        2 * (dp.x * (pP1.x - pSphereCenter.x) + dp.y * (pP1.y - pSphereCenter.y) + dp.z * (pP1.z - pSphereCenter.z));
         c = pSphereCenter.x * pSphereCenter.x + pSphereCenter.y * pSphereCenter.y + pSphereCenter.z * pSphereCenter.z;
         c += pP1.x * pP1.x + pP1.y * pP1.y + pP1.z * pP1.z;
         c -= 2 * (pSphereCenter.x * pP1.x + pSphereCenter.y * pP1.y + pSphereCenter.z * pP1.z);

src/teilchen/util/Random.java

@@ -22,17 +22,17 @@
  */
 package teilchen.util;
 
-import java.io.Serializable;
 import processing.core.PVector;
 
+import java.io.Serializable;
+
 /**
  * generate random numbers.
- *
- * note that if different types are requested the random generator moves on
- * anyway.
+ * <p>
+ * note that if different types are requested the random generator moves on anyway.
  */
 public class Random
-        implements Serializable {
+implements Serializable {
 
     private static final long serialVersionUID = -5871934750136232555L;
 
@@ -69,9 +69,8 @@ public void setSeed(long pSeed) {
     /**
      * return a random int value from theStart to theEnd, including both values.
      *
-     * @param theStart int
-     * @param theEnd   int
-     *
+     * @param pStart int
+     * @param pEnd   int
      * @return int
      */
     public int getInt(int pStart,
@@ -85,12 +84,10 @@ public int getInt() {
     }
 
     /**
-     * return a random float value from theStart to theEnd, excluding both
-     * values.
-     *
-     * @param theStart float
-     * @param theEnd   float
+     * return a random float value from theStart to theEnd, excluding both values.
      *
+     * @param pStart float
+     * @param pEnd   float
      * @return float
      */
     public float getFloat(float pStart,
@@ -104,7 +101,7 @@ public float getFloat() {
         return mRandomNumberGenerator.nextFloat();
     }
 
-//    public static float getFloat(float theStart,
+    //    public static float getFloat(float theStart,
 //                                 float theEnd) {
 //        return mSeedGenerator.getFloat(theStart, theEnd);
 //    }