Visual packets adapter

Visual packets: Reusable analysis surfaces, not provider parsing.

The Visual adapter packages analysis-ready shapes that are not raw provider feeds: phase maps and player surfaces. It is the seam for dashboard packets that should be reusable across apps while leaving scoring, calibration, and interpretation in the product using Campos.

All adapters What you can build

Input shape

App-owned score-space points, calibration status, lineups, average positions, passing-network edges, and role-tag candidates.

Status

Tracking / visual packets

Raw feed

Visual packets

Provider-shaped. Their coordinates, their qualifier codes, their outcome strings.

Messy

Campos adapter

fromVisual.phaseMapSnapshot(snapshot, ctx)

Flips direction, standardises outcomes, filters own-goals and shootouts, resolves player labels.

One call

Typed data

PhaseMapSnapshot

Drop into <ShotMap />, your own React view, a server-side report, or an analysis script.

Ready

Not a provider adapter

This seam is for app-owned analysis that still needs reusable Campos packets. The data is already interpreted upstream; Campos preserves the visual contract, evidence, caveats, and source metadata.

Get it running

One import, one call per surface.

import { fromVisual } from "@withqwerty/campos-adapters";

const phaseMap = fromVisual.phaseMapSnapshot(snapshot, { matchId });
const playerSurface = fromVisual.playerSurfaceSnapshot(surface, { matchId });

What this adapter ships

The calls you can make today.

Shipped

phaseMapSnapshot(s)() returns PhaseMapSnapshot[]

Reusable output/cost quadrant-map packets.

Visual packets notes: Quadrant-map packet only; output/cost scoring stays outside Campos.

Shipped

playerSurfaceSnapshot(s)() returns PlayerSurfaceSnapshot[]

Lineups, average positions, networks, and role tags.

Visual packets notes: Lineups, average positions, passing networks, and role tags as visual data.

What you can build with this

Charts that drop straight onto this adapter's output.

Supported cards plot from this adapter with no extra work. Partial cards plot, but read the scope note. Dimmed cards need a surface this provider doesn't ship.

Pitch charts

Plot events, shots, passes, and formations directly on the pitch.

ShotMap

Needs shots() — not shipped on Visual packets yet.

PassMap

Needs passes() — not shipped on Visual packets yet.

PassFlow

Needs passes() — not shipped on Visual packets yet.

PassNetwork

Needs passes() — not shipped on Visual packets yet.

PassSonar

Needs passes() — not shipped on Visual packets yet.

Heatmap

Needs events() — not shipped on Visual packets yet.

KDE

Needs events() — not shipped on Visual packets yet.

Territory

Needs events() — not shipped on Visual packets yet.

Formation

Needs formations() — not shipped on Visual packets yet.

Match-time + xG

Time-series and xG-driven views from shots().

XGTimeline

Needs per-shot xG — Visual packets doesn't provide it.

Bring your own aggregates

These charts are adapter-independent — they take pre-aggregated inputs.

ScatterPlot

Takes pre-aggregated data. No adapter dependency.

RadarChart

Takes pre-aggregated data. No adapter dependency.

PizzaChart

Takes pre-aggregated data. No adapter dependency.

BumpChart

Takes pre-aggregated data. No adapter dependency.

LineChart

Takes pre-aggregated data. No adapter dependency.

CometChart

Takes pre-aggregated data. No adapter dependency.

Beeswarm

Takes pre-aggregated data. No adapter dependency.

DistributionChart

Takes pre-aggregated data. No adapter dependency.

PercentileSurfaces

Takes pre-aggregated data. No adapter dependency.

StatBadge

Takes pre-aggregated data. No adapter dependency.

Phase maps

Output/cost quadrants without hard-coding the scoring model.

phaseMapSnapshot() carries score-space points, team centroids, axis labels, calibration status, evidence, caveats, and source metadata. The adapter clamps values and preserves provenance; it does not decide how output or cost should be scored.

const phaseMap = fromVisual.phaseMapSnapshot(
  {
    id: "match-1:phase-map",
    points,
    centroids,
    calibration: { status: "insufficient-rich-sample" },
    caveat: "Within-match diagnostic only.",
  },
  { matchId: "match-1" },
);

Player surfaces

Lineups, positions, networks, and role candidates in one packet.

playerSurfaceSnapshot() packages the visual material a player-level analysis page usually needs: home and away team sheets, average-position points, passing-network edges, and role-tag candidates. Role scoring, tactical responsibility, and authored conclusions remain consumer-owned.

const surface = fromVisual.playerSurfaceSnapshot(
  {
    id: "match-1:players",
    home,
    away,
    averagePositions,
    passingNetwork,
    roleTags,
  },
  { matchId: "match-1" },
);

Current scope

What's honest about this adapter today.

What Campos owns

The visual contract.

IDs, clamped score-space or pitch-space co-ordinates, nullable fields, inferred-edge flags, evidence, caveats, and source metadata.

What stays upstream

Analysis logic.

Output scoring, cost scoring, role assignment, pass-network aggregation thresholds, calibration, and final football interpretation stay in the app.

Good use case

Reusable dashboards.

Use these packets when multiple apps should draw the same analytical object but should not share one hard-coded tactical model.

Lineage

What this adapter borrows from whom.

Concrete credits for the projects that did the underlying research or laid the reference tables we read from.

socceraction Python

SPADL canonical action taxonomy as a reference when we decided which Wyscout tag combinations collapse into which canonical event.

Compare providers