Skip to content

Release v3.6

Latest

Choose a tag to compare

@Stukova Stukova released this 04 Nov 17:16
· 5 commits to main since this release

🎉 What's New

The Layout Decides Its Own Size

Every position used to be clamped into the spaceSize square on every tick. A layout whose natural size was larger than the space could not grow into it: it piled up along the border and took the square's shape, and fitView framed the square rather than the graph. Nothing bounds a position now. A layout grows as far as its forces take it, the repulsion grid follows the points wherever they go, and fitView frames the points.

spaceSize: 4096,                      // deprecated: it places the world origin at spaceSize / 2 and bounds nothing — leave it at the default

graph.fitView()                       // frames the points, wherever they went
layer.getBounds()                     // deck.gl: the box of the live layout, measured without a stall

Existing graphs that filled the space will now spread past it, with gravity setting the size: at the default gravity a layout settles near 2·√(40n) units across, which 100,000 points fit inside the old square and 300,000 did not. A non-default spaceSize logs a deprecation warning; a layout saved around another origin will need shifting when the key goes in the next major. One known limit: a single point very far from the rest coarsens the repulsion grid for everyone until gravity brings it back — the Far Point example shows it. Try it →

The Space Size Wall example with 30,000 points, no gravity, at tick 300: before, the points pile into the spaceSize square and take its shape; after, they spread into a disk twice its width, red where they are beyond the square

Repulsion That Fits the Layout

Above 4,096 points the many-body force approximates: far away, a cell's centroid stands in for its points; up close, each point is repelled through a sample of its cell's points. The far-field grid now follows the layout, and the near-field sample count can follow measured cell occupancy.

simulationRepulsionQuality sets how close a centroid may come. One cell away shimmers on clustered data while the simulation is hot; two cells away is calm and costs about a third more per step above 25,000 points.

  • 'precise' — every centroid at least two cells away (a 5×5 shell on every level but the finest)
  • 'fast' — a centroid may be one cell away (3×3)
  • 'auto' — precise up to 25,000 points, fast above

simulationRepulsionSamples is how many points are sampled from each nearby grid cell. It used to depend on the point count alone, so crowded clusters shimmered while sparse layouts did extra work. Now, when you leave it unset, the graph checks how crowded the layout is and picks the number for you; set a number to fix it. This close-range step is also about a quarter faster.

Automatic measurement runs only when Graph owns both its device and render loop. Host-driven graphs—including deck.gl, GraphSimulation, headless or manual rendering, enableRenderLoop: false, and external-device graphs—keep the point-count fallback (32 / 16 / 8). On a busy GPU each measurement can cause a short pause, so checks are spaced to cost about 1 % of the time. See it under load →

simulationRepulsionQuality: 'auto',   // new: 'precise' | 'fast' | 'auto'
simulationRepulsionSamples: 32,       // new: fixes the sample count, 2 to 64; unset (the default) measures it

A change of either key applies on the next tick. Try it →

Before and now, far field and near field. Far field: before, lumps stand in for the cells from one cell away, coarse next door and shimmering on clusters; now, from two cells away, still, a third more work above 25,000 points. Near field: before, 32 samples for a spread-out and a clustered layout alike, wasted passes on one and missed points and shimmer on the other; now, 8 samples for the spread-out layout at a quarter of the work and 64 for the clustered one, still

A Stroke in the Point's Own Color

Overlapping points of one color used to merge into a blob. Each point can now wear a thin stroke along its inside edge in a shade of its own fill: a step lighter or darker in OKLab lightness, so it reads the same on every hue, and 'auto' picks the direction per point. Off by default.

pointDefaultStrokeWidth: 1,          // CSS px; 0 (the default) draws none
pointDefaultStrokeColor: 'auto',     // 'auto' | 'darken' | 'lighten' | any color
pointStrokeContrast: 0.03,           // default lightness step

graph.setPointStrokeColors(colors)   // RGBA per point; NaN = the default
graph.setPointStrokeWidths(widths)   // CSS px per point; NaN = the default

