Software Demos · Interactive demo

StructSAM: Structure- and Spectrum-Preserving Token Merging for Segment Anything

Token merging tailored to the Segment Anything Model: a feature-gradient energy protects boundary and prompt tokens, keeping both the graph spectrum and the segment boundaries. Use the buttons beside each control (or the Run the experiments launchers) to auto-play; everything runs client-side.

StructSAM: Structure- and Spectrum-Preserving Token Merging for Segment Anything

Token merging accelerates a Vision Transformer by collapsing redundant tokens, but the Segment Anything Model (SAM) breaks the recipe twice over: its image encoder mixes windowed and global attention, and its mask decoder needs a dense, prompt-conditioned feature grid for crisp boundaries. Applied off-the-shelf, ToMe / PiToMe-style destination heuristics erode object contours and leak prompt information as the merge rate rises. StructSAM (extending PiToMe) fixes this with three moves: a token-energy score from first-order feature gradients (high = boundary, low = flat), grid-based flatness screening that protects boundary and prompt tokens, and a merge-unmerge wrapper that restores the dense grid for the decoder. Step through the layers and watch StructSAM keep both the graph spectrum and the segment boundaries intact while naive ToMe degrades them at the same compute.

Token merging for SAMStructure preservationSpectral graph coarseningPrompt-aware mergingEfficient segmentation
Structure- and spectrum-preserving merge vs naive window-restricted ToMe
patch colour = current (lifted) feature · amber edge = boundary token (high gradient G) · teal ring = protected · pink box = prompt · arrows = next merge (pink = crosses a boundary) · number = patches merged
Laplacian spectrum, spectral & structure distanceSD & struct
StructSAM keeps both distances near 0 (spectrum AND boundaries preserved); naive ToMe climbs on both

Each square is a patch token of SAM's image encoder, laid out on the H×W patch grid, painted with 2–3 object regions on a flat background (each token's feature is a region signature plus noise) and a prompt box over one object. StructSAM's real energy score is computed live: the first-order feature-gradient energy G(h,w) = √(‖∇xf‖² + ‖∇yf‖²) from central differences on the feature map, so high G = a boundary/edge token (amber edge, protect) and low G = a flat region (safe to merge). StructSAM runs grid-based flatness screening: tokens with G above the margin threshold (and, in prompt-aware mode, the prompt tokens) are protected (teal / pink rings); the remaining flat tokens are merged toward the low-energy (argmin G) destination by a size-weighted average (the number in a merged token is the patches it now represents), and a merge-unmerge / recovery step duplicates the destination feature back to the cell so the decoder still sees a dense grid (the patch colours you see are that lifted feature map). Naive ToMe is window-restricted with no screening: it collapses each window toward a structure-agnostic destination, so it absorbs boundary and prompt tokens and its contours bleed. The right panel is the money shot. It builds the normalized Laplacian L = I − D−1/2 A D−1/2 of the token graph and, following the paper's spectral graph coarsening view, compares the leading eigenvalues of the original grid against the lifted (unmerged) grid, reporting a running spectral distance SD = Σ|λi − λ̂i| and a running structure distance (boundary-map distortion ‖G − Ĝ‖). Because StructSAM only merges inside coherent flat regions, both stay near zero (bounded Laplacian distortion, Theorem 1); naive ToMe erodes boundaries and leaks prompts, so both climb. Turn on Prompt-aware to protect the prompt tokens and merge the background harder (the extra FLOPs saved appear in the readout). (This is a 2D didactic illustration of the exact mechanism: the gradient-energy score, the flatness / prompt screening, the low-energy merge, the merge-unmerge recovery, and the normalized-Laplacian spectral distance are all computed live on a synthetic patch grid. Honest toy simplifications: tokens are hand-painted region patches, not real SAM ViT features; "attention" is not run (there is no encoder or mask decoder), so "structure distance" is a boundary-map proxy for mask mIoU, not an IoU against ground truth; FLOPs are an analytic n² estimate from token count, not a GPU benchmark; the eigen-decomposition is exact but on a small toy graph, so absolute SD values are illustrative; and merging is shown as one progressive pass rather than the encoder's per-layer margin schedule. In the published method the merge happens inside SAM's ViT image encoder. Across eight natural and medical benchmarks StructSAM cuts encoder FLOPs by 25–30% (up to 40%+ with prompt-aware merging) with only minor mIoU/Dice drops, consistently outperforming ToMe, PiToMe, ToMeSD, VidToMe and ALGM at the same compute, and a StructSAM + OpenVLA robotics variant matches SAM-2 tracking with a ~45% speedup. TrungTin Nguyen is a co-author.)

Run the experiments

Every animation runs live in your browser. Click a button to play that experiment on the demo (it scrolls up and starts); drag any control to take over. Nothing is downloaded.

Merge the token layers

Step through the layers: flat cells merge while boundary and prompt tokens are protected, keeping both the spectrum and the segment boundaries.

StructSAM vs naive ToMe

Flip the policy and compare the spectral and structure distances.

Keep ratio

Merge more or fewer tokens per layer.

Boundary margin

Sweep the gradient threshold that flags a boundary token to protect.

The idea in three steps

PiToMe proved that scoring redundancy and protecting the informative tokens keeps the graph spectrum. StructSAM carries that guarantee to SAM by making the score a structure quantity, screening on flatness, and adding a recovery step so dense mask decoding still works.

1 · Score

Energy = feature gradient

Replace PiToMe's similarity energy with a first-order feature-gradient energy G on the encoder feature map. High G marks a boundary/edge token to protect; low G marks a flat, homogeneous region that is safe to merge. Redundancy becomes an image-structure quantity.

2 · Screen then merge

Protect boundaries and prompts

Grid-based flatness screening protects the high-gradient boundary tokens and the prompt-region tokens, then merges only the flat tokens toward the low-energy destination by a size-weighted average. Naive ToMe, merging within windows with no such screening, bleeds across contours and leaks the prompt.

3 · Recover, preserve both

Unmerge keeps the dense grid

After attention runs on the reduced token set, a merge-unmerge step duplicates each destination back to its cell, restoring the full-resolution grid the mask decoder needs. Because merges stay inside flat regions, the normalized-Laplacian spectral distance and the boundary-structure distance both stay near zero (bounded distortion), while ToMe drifts up on both.

For the gradient-energy score, the flatness / prompt screening, the merge-unmerge framework, the spectral-coarsening bound, and the SAM / Medical-SAM / Efficient-SAM experiments on DIS5K, ThinObject-5K, COIFT, HRSOD and INbreast, see StructSAM: Structure- and Spectrum-Preserving Token Merging for Segment Anything Models (Duy M. H. Nguyen, Tuan A. Tran, …, TrungTin Nguyen, …, Jan Peters, Mathias Niepert; arXiv 2026, under review), which extends Accelerating Transformers with Spectrum-Preserving Token Merging (PiToMe) (NeurIPS 2024) and reuses the PiToMe code.