3D Force-Directed Layout

Overview

The D3Force3D layout is a 3D extension based on d3-force, which simulates physical forces in three-dimensional space to achieve automatic layout. Compared to 2D layouts, it adds force effects in the Z-axis direction, allowing richer data relationships to be displayed in 3D space.

Core Concepts

Force System

D3Force3D extends the traditional 2D force-directed layout with the following forces:

3D Centering Force: Pulls nodes toward the center point in 3D space
3D Collision Force: Prevents node overlap in 3D space
3D Radial Force: Attracts nodes to a sphere in 3D space
3D Axis Forces: Applies forces along the X, Y, and Z axes

Iteration System

The layout is computed through iterations, mainly involving the following parameters:

alpha: The current energy value of the iteration, controlling node movement speed
alphaDecay: The decay rate of the energy value
alphaMin: The minimum energy value; iteration stops below this value
velocityDecay: The velocity decay factor

Options

Property	Description	Type	Default	Required
type	Layout type	string	`d3-force-3d`	✓
nodeSize	Node size (diameter), used for collision detection	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-
iterations	Number of force iterations; higher means more precise but slower	number	-
numDimensions	Number of dimensions (2 or 3)	number	3
forceSimulation	Custom force simulation method	Simulation<NodeDatum, EdgeDatum>	-
onTick	Callback for each iteration	(data: LayoutMapping) => void	-
randomSource	Random number generator	() => number	-

Iteration Control

Property	Description	Type	Default
alpha	Current convergence threshold	number	1
alphaDecay	Convergence decay rate (0-1)	number	0.028
alphaMin	Stop iteration threshold	number	0.001
alphaTarget	Target convergence threshold	number	0
velocityDecay	Velocity decay factor	number	0.4

Force Model Options

Centering Force (center)

Property	Description	Type	Default
center.x	Center x coordinate	number	0
center.y	Center y coordinate	number	0
center.z	Center z coordinate	number	0
center.strength	Force strength	number	1

Collision Force (collide)

Property	Description	Type	Default
collide.radius	Collision radius	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	10
collide.strength	Force strength	number	1
collide.iterations	Collision iterations	number	1

Link Force (link)

Property	Description	Type	Default
link.id	Edge id generator	(edge: EdgeDatum, index: number, edges: EdgeDatum[]) => string	edge.id
link.distance	Ideal edge length	number \| ((edge: EdgeDatum, index: number, edges: EdgeDatum[]) => number)	30
link.strength	Force strength	number \| ((edge: EdgeDatum, index: number, edges: EdgeDatum[]) => number)	1
link.iterations	Link force iterations	number	1

Many-Body Force (manyBody)

Property	Description	Type	Default
manyBody.strength	Force strength	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-30
manyBody.theta	Barnes-Hut accuracy	number	0.9
manyBody.distanceMin	Minimum interaction distance	number	1
manyBody.distanceMax	Maximum interaction distance	number	Infinity

Radial Force (radial)

Property	Description	Type	Default
radial.strength	Force strength	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	0.1
radial.radius	Target radius	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	100
radial.x	Sphere center x	number	0
radial.y	Sphere center y	number	0
radial.z	Sphere center z	number	0

Axis Forces (x, y, z)

Each axis can be configured separately:

Property	Description	Type	Default
x.strength	X-axis force strength	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-
x.x	Target x coordinate	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-
y.strength	Y-axis force strength	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-
y.y	Target y coordinate	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-
z.strength	Z-axis force strength	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-
z.z	Target z coordinate	number \| ((node: NodeDatum, index: number, nodes: NodeDatum[]) => number)	-