The stroke is inset, so points keep their size, and it stays the same width however far you zoom. A point too small for its stroke gets a narrower band, so some fill always shows. Images sit above it, and greyed-out points fade stroke and all. Changes animate like colors and sizes do. Try it →

One pile of overlapping discs from the Point Stroke example, without a stroke on the left and with a pale stroke on the right: a flat blob becomes legible discs

A Place for Every Point

Pinning a point takes it out of the layout, and the cluster force pulls a whole group to one spot. Now each point can have a place of its own and is pulled toward it as one force among the others, so links and repulsion still shape the layout around it. The d3 equivalent is forceX / forceY.

simulationAttractor: 0.3,                 // the pull, on the same scale as simulationCluster (default 0.1)

graph.setPointAttractors(targets)         // [x0, y0, x1, y1, …] in simulation space; NaN = no attractor
graph.setPointAttractorStrength(weights)  // per point; default 1

The pull grows with the distance, like a spring, so a firm attractor holds its point in place and a loose one lets the neighbours have a say. Points without an attractor move as before, and a graph that sets none pays nothing per tick. Try it →

Three shapes from the Attractors example, a heart, a star and a rose, each traced by a rainbow chain of 400 linked points pulled toward attractors along the curve

Collision That Holds

With collision on, a dense cluster whose links pulled inward never resolved: the leaves of a hub stayed inside each other for as long as the simulation ran. The push faded with alpha like every other force, so whatever overlap the springs made while the layout was hot froze in. Collision is now a constraint. It does not fade, it is applied in full, every overlapping pair is resolved against the real neighbour at every graph size, and a link can no longer ask two points to overlap: while collision is on, a link's rest length is never shorter than the two points' touching distance.

simulationCollision: 1,               // now a relaxation factor: 1 = the full correction per pass, up to 2 over-relaxes
simulationCollisionIterations: 2,     // new: collision passes per tick; 1 by default, 2–4 for dense clusters
simulationCollisionCooling: 0,        // new: 0 never fades (default); 1 fades with alpha like the other forces

Existing graphs with collision on will lay out differently: overlap keeps resolving while the layout cools, and linked pairs settle touching instead of overlapping. A layout held under compression, where points cannot all fit, may keep adjusting until the simulation ends; simulationCollisionCooling: 1 brings back the old fading there. Each extra pass costs about as much as the first. Try it →

Seven hub clusters from the Collision vs Hub Springs example at tick 4,000: before, every cluster is a blob with its leaves stacked on the hub; after, each hub packs its leaves around it with nothing overlapping

Choose What's on Top

Points were always drawn in index order: a higher index landed on top, and the only way to change that was to reorder your data. Now you say which points go on top, and nothing else moves:

graph.setPointRenderOrder([7])           // point 7 on top, everything else as before
graph.setPointRenderOrder([3, 7])        // 3 above the rest, 7 above 3
graph.setPointRenderOrder(permutation)   // a full order, back to front
graph.setPointRenderOrder(null)          // back to index order

Indices, links, the layout and every per-point array keep their meaning. Hover, click, label sampling and your own picking pass all follow the order, and highlighted points stay above greyed-out ones. In the demo, click a point to bring it to the front. Try it →

Two frames of the Render Order example: four overlapping groups of points mixed by index order, then the Coral group brought on top with one call

Labels That Keep Up

Non-blocking position reads ({ nonBlocking: true }) could fall several frames behind on big, GPU-bound graphs, so labels visibly trailed their points, and collecting the result could still stall the page. The render loop now keeps one frame in flight while a copy is on its way: positions arrive one frame behind the drawn points, and reading them never waits for the GPU.

Labels shown again after a pause now appear where the points are, not where they were. While an overlay is reading, the simulation may run a little slower; with no reads in progress nothing changes.

getSampledPoints() and getSampledPointPositionsMap() now support { nonBlocking: true }. Both still read synchronously by default.

Link Defaults Stay in Sync

Changing the default link color or width now updates all links that use it, without changing your data.