Kinetic Map — Tutorial

A start-to-finish walkthrough for building a Kinetic Map report in Power BI: plotting units from MGRS, adding MIL-STD-2525C military symbols, marking scenario events and facilities, drawing area overlays, showing movement over time, and filtering by date with the companion Kinetic Timeline.

If you just want the full list of symbol names, see the symbol reference. For field wells, licensing, and troubleshooting, see the Kinetic Map support page.

---

What this visual does (in one paragraph)

You give it locations as MGRS grid references (e.g. 18SUJ2348316806) or decimal latitude/longitude — whichever your data uses — and it plots them on a satellite map as labelled points or 2525C military symbols. On top of that you can overlay scenario events (engagements, incidents, facilities), areas (geofences), an MGRS grid, and movement trails over time. The point and unit data stays inside your Power BI dataset; only basemap imagery is fetched from the internet.

---

Before you start

• Power BI Desktop is the easiest place to build this (the Service works too once published).
• Your tenant admin must have enabled “Allow visuals created using the Power BI SDK” (Admin portal → Tenant settings). Without it, you can’t import the visual.
• Grab the visual file KineticMap.pbiviz and the sample data in sample-data/.

---

Step 1 — Import the visual

1. In Power BI Desktop, open the Visualizations pane.
2. Click the ⋯ (more options) → Import a visual from a file.
3. Select KineticMap.pbiviz → OK.
4. The Kinetic Map icon appears in the Visualizations pane. Drag it onto the canvas and make it large.

Updating later: when you get a new .pbiviz, re-import it the same way. Power BI caches visuals by ID, so if a new version seems to still show old behaviour, remove the visual from the pane (right-click → delete), re-import, and restart Desktop. Your field bindings survive.

---

Step 2 — Understand the two ways to place a symbol

This is the one concept that saves the most confusion. There are two layers, each with its own location field:

Layer	Location field	Use it for
Units / points	Unit: MGRS / grid ref or Unit: latitude + Unit: longitude	Your own units, elements, and fixed locations/facilities
Scenario events	Event: MGRS / grid ref or Event: latitude + Event: longitude	Engagements, incidents, and events during an exercise

MGRS or lat/long: bind either the MGRS field or both latitude + longitude (decimal degrees) for a layer. If a row has both, MGRS wins; latitude/longitude is used wherever MGRS is blank — so you can even mix the two within one column set. Hover still shows the grid reference (computed from lat/long when needed).

Both layers can show a 2525C symbol by friendly name (like infantry, hospital, tank) — and the same names work in either layer, so you don’t have to memorise which list a name is in. The practical difference:

• Events have an affiliation field (friend / enemy / neutral / unknown), so an enemy tank can be red. Units are friendly by default.
• Use units for your laydown; use events when you want per-row affiliation (e.g. plotting OPFOR sightings).

---

Step 3 — Plot your first points

1. Get the data in. Home → Get data → Text/CSV → sample-data/map-sample.csv → Load. It has three text columns: Unit, Organization, MGRS.

2. Select the Kinetic Map visual, then bind the fields in the Build pane:

   Visual field	Your column
   Unit: name	Unit
   Unit: organization	Organization
   Unit: MGRS / grid ref	MGRS

3. The four points appear over Washington DC, each labelled Unit — Organization, auto-coloured by organization, with the map auto-zoomed to fit.

MGRS tips: spaces are optional (18SUJ2348316806 or 18S UJ 23483 16806 both work). 8- and 10-digit precision are supported. Rows with malformed MGRS are skipped silently.

---

Step 4 — Choose the basemap

In the Format your visual pane (paintbrush) → Basemap:

• Map style — Satellite (default), Hybrid (satellite + labels), Street, Topographic, Light gray, or National Geographic. These come from ArcGIS/Esri; click Allow on the WebAccess prompt the first time.
• Leave Tile URL template blank unless you run your own tile server.

---

Step 5 — Add military symbols (2525C)

To turn a plain point into a military symbol, add a column with the symbol name and bind it.

1. In your unit table, add a column (e.g. Symbol) with values like infantry, armor, field artillery, engineer, military police, hospital, motor pool, base gate…
2. Bind it to Unit: symbol (2525C).
3. Each point now renders as the corresponding 2525C symbol instead of a circle.

You can type either a friendly name (case-insensitive — field artillery, medevac helicopter, hospital) or a raw 15-character SIDC (e.g. SFGPUCI----E---). The full name list — 123 unit types and 200+ event/facility symbols — is in symbol reference (and as spreadsheet tabs in sample-data/symbol-codes.xlsx).

