Module

Hylograph.Forces.Directional

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

The directional link constraint: keep each link's target at least a gap beyond its source along an axis (children below their parents).

Not in d3. The rule is the Rust kernel's (apply_directional in force-kernel/src/forces.rs), and the two are held to each other bit for bit by test/differential.mjs.

With u the unit axis, and working on anticipated positions a = position + velocity, for each iteration and each link in order, reading the velocities as the links before it left them:

d = (a_target - a_source) . u
if d < gap:
  push = (gap - d) * strength * alpha
  v_target += u * push * bias
  v_source -= u * push * (1 - bias)

where bias is d3's link bias, so the better connected end moves less. A link already satisfied is not touched: the force pushes apart and never pulls. A link whose gap or strength is NaN is left alone.

That is a force, scaled by alpha and shared with everything else that pushes, so the gap it leaves can be well short of the one asked for.

HARD. With hard: true the gap asked for is the gap kept: after the nodes have moved, with the hard containments and in the order the forces are listed, the links are projected. A node is HELD along the axis if it is pinned on a coordinate the axis has a part in (fx when u.x is not 0, fy when u.y is not 0; here, whatever the config's heldX and heldY say). One pass takes each link in order, on the positions as the links before it left them, both ends finite:

d = (p_target - p_source) . u
if d < gap:
  short = gap - d
  if the target is not held:      p_target += u * short,  v_target += u * short
  else if the source is not held: p_source -= u * short,  v_source -= u * short
  else:                           nothing

So the target gives way, and the source only where the target cannot. Passes repeat until one moves nothing, thirty-two at most (a chain of links listed child-first needs one pass per link; a cycle of links can never be satisfied and stops at the limit). The velocity changes with the position, as a containment's clamp does, so the node does not fly back next tick. The soft force above is applied as well, unless its strengths are 0.

#Config Source

type Config :: Row Type -> Type -> Typetype Config row link = { axis :: { x :: Number, y :: Number }, gap :: link -> Number, hard :: Boolean, heldX :: Node row -> Boolean, heldY :: Node row -> Boolean, iterations :: Int, strength :: link -> Number }

gap and strength are asked once per link when the force is initialized. The axis need not be a unit vector: it is normalised, and an axis of zero or infinite length becomes (0, 1), which is "below" on a screen. heldX and heldY matter only to the hard projection, and are asked each time it runs: Node.pinnedX and Node.pinnedY are the ones to give for nodes with fx and fy.

#Directional Source

newtype Directional :: Row Type -> Typenewtype Directional row

An initialized directional constraint.

#initialize Source

initialize :: forall row linkRow. Config row (Endpoints linkRow) -> Array (Node row) -> Array (Endpoints linkRow) -> Directional row

For links that name their nodes by place in the node array.

#initializeById Source

initializeById :: forall id row linkRow. Ord id => Show id => (Node row -> id) -> Config row (Identified id linkRow) -> Array (Node row) -> Array (Identified id linkRow) -> Either String (Directional row)

For links that name their nodes by id; a link to an id no node has is d3's error, node not found: <id>.

#apply Source

apply :: forall row. Directional row -> Number -> Effect Unit

The target is written before the source's velocity is read, so a link from a node to itself comes out as it does in the Rust.

#isHard Source

isHard :: forall row. Directional row -> Boolean

Does this force project its links after the nodes have moved?

#constrain Source

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

The hard projection. Nothing unless the force is hard.