6 min read

MAP:IQ — Sequence Mapping

A sequence built for someone else's yard, fitted to yours — AI first pass, your final say.

Every xLights sequence was built on somebody's layout, and that somebody isn't you. MAP:IQ 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.

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
Pick a sequence
Lights of Elm Ridge tab: click any sequence from the catalog — free or purchased — and go.
Other vendor tab: upload two files from the vendor's sequence folder: their rgbeffects.xml (their layout) and the .xsq (the sequence). Both must come from the same vendor set.
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
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
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
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.

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.

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).

FAQ

'Start mapping' stays disabled after my vendor upload.

One of the two files didn't validate. Check that the layout file's root is <rgbeffects> and the sequence's is <xsequence> — it's easy to grab the same file twice. Re-export from xLights if a file looks corrupted.

I got a 'low overlap' warning on vendor files.

Fewer than 15% of the sequence's models appear in the layout file you paired with it — usually a sign the two files came from different vendor sets or versions. You can continue, but expect low coverage.

Some sequence layers show red with zero suggestions.

The matcher found nothing above its confidence floor for those layers. In Polish, search the browse list manually — or skip them if your yard genuinely has no equivalent prop.

My yard changed since I uploaded my layout.

Re-upload rgbeffects.xml on the Layout tab. If MAP:IQ shows a stale layout banner mid-session, click Re-ingest layout to pull in the fresh one.

Can I change a mapping after exporting?

The exported .xmap is final, but nothing stops you from running the same sequence again — hit Map another sequence on the recap and your layout's already loaded.

The matching run never finished.

Occasionally a fetch times out mid-pipeline. Hit Retry. If it keeps happening on one sequence, tell us — that's a bug we want.