Colour — symbols follow, in priority order: a per-row Unit: color value (hex like #FF8800 or a colour name like crimson), then auto color-by-organization, then the standard affiliation colour. Bind a colour column to Unit: color to override per point.

Seeing a “hook”/squiggle instead of a building or vehicle? That’s milsymbol’s “unrecognised symbol” placeholder, which appears when a name didn’t match. Check spelling against symbol reference. (As of v1.0.55 facility/event names work in the Unit symbol field too, so this should be rare — but a typo will still produce the placeholder.)

---

Step 6 — Mark scenario events

Events are a separate layer with their own affiliation and colour.

1. Get data → Text/CSV → sample-data/events-sample.csv. Columns: EntityID, EventName, MGRS, EventType, Affiliation, Color.

2. Bind:

   Visual field	Column
   Event: name	EventName
   Event: MGRS / grid ref	MGRS
   Event: type	EventType
   Event: affiliation	Affiliation
   Event: color	Color

3. Each event renders as its 2525C activity/facility symbol, framed by affiliation.

Event types include kinetic activities (explosion, ied, sniper, ambush…), UAVs, PSYOP, CBRN, facilities (hospital, prison, police, bank, fuel depot, checkpoint…), equipment sightings (tank, apc, sam launcher, radar…), and air tracks (fighter, attack aircraft, helicopter…). Full list in symbol reference.

Affiliation (the Affiliation column) sets the frame — type any of:

Value	Frame
friendly / bluefor	blue rectangle
enemy / hostile / opfor (or blank)	red diamond
neutral	green square
unknown / pending	yellow cloud

Facilities (hospital, gate, supply points…) are usually your own — set their Affiliation to friendly for the blue rectangle frame.

---

Step 7 — Draw areas (geofences)

Areas are kept separate from your data model — you supply them as JSON, two ways (use either or both):

• Inline: Format → Fenced areas → Inline fences (JSON) and paste an array, e.g. the contents of sample-data/fences.json:

  [{ "name": "Training Area North", "wkt": "POLYGON((-77.05 38.88, -77.02 38.88, -77.02 38.91, -77.05 38.91, -77.05 38.88))", "color": "forestgreen" }]

  Each object takes wkt (required), name (the centred label), and optional color (overrides the card colours for that shape).
• URL: Format → Fenced areas → External fences file URL pointing at a hosted copy of the same JSON — handy for overlays shared across reports.

Tune fill/border colour, opacity, and Show area names in the Fenced areas card.

---

Step 8 — Turn on the MGRS grid

Format → MGRS grid → Show MGRS grid. The grid is zoom-adaptive: grid-zone boundaries when zoomed out, then 100 km → 10 km → 1 km → 100 m squares as you zoom in. Separate toggles control the zone/square labels (18SUJ) and the easting/northing numbers, and you can set the line colour and opacity.

---

Step 9 — Show movement over time

If your unit data has timestamps, the visual can draw each unit’s path.

1. Load sample-data/track-sample.csv (a unit reported at several times/places).
2. Bind DateTime → Unit: date/time (use the raw date/time column, not the auto date hierarchy), alongside the usual Unit/Organization/MGRS bindings.
3. Now:
   • A unit identified by name + organization shows one marker — its latest record.
   • When that unit’s records span different grid refs, the path draws as a movement trail (oldest → newest) with direction arrows and history dots. Hover a leg to see unit — from-grid → to-grid — date arrived.

This pairs with the Kinetic Timeline (Step 13): scrub the date range and each unit’s marker moves to its latest in-range position.

Tune the trail in the Movement trails card (width, arrows, history dots, fallback colour).

---

Step 10 — Co-located symbols

If several same-type units or events share a grid reference, the visual spreads them into a north–south stack centred on the point, with a box around the group (so they don’t overlap into an unreadable blob). Different types at one spot form side-by-side columns. Adjust spacing/box in the Co-located items card (on by default).

---

Step 11 — Hover tooltips

The Hover tooltip card chooses which fields appear when you hover a marker — units can show name / organization / MGRS / symbol; events can show name / type / affiliation / MGRS. Default is MGRS only.

---

Step 12 — Offline resilience (optional)

Symbols, grid, trails, and areas need no network — only the satellite imagery does. To keep the imagery for your area working on a weak connection, turn on Format → Basemap → Pre-cache tiles for data area while you have a good connection; it warms the browser cache with the tiles around your data. For guaranteed offline imagery, point the Tile URL template at a local/LAN tile server. (See the Offline resilience section of support page for the details and limits.)

---

Step 13 — Filter by date with the Kinetic Timeline

The Kinetic Timeline is a companion slicer visual (separate .pbiviz, kinetic-timeline-powerbi-visual). Add it to the same report page and bind your timestamp column; it emits a standard page filter, so scrubbing the day strip filters every visual on the page — including the Kinetic Map. Select a single day to reveal a within-day time-of-day slider. Because the map keeps your pan/zoom across filter changes, you can sit at one zoom level and scrub time to watch the picture evolve.

---

Putting it together — the bridge table (independent slicers)

For a polished report you usually want units and events as separate tables, each filterable by its own slicer, without Power BI’s “Can’t determine relationships” error. The fix is a one-column bridge table:

1. Load sample-data/bridge/map-sample-full.xlsx (tabs Units, Bridge, plus a Symbol Codes reference).
2. In Model view, create single-direction relationships Bridge[EntityID] → Units[EntityID] (and the same for an events table, if you keep events separate).
3. Bind ID (bridge key) → Bridge[EntityID] and the rest of the unit/event fields normally.

Single-direction relationships keep a slicer on one group from touching the other. Full walkthrough in smoke-test/SMOKE-TEST.md.

---

Quick troubleshooting

Symptom	Fix
No “Import a visual from a file” option	Tenant setting “Allow visuals created using the Power BI SDK” is off — ask your admin to enable it.
Points missing	MGRS not bound, or the grid strings are malformed (bad rows skip silently).
Symbol shows a “hook”/squiggle in a cloud or circle	The symbol name didn’t match — check spelling in symbol reference.
Old behaviour after re-importing a new .pbiviz	Power BI’s visual cache — remove the visual, re-import, restart Desktop.
Grey background	Basemap unreachable — check the Tile URL / WebAccess and your connection.
Areas don’t appear	Inline JSON not valid yet (it’s ignored until it parses), or the URL host isn’t reachable.
A facility renders friendly-blue but you want enemy-red	Use the Event layer (it has an affiliation field) rather than the Unit layer.

---

Where to go next

• symbol reference — every symbol name (units + events), with SIDCs, and how to change echelon/affiliation.
• support page — full data-role reference, every format-pane option, the data-residency model, and build/deploy notes.
• sample-data/ — ready-to-load CSV/Excel/JSON for every feature in this tutorial.