MAP:IQ — Sequence Mapping

Every xLights sequence was built on somebody’s layout, and that somebody isn’t you. Their show might have three mega trees and a 200-pixel matrix. You might have arches and a porch. MAP:IQ reads both layouts, matches the sequence’s props to your props automatically, lets you review and fix the matches, and hands you a .xmap file xLights imports directly. What used to be an evening of squinting at model names is now a coffee break.

What sequence mapping actually does

A sequence is a list of effects painted onto models — the source layout’s arches, trees, snowflakes, and groups. To run that sequence on your yard, every source model needs a home: one of your models. That pairing is the mapping, and the .xmap file is just the saved list of those pairs.

MAP:IQ does the matching for you. It looks at three things:

• Names — “Arch 1” on their layout wants “Arch 1” (or “Left Arch”) on yours.
• Type and size — a 50-pixel arch maps to an arch, not to a single floodlight. Pixel counts that line up score higher.
• Groups and submodels — a group of four arches on their side should land on your group of arches, and a spinner’s arms should pair arm-to-arm, not all onto one arm.

Source layout vs. target layout

Two layouts go into every map, and it helps to keep them straight:

• Source layout — the yard the sequence was built on. It comes from the sequence author. For our catalog sequences, MAP:IQ already knows it. For other vendors, you upload it.
• Target layout — your yard. This is the rgbeffects.xml you upload once in Studio IQ. Every map you ever build points at this.

MAP:IQ tries to pour the source layout into the target. The closer the two yards are in shape, the more of the show survives the pour.

The flow

1. 1

   Source — the sequence you're mapping

   Two tabs. Lights of Elm Ridge — “★ Layout on file — one click” — lists your mappable catalog sequences (free, purchased, or in your library); pick one and both the source layout and the .xsq load automatically, no files to hunt down. Other vendor — “Upload their layout + sequence” — takes two file drops from the vendor’s folder: their rgbeffects.xml (the source layout) and the .xsq (the sequence). Both must come from the same vendor set.
2. 2

   Your layout — where the show is going

   Point MAP:IQ at your yard. Pick a show whose layout is already on file, or drop in your xLights rgbeffects.xml. This is the target every match lands on.
3. 3

   Tune & run

   Set a few knobs — the confidence gate (high only, medium+, or low+), coverage fill, structural boost, and submodel rows — then hit Run. Running matches the sequence to your layout in the browser; it’s not the export yet, so you can re-run with different knobs as often as you like.
4. 4

   Review & export

   The match comes back as a scorecard and a hierarchy you read top to bottom — Supergroups → Groups → Models → Submodel groups. Scan it, fix anything that looks off (see below), then hit Export in the sticky bar to download the .xmap. A report of every mapping, with scores, downloads alongside it.

Confidence and hierarchy

Every match carries a confidence badge — a quick read of how sure MAP:IQ is:

• High — the names and types line up. Safe to trust.
• Med — a plausible match worth a glance.
• Low — a long shot; check it before you ship.

The review is grouped the way sequencers think — biggest grouping first, down to the smallest part — so you fix the matches that matter most, first. The Tier filter chips and the search box narrow every part of the review at once.

Reading and fixing the mapping

Each match is one row: source model → your model, with its confidence badge and score. The left side is the sequence author’s name; the right side is your prop. Read it in whichever density suits you — Table, Compact, or Collapsible.

Two actions live on every row when a match needs a change:

• Remap — point a source at a different prop. A search box opens with the engine’s top suggestions and your whole layout; pick a new home and the row updates (with an Undo). A prop that already has a match is greyed out — xLights keeps one source per destination, so unlink the other one first.
• Unlink — drop a match you don’t want, choosing a quick reason (wrong prop, wrong index, and so on). Re-link puts it back. Unmapped sources that have a good candidate offer an accept-the-suggestion shortcut too.

Below the mapped rows, a held-back list shows matches that fell short of the confidence gate, and an unmapped list shows source props that found no home — both good places to pick up a little extra coverage by hand.

Groups cascade down to their props

Most sequences lean on groups — “All Arches,” “Outline Everything,” “Spinners.” When MAP:IQ matches a source group to one of your groups, the effect cascades to every prop inside it. Map “All Arches” → your arch group once, and all your arches light up together, no row-by-row busywork.

This is why a group with no good home hurts more than a single prop with no home. A missed arch is one dark arch; a missed group can be a whole chunk of the show — which is why the review puts groups near the top.

Coverage scoring — your two numbers

Mapping has two sides, so the scorecard shows two numbers. They answer different questions, and a good map wants both high.

• Coverage — what share of your props got an effect. Low here means parts of your yard sit dark.
• Usage — what share of their sequence landed somewhere. Low here means you’re leaving show on the table.

How good is good?

• 90%+ coverage — green banner. Ship it.
• 70–89% — amber. Solid; a little cleanup by hand usually picks up the rest.
• Under 70% — red. Usually means the sequence and your yard just don’t share much (a mega-tree showcase mapped onto a yard with no mega tree can only do so much).

Using the .xmap in xLights

Open your sequence in xLights and use Import → Import Effects, choosing your downloaded .xmap as the mapping. xLights applies every source-to-prop match you approved, and your whole yard lights up with the new sequence.

FAQ

Want to plan which sequences run which nights once they’re mapped? Head to SET:IQ.