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.

Before you start: upload your layout

MAP:IQ needs to know what props you own. One-time setup: go to Studio IQ → Layout tab and upload your xLights rgbeffects.xml. If MAP:IQ says “Build your layout first,” this is what it’s asking for.

The flow

1. 1

   Pick a sequence

   Lights of Elm Ridge tab: click any sequence from the catalog — free or purchased — and go. The source layout is already loaded.

   Other vendor tab: upload two files from the vendor’s sequence folder: their rgbeffects.xml (their source layout) and the .xsq (the sequence). Both must come from the same vendor set.

2. 2

   Take the Source Tour (or skip it)

   A quick pre-flight: the sequence’s top effects, how much of it should map to your yard, special group patterns like arches, and anything to watch out for. It’s optional — you can skip straight to mapping.
3. 3

   Accept matches, tier by tier

   The AI sorts every match by confidence: Perfect (100%) → Strong (80–99%) → Medium (65–79%) → Weak (40–64%). Each tier shows source → destination cards. Accept all in one click, or skip the ones you don’t trust — skipped cards wait for you in Polish.
4. 4

   Polish — finish by hand on your own yard

   Your layout appears as a canvas with unmapped props highlighted. Click any prop to see the AI’s top three suggestions or search everything in the sequence. Toggle between Individual and Groups, pair up spinner submodels arm-by-arm, and watch the scoreboard fill in.
5. 5

   Review and export

   Check your two numbers — Display Coverage (how many of your props got mapped) and Effects Used (how much of the sequence found a home) — then hit Export to download the .xmap. The recap also offers a CSV report of every mapping, with scores.

How auto-matching tiers the work

MAP:IQ doesn’t dump every guess on you at once. It scores each pair, then stacks the matches into four tiers so you spend your time where it counts. Accept whole tiers in one click — the Perfect and Strong tiers are usually a single tap each, leaving you a short list to think about.

• Perfect — the names and types line up exactly. Safe to accept all.
• Strong — a tiny difference (a number, a word), but almost certainly right.
• Medium — a plausible guess worth a glance.
• Weak — a long shot. Accept only if it’s clearly the prop you meant.

Reading the mapping list

Inside each tier, every match is one row: source model → your model, with the tier badge on the right. The left side is the sequence author’s name; the right side is your prop. If a row points at the wrong prop, swap it before you accept.

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. In Polish, the canvas flags unmapped groups first for exactly that reason.

Coverage scoring — your two numbers

Mapping has two sides, so MAP:IQ shows two scores. They answer different questions, and a good map wants both high.

• Display Coverage — what share of your props got an effect. Low here means parts of your yard sit dark.
• Effects Used — 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 pass through Polish 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.