[orx-force-2d] Add kdoc strings

Author: edwinRNDR

orx-force-2d/README.md

@@ -0,0 +1,3 @@
+# orx-force-2d
+
+Implements 2D XPBD for simulating physical forces. 

orx-force-2d/src/commonMain/kotlin/BodyAreaConstraint.kt

@@ -2,6 +2,19 @@ package org.openrndr.extra.force2d
 
 import org.openrndr.math.Vector2
 
+/**
+ * Represents a constraint that maintains a specified area for a deformable body.
+ *
+ * This class ensures that the area defined by the body's boundary remains close
+ * to a target rest area during simulation. The constraint is solved iteratively
+ * and includes compliance to allow some flexibility in maintaining the target area.
+ *
+ * @constructor Creates a BodyAreaConstraint for the specified body.
+ * @param body The deformable body whose area is constrained.
+ * @param compliance The compliance factor that governs the flexibility of the constraint.
+ *                   Higher values allow more deviation from the rest area.
+ * @param iterations The number of iterations for solving the constraint in each simulation step.
+ */
 class BodyAreaConstraint(val body: Body, var compliance: Double = 0.0, var iterations: Int = 1) : Constraint {
 
     var restArea: Double = area()
@@ -69,6 +82,14 @@ class BodyAreaConstraint(val body: Body, var compliance: Double = 0.0, var itera
     }
 }
 
+/**
+ * Adds a body area constraint to the body, ensuring that its area remains close
+ * to a target rest area during simulation. The constraint includes compliance
+ * and uses iterative solving to maintain this condition.
+ *
+ * @param configure A lambda function used to configure the `BodyAreaConstraint`
+ *                  instance before it is added to the body's constraints list.
+ */
 fun Body.bodyAreaConstraint(configure : BodyAreaConstraint.() -> Unit = {}) {
     constraints.add(BodyAreaConstraint(this).apply(configure))
 }

orx-force-2d/src/commonMain/kotlin/BoundaryNodeRelaxForce.kt

@@ -1,5 +1,19 @@
 package org.openrndr.extra.force2d
 
+/**
+ * BoundaryNodeRelaxForce is a type of force that acts on the boundary nodes of a [Body].
+ * It aims to relax the boundary nodes by adjusting their velocities based on neighboring node positions.
+ * Each boundary node is influenced by the midpoint of its neighboring boundary nodes, providing a smoothing effect.
+ *
+ * @property strength Controls the intensity of the relaxation force. A higher strength results in greater adjustment of the node velocities.
+ *
+ * This force operates frame-by-frame:
+ * 1. In each frame, the [apply] method computes the velocity correction for each boundary node.
+ * 2. The correction is calculated by determining the difference between the node's current position and the midpoint of its neighboring nodes.
+ * 3. The computed difference is scaled by the time step `dt` and the `strength` property, then added to the node's velocity.
+ *
+ * The force assumes a cyclic relationship between boundary nodes, where the first and last nodes are neighbors.
+ */
 class BoundaryNodeRelaxForce : Force {
 
     var strength = 1.0
@@ -20,5 +34,13 @@ class BoundaryNodeRelaxForce : Force {
     }
 }
 
+/**
+ * Adds a [BoundaryNodeRelaxForce] to the [Body]'s list of forces.
+ * This force acts on the boundary nodes of the body to relax their positions
+ * by adjusting their velocities based on neighboring node positions.
+ *
+ * @param configure A lambda configuration function for the [BoundaryNodeRelaxForce].
+ *                  Use this to set properties such as `strength` to customize force behavior.
+ */
 fun Body.boundaryNodeRelaxForce(configure: BoundaryNodeRelaxForce.() -> Unit) =
     forces.add(BoundaryNodeRelaxForce().apply(configure))

orx-force-2d/src/commonMain/kotlin/ContourToBlob.kt

@@ -2,6 +2,21 @@ package org.openrndr.extra.force2d
 import org.openrndr.math.Vector2
 import org.openrndr.shape.ShapeContour
 
+
+/**
+ * Converts a given shape contour into a physical body representation with configurable nodes and links.
+ *
+ * The function creates a series of nodes based on equidistant positions along the contour
+ * and connects them using links to form a flexible structure. Additional neighbor links can
+ * be added for increased connectivity. The resulting [Body] can be further configured
+ * using the provided [configure] block.
+ *
+ * @param contour the shape contour to be converted into a physical body representation.
+ * @param density the density of nodes along the contour, defining the spacing between nodes. Default is 10.0.
+ * @param linkNeighbors the number of additional neighboring links to create for each node. Default is 1.
+ * @param configure a lambda to configure the resulting [Body] instance.
+ * @return a [Body] instance representing the given contour with nodes and links.
+ */
 fun contourToBody(contour: ShapeContour, density: Double = 10.0, linkNeighbors: Int = 1, configure: Body.() -> Unit = {}): Body {
     val points = contour.equidistantPositions((contour.length / density).toInt())
 

orx-force-2d/src/commonMain/kotlin/ForceSimulation.kt

@@ -5,6 +5,22 @@ import org.openrndr.shape.Rectangle
 import kotlin.coroutines.CoroutineContext
 import kotlin.math.abs
 
+/**
+ * Represents a single physical node with position, velocity, and related properties.
+ *
+ * A node serves as an element in simulations, with attributes including its current position,
+ * previous position, velocity, inverse mass, radius, and a unique identifier. These properties
+ * define the motion and interaction of the node with forces or other nodes in the simulation.
+ *
+ * @property position the current position of the node in the simulation space.
+ * @property prevPosition the position of the node in the previous simulation step.
+ * @property velocity the current velocity of the node.
+ * @property inverseMass the reciprocal of the node's mass. A value of 0 represents an immovable object,
+ * while higher values represent lower mass.
+ * @property radius the radius of the node, used for interactions or spatial calculations.
+ * @property id an optional unique identifier for the node. Default is 0.
+ * @property bounds a bounding rectangle centered around the node, with dimensions based on its radius.
+ */
 class Node(
     var position: Vector2,
     var prevPosition: Vector2,
@@ -18,12 +34,43 @@ class Node(
 
 }
 
+/**
+ * Represents a connection or relationship between two [Node]s, identified by their indices.
+ *
+ * This class is primarily used to model a connection between two nodes or objects in a system,
+ * such as a physical simulation or graph structure. The `source` and `target` properties represent
+ * the indices of the connected nodes.
+ *
+ * @property source the index of the source node.
+ * @property target the index of the target node.
+ */
 class Link(
     var source: Int,
     var target: Int,
 )
 
+/**
+ * Represents a triangle defined by three node indices in a physical simulation.
+ *
+ * A Triangle is primarily used to perform calculations related to its geometry,
+ * such as computing its signed area based on the positions of nodes in a given list.
+ *
+ * @constructor Creates a Triangle with indices pointing to nodes in a list.
+ * @param a the index of the first node in the triangle.
+ * @param b the index of the second node in the triangle.
+ * @param c the index of the third node in the triangle.
+ */
 class Triangle(var a: Int, var b: Int, var c: Int) {
+
+    /**
+     * Computes the signed area of the triangle defined by the nodes referenced in this triangle.
+     * The signed area is positive if the nodes are ordered counterclockwise,
+     * and negative if they are ordered clockwise.
+     *
+     * @param nodes a list of [Node] objects where this triangle's node indices correspond to the nodes in the list.
+     * Each [Node] must have a valid position.
+     * @return the signed area of the triangle defined by the referenced nodes.
+     */
     fun signedArea(nodes: List<Node>): Double {
         val p0 = nodes[a].position
         val p1 = nodes[b].position
@@ -34,30 +81,99 @@ class Triangle(var a: Int, var b: Int, var c: Int) {
     }
 }
 
+/**
+ * Represents a constraint in a physical system, which influences the behavior of a [Body].
+ *
+ * A [Constraint] typically applies rules or restrictions to the motion or interaction of
+ * the elements within a [Body]. This can include conditions like maintaining distances
+ * between points, restricting movement to certain boundaries, or other physical interactions.
+ */
 interface Constraint {
     suspend fun initialize()
+
+    /**
+     * Resolves constraints and updates the state of nodes within the given physical body over a time step.
+     *
+     * This method applies all constraints associated with the [Body], ensuring that the system adheres
+     * to the defined physical rules. For example, constraints might enforce distance limitations,
+     * maintain structural rigidity, or apply boundary conditions. It leverages the constraint-solving
+     * functionality for the provided time interval, potentially resulting in updated positions or states
+     * of the body's components.
+     *
+     * @param body the [Body] whose constraints are to be resolved, representing the physical system.
+     * @param dt the duration of the time step during which the constraints are solved, expressed in seconds.
+     */
     suspend fun solve(body: Body, dt: Double)
 }
 
+/**
+ * Represents a physical force that can be applied to a [Body] in a simulation.
+ *
+ * Implementing classes define specific behaviors for initializing and
+ * applying forces on the [Body], altering the state of its nodes over time.
+ */
 interface Force {
     suspend fun initializeFrame(body: Body)
     suspend fun apply(body: Body, dt: Double)
 }
 
+/**
+ * Interface representing a force interaction between two physical bodies in a simulation.
+ *
+ * Implementations of this interface define the logic for detecting overlapping pairs of bodies,
+ * initializing frames for force calculations, and applying interbody forces during simulation steps.
+ */
 interface InterbodyForce {
     suspend fun initializeFrame()
     suspend fun findOverlappingPairs(bodies: List<Body>): List<Pair<Int, Int>>
     suspend fun apply(body: Body, other: Body, dt: Double, substep: Int)
 }
 
+/**
+ * An interface representing a constraint that resolves collisions between two bodies in a simulation.
+ *
+ * Implementations of this interface must define the logic for resolving collisions between the specified
+ * [body] and [other] based on their physical properties, positions, and velocities. This process
+ * ensures that the bodies interact realistically while respecting the constraints defined for the simulation.
+ *
+ * The [solve] method is called with a time step [dt] to calculate and apply necessary adjustments to
+ * the bodies involved in the collision.
+ */
 interface CollisionConstraint {
     suspend fun solve(body: Body, other: Body, dt: Double)
 }
 
+/**
+ * Interface for detecting broad-phase collisions in a physics simulation.
+ *
+ * The broad-phase collision detector is responsible for identifying potential overlapping
+ * pairs of bodies in a physics simulation. It typically uses efficient spatial partitioning
+ * or bounding volume techniques to narrow down the list of potential collisions from
+ * a large number of bodies.
+ */
 interface BroadPhaseCollisionDetector {
     suspend fun findOverlappingPairs(bodies: List<Body>): List<Pair<Int, Int>>
 }
 
+/**
+ * Represents a physical body in a simulation composed of nodes, links, and triangles.
+ *
+ * A [Body] serves as the central structure in simulations, encapsulating physical properties,
+ * relationships, and behaviors of its constituent parts. It supports initialization,
+ * integration of forces, resolution of constraints, and updates to its boundaries.
+ * The body can either be static or dynamic, depending on the `static` property.
+ *
+ * @property nodes the list of [Node]s that make up the physical body.
+ * @property boundaryNodes the list of indices referring to nodes considered as boundary nodes.
+ * @property links the list of [Link]s that define relationships or connections between nodes.
+ * @property boundaryLinks the list of indices referring to links considered as boundary links.
+ * @property triangles the list of [Triangle]s used for structural and mass-related calculations.
+ * @property inverseBodyMass the reciprocal of the total mass of the body, used in weight calculations.
+ * @property static a flag indicating whether the body is static (non-movable) or dynamic.
+ * @property forces the list of [Force]s acting on the body in the simulation.
+ * @property constraints the list of [Constraint]s influencing the behavior and interaction of the body.
+ * @property bounds the bounding rectangle that encapsulates the body's nodes, updated automatically.
+ */
 class Body(
     val nodes: List<Node>,
     val boundaryNodes: List<Int> = emptyList(),
@@ -145,6 +261,26 @@ class Body(
     }
 }
 
+/**
+ * Represents a physics simulation of interacting bodies.
+ *
+ * The [ForceSimulation] class provides the infrastructure to simulate the dynamics
+ * of a system of bodies under the influence of forces and constraints. It supports
+ * customizable interbody forces, collision detection, and resolution, allowing for
+ * a wide variety of physical interactions.
+ *
+ * @property bodies The list of [Body] objects participating in the simulation. Each body
+ * has its own properties, forces, and constraints that determine its behavior.
+ * @property broadPhaseCollisionDetector The collision detection algorithm used to identify
+ * potential overlapping pairs of bodies during the simulation. It operates in the broad-phase
+ * stage of collision resolution.
+ * @property collisionConstraint The collision resolution handler responsible for determining
+ * the outcome of detected collisions between bodies.
+ * @property interbodyForces A list of interbody forces that affect pairs of bodies in the simulation.
+ * These forces are computed per pair of bodies and influence their dynamics.
+ * @property context The coroutine context in which the simulation runs, allowing for asynchronous
+ * computations. By default, it uses [Dispatchers.Default].
+ */
 class ForceSimulation(val bodies: MutableList<Body> = mutableListOf()) {
 
     var broadPhaseCollisionDetector: BroadPhaseCollisionDetector? = null

orx-force-2d/src/commonMain/kotlin/GravityForce.kt

@@ -1,6 +1,22 @@
 package org.openrndr.extra.force2d
 import org.openrndr.math.Vector2
 
+/**
+ * Represents a constant gravitational force applied to a physical body in a simulation.
+ *
+ * The `GravityForce` class is a specific implementation of the [Force] interface.
+ * It applies a constant acceleration, defined by the `gravity` vector, to all nodes
+ * of the body over time. The force is applied during every simulation frame,
+ * updating the velocity of the nodes based on the gravitational vector and the elapsed time step.
+ *
+ * @property gravity the gravitational acceleration vector applied to the body.
+ * Default value is [Vector2.ZERO], indicating no gravity unless explicitly configured.
+ *
+ * The `initializeFrame` method is a placeholder in this implementation and does not perform any initialization logic.
+ *
+ * The `apply` method applies the gravitational force by calculating the change in velocity
+ * for each node in the body. It updates the velocity of each node over the given time step, `dt`.
+ */
 class GravityForce : Force {
     var gravity = Vector2.ZERO
 
@@ -14,6 +30,21 @@ class GravityForce : Force {
     }
 }
 
+/**
+ * Adds a gravitational force to the body and allows configuring its properties.
+ *
+ * This method attaches a new instance of [GravityForce] to the body, applying a constant
+ * gravitational acceleration defined in the configuration block. The force affects all
+ * nodes in the body during simulation steps.
+ *
+ * @param configure a lambda to configure the properties of the [GravityForce] instance,
+ * such as setting the gravitational acceleration vector.
+ */
 fun Body.gravity(configure: GravityForce.() -> Unit) = forces.add(GravityForce().apply(configure))
 
+/**
+ * Applies a gravitational force to the body by adding it to the list of forces acting on the body.
+ *
+ * @param gravity the gravitational force to be applied, represented as a [GravityForce] instance.
+ */
 fun Body.gravity(gravity: GravityForce) = forces.add(gravity)

orx-force-2d/src/commonMain/kotlin/LinkLengthConstraint.kt

@@ -1,6 +1,23 @@
 package org.openrndr.extra.force2d
 
-class LinkLengthConstraint( val body: Body, var compliance: Double = 0.0, var iterations: Int = 1) :
+/**
+ * A constraint that enforces the lengths of links between nodes within a [Body].
+ *
+ * The [LinkLengthConstraint] ensures that links connecting nodes in the [Body] adhere to their
+ * defined rest lengths. It computes corrections over a number of iterations to resolve any
+ * deviations in length while considering compliance, which introduces flexibility into the system.
+ *
+ * @property body the [Body] that this constraint operates on.
+ * @property compliance a parameter controlling the flexibility of the links. Higher compliance
+ * allows greater deviation from the rest lengths.
+ * @property iterations the number of iterations to refine the resolution of the constraint for
+ * each time step.
+ *
+ * This constraint works by computing the deviation of each link's current length from its rest
+ * length and applying corrective forces iteratively to the connected nodes. It takes into
+ * account the mass of the nodes and compliance to distribute corrections appropriately.
+ */
+class LinkLengthConstraint(val body: Body, var compliance: Double = 0.0, var iterations: Int = 1) :
     Constraint {
 
     private var lambdas: DoubleArray = DoubleArray(body.links.size)
@@ -48,6 +65,6 @@ class LinkLengthConstraint( val body: Body, var compliance: Double = 0.0, var it
     }
 }
 
-fun Body.linkLengthConstraint(configure : LinkLengthConstraint.() -> Unit = {}) {
+fun Body.linkLengthConstraint(configure: LinkLengthConstraint.() -> Unit = {}) {
     constraints.add(LinkLengthConstraint(this).apply(configure))
 }