Back to docs

Tool Transport Map

Category: Visual Testing · Since: v18.24.0 · Tier: All

Show WHERE visual content moved between two page states. Other tools only show that something changed. This tool shows how and where.

What Makes This Unique

Other visual regression tools answer: "Did something change?" (yes/no plus a score).

The Visual Transport Map answers:

  • Where did changes happen? (heatmap)
  • How did content move? (flow arrows)
  • What changed most? (hotspots with labels)

It solves the optimal transport problem between two images. This finds the lowest-cost plan for transforming one visual distribution into another.

How It Works

  1. Grid Division -- Both images split into cells (size is configurable)
  2. Per-Cell Histograms -- Color distribution computed for each cell
  3. Heatmap -- Wasserstein distance computed per cell (blue = no change, red = major)
  4. Transport Flows -- Greedy nearest-neighbor matching of sources (lost content) to sinks (gained content)
  5. Hotspot Detection -- Adjacent high-change cells merged into hotspot regions
  6. SVG Generation -- Overlay with heatmap, arrows, and labeled hotspots

Parameters

Parameter Type Default Description
baselinePath string required Path to baseline screenshot
currentPath string required Path to current screenshot
cellSize number 32 Grid cell size in pixels (smaller = finer granularity)
hotspots number 5 Number of hotspot regions to identify

Example

Generate a transport map between these two screenshots to show me what changed

Compare baseline.png and current.png with a transport map using 16px cells

Response

{
  "grid": { "rows": 34, "cols": 60 },
  "flows": 23,
  "totalCost": 0.0847,
  "hotspots": [
    {
      "region": { "x": 120, "y": 340, "width": 280, "height": 96 },
      "magnitude": 0.142,
      "description": "Significant visual change in 280×96px region"
    },
    {
      "region": { "x": 0, "y": 0, "width": 1920, "height": 64 },
      "magnitude": 0.089,
      "description": "Major layout change across large area"
    }
  ],
  "svgPath": "/path/to/transport-map.svg",
  "dimensions": { "width": 1920, "height": 1080 },
  "computeTime": "280ms"
}

SVG Visualization

The SVG has three layers:

  1. Heatmap overlay (40% opacity) -- Blue-Yellow-Red ramp showing change size per cell
  2. Flow arrows -- Red arrows showing where visual mass moved (width = mass)
  3. Hotspot outlines -- Yellow dashed boxes around the biggest change regions, with labels

The SVG saves to ~/.cbrowser/transport-maps/. Overlay it on the original screenshot.

Use Cases

Responsive Regression

Compare desktop vs mobile layout. The transport map shows how elements reflow:

Compare the desktop and mobile screenshots with a transport map

Cross-Browser Diff

See where Chrome and Safari render differently:

Take screenshots in chromium and webkit, then generate a transport map between them

Deploy Verification

Before/after deploy comparison showing what changed:

Generate a transport map between the pre-deploy and post-deploy screenshots

A/B Test Analysis

Visualize the actual visual differences between variants:

Show me a transport map of variant A vs variant B

Mathematical Foundation

The transport map solves a discrete optimal transport problem. Each grid cell is a node with a mass (total pixel weight). The transport plan redistributes mass from baseline to current at minimum cost.

The heatmap uses per-cell Wasserstein-1 distance between color histograms. The flows use greedy nearest-neighbor matching. This approximates the Earth Mover's Distance transport plan.

CLI

cbrowser transport-map baseline.png current.png
cbrowser transport-map baseline.png current.png --cell-size 16 --output changes.svg
cbrowser transport-map baseline.png current.png --hotspots 10

Related Tools

From the Blog