Module

Hylograph.Forces.Contain

Package
purescript-hylograph-forces
Repository
afcondon/purescript-hylograph-forces

Containment: keep each node inside a region. A soft force steers a node back in before the nodes move; an optional hard confine puts it back in after they have.

Not in d3. The rules are the Rust kernel's (Region::project, apply_contain and constrain in force-kernel/src/forces.rs), and the two are held to each other bit for bit by test/differential.mjs.

The body. A node is kept inside as a rectangle of half-width w and half-height h, grown all round by a radius r: a circle when w and h are zero, a plain rectangle when r is, a rounded rectangle otherwise.

Projection. project region r w h x y is where such a body centred on (x, y) has to move its centre to, to lie inside the region. A centre already far enough inside comes back unchanged.

  • Rectangle: clamp x to [x0 + (r + w), x1 - (r + w)] and y to [y0 + (r + h), y1 - (r + h)]. If the rectangle is narrower than the body on an axis, that coordinate goes to the middle of the rectangle.
  • Circle: the body counts as the circle round it, of radius r + sqrt(w*w + h*h) (exact for a round body, a little cautious for a rectangle). With R' = max(R - r - sqrt(w*w + h*h), 0), a centre further than R' from the region's centre c moves to c + (p - c) * (R' / |p - c|).
  • Convex polygon: one pass visits the edges in order; for each, with inward unit normal n and d the signed distance from the centre (as it now is) to the edge's line, positive inside, the body reaches s = (r + |n.x| * w) + |n.y| * h towards the edge, and a centre with d < s moves along the normal by s - d. Passes repeat until one moves nothing, eight at most.

Soft. For every node with a region, with a = position + velocity finite and c = project region r w h a: v += (c - a) * strength. Not scaled by alpha: it is a constraint, like collide.

Hard. After the nodes have moved, every node with a region and a finite position is put at project region r w h position, and its velocity changes by the same amount, so that the velocity is still the step the node actually took. Pinned coordinates are then put back: a pin beats a region.

#Region Source

data Region

A region nodes can be confined to. A polygon is held as its edges: a point on each and the edge's inward unit normal, in the order the vertices were given.

#rectangle Source

rectangle :: Number -> Number -> Number -> Number -> Region

The rectangle with these two corners, in either order.

#circle Source

circle :: Number -> Number -> Number -> Region

The circle about (x, y).

#polygon Source

polygon :: Array { x :: Number, y :: Number } -> Region

A convex polygon from its vertices, in either winding. Convexity is the caller's promise and is not checked. Fewer than three vertices, or zero area, gives a polygon with no edges, which confines nothing. An edge of zero length is left out.

#project Source

project :: Region -> Number -> Number -> Number -> Number -> Number -> { x :: Number, y :: Number }

Where a body (radius, half-width, half-height) centred on (x, y) has to move its centre to, to lie inside the region.

#Confinement Source

data Confinement

Whether a node is confined, and to what.

#free Source

free :: Confinement

Not confined.

#within Source

within :: Region -> Confinement

Confined to this region.

#Config Source

type Config :: Row Type -> Typetype Config row = { halfHeight :: Node row -> Number, halfWidth :: Node row -> Number, hard :: Boolean, radius :: Node row -> Number, region :: Node row -> Confinement, strength :: Number }

region, radius, halfWidth and halfHeight are asked once per node when the force is initialized; NaN for any of the three sizes counts as zero. strength is the soft force's (zero turns it off); hard adds the confine after the nodes move.

#Contain Source

newtype Contain :: Row Type -> Typenewtype Contain row

An initialized containment.

#initialize Source

initialize :: forall row. Config row -> Array (Node row) -> Contain row

#apply Source

apply :: forall row. Contain row -> Effect Unit

The soft part, applied with the forces.

#isHard Source

isHard :: forall row. Contain row -> Boolean

Whether this containment clamps after the nodes move.

#constrain Source

constrain :: forall row. Contain row -> Effect Unit

The hard part, applied after the nodes have moved; nothing unless the containment is hard. The velocity is written first, from the position as it still is, and then the position.