Skip to main content

Quick Start Guide

Overview​

This guide shows you in 5 steps how to set up a functioning wayfinding system for your shopping center.

Step 1: Prepare SVG Floor Plan​

Option A: Use Example SVG​

# Copy an example SVG
cp docs/wayfinding/examples/example-mall-single-floor.svg my-mall.svg

Option B: Create Your Own SVG​

  1. Open Adobe Illustrator, Inkscape, or Figma
  2. Create layers with the following IDs:
  • shops (for shop areas)
  • services (for services like restrooms, info)
  • facilities (for elevators, stairs)
  • entrances (for entrances)
  1. Name each element uniquely (e.g., shop-1, service-info)
  2. Add data-name attributes for names
  3. Export as SVG

Option C: Hybrid / AI raster plan (without vector SVG)

  1. Create the plan as PNG/JPEG (e.g. with AI Master Prompt + architect floor plan as reference)
  2. In the dashboard: Center Plans → SVG Center Plan → PNG → Hybrid SVG
  3. Assign polygons → Shop Mapping — Details: Hybrid Center Plan

Detailed Guide: SVG Structure & Wayfinding

Step 2: Upload SVG​

In the Dashboard:​

1. Go to: Dashboard → Center Plans → New Center Plan (or Edit Floor)
2. Click "Upload SVG" or drag and drop the file
3. Wait for automatic analysis
4. Check recognized elements in the preview

For Graphic Only / Without Wayfinding Labels (Optional):​

If you want to save the SVG only as a site plan with no labeled shop/service areas, enable "Graphic Only / Schema Check Relaxation" during upload. This way, you won't encounter the error "No elements in SVG," and you can still save the plan and later add a complete SVG or supplement it in mapping.

What Happens:​

  • The system analyzes SVG structure
  • Extracts shops, services, facilities
  • Displays a preview with all recognized elements
  • Creates a MapFloor entry in the database

Expected Result:​

6 shops recognized
4 services recognized
4 facilities recognized
3 entrances recognized
5 waypoints recognized

Step 3: Create Floor in Database​

The SVG upload automatically creates a MapFloor entry.

Manually (If Needed):​

// API-Call
POST /api/wayfinding/floors

{
  "centerId": "center-uuid",
  "floorNumber": 0,
  "name": "Ground Floor",
  "mapImage": "/uploads/wayfinding/svg/my-mall.svg",
  "mapSvg": "<svg>...</svg>",
  "isDefault": true
}

Check:​

Dashboard → Center Plans
→ Should display new Floor

Step 4: Map Shops & Services​

In the Dashboard:​

1. Go to: Dashboard → Center Plans → Mapping (or Edit Floor → Mapping Tab)
2. Select Center (top right)
3. Select Floor (Tabs)
4. You should see:
- On the left: Unmapped Shops/Services
- On the right: Interactive SVG Map

Perform Mapping:​

1. Click on an area in the SVG map (right)
2. A modal opens with the list of available shops/services
3. Select the shop from the list
4. The shop is placed at the clicked position
5. Repeat for all shops/services

Tips​

  • Zoom: Mouse wheel or zoom buttons
  • Pan: Hold left mouse button + drag
  • Delete: Click on mapped shop → Trash icon
  • Auto-Save: Mappings are saved automatically

Step 5: Test & Verify​

1. Check Mapping Status:​

Dashboard → Center Plans → Mapping
→ Statistics at the top: "X of Y Shops Mapped"

2. Test 3D Preview:​

Dashboard → Center Plans
→ Click on Floor Map
→ 3D Viewer should open

3. Test API:​

# Fetch all Floors
curl http://localhost:3000/api/wayfinding/floors?centerId=YOUR_CENTER_ID

# Fetch all MapLocations
curl http://localhost:3000/api/wayfinding/locations?floorId=YOUR_FLOOR_ID

4. Test Frontend:​

Frontend App → Center Website → Center Plan
→ Should display interactive map

Expected Final Result​

After completing all steps, you should have:

Database:​

  • MapFloor entry with SVG
  • MapLocation entries for each shop/service
  • Coordinates (x, y) for each location

Dashboard:​

  • SVG map visible in mapping interface
  • All shops/services mapped
  • 3D preview works

Frontend:​

  • Interactive map on center website
  • Shops clickable
  • Navigation works

Troubleshooting​

Problem: SVG is not recognized​

Symptom: "No shops found"

Solution:

  1. Check layer IDs in SVG: 
    <g id="shops">  <!-- Must contain "shops" or "shop" -->
      <rect id="shop-1" ... />
    </g>
  2. Check element IDs: Must be unique
  3. Check size: Min. 40x30px for shops

Test:

# Analyze SVG structure
cat my-mall.svg | grep -E 'id="(shop|service|facility)"'

Problem: Modal does not open on click​

Symptom: Click on map shows no shop selection

Solution:

  1. Check browser console for errors
  2. Ensure the floor is selected
  3. Check if SVG is loaded
  4. For small areas: Click "Hide Names" so text elements don't intercept clicks
  5. Try browser refresh (Cmd+R / Ctrl+R)

Problem: Shops are not saved​

Symptom: Mappings are gone after refresh

Solution:

  1. Check API response in Network tab
  2. Check database: 
    SELECT * FROM "MapLocation" WHERE "floorId" = 'YOUR_FLOOR_ID';
  3. Check permissions (User must have center access)

Test:

# Test API directly
curl -X POST http://localhost:3000/api/shop-mapping \
-H "Content-Type: application/json" \
-d '{
    "shopId": "shop-uuid",
    "floorId": "floor-uuid",
    "coordinates": {"x": 100, "y": 200}
  }'

Problem: Multi-Floor does not work​

Symptom: Only one floor is recognized

Solution:

  1. Check SVG structure: 
    <g id="floor-eg">  <!-- Must contain "floor" -->
      <g id="shops-floor-eg">
        <rect id="shop-eg-1" ... />
      </g>
    </g>
  2. Each floor needs its own group
  3. Shops must be within the floor group

Test:

# Find floor groups
cat my-mall.svg | grep -E 'id="floor-'

Additional Resources​

🎓 Next Steps​

After the basic setup, you can:

  1. Add waypoints for navigation
  2. Upload 3D models (GLB/GLTF)
  3. Define routes between locations
  4. Integrate digital signage
  5. Generate QR codes for locations

Best Practices​

SVG Creation:​

  • Use meaningful IDs (shop-aldi instead of rect-1)
  • Add data-name attributes
  • Keep structure consistent across all floors
  • Use standard colors (see SVG Structure)

Mapping:​

  • Map larger shops first (anchor tenants)
  • Then small shops
  • Lastly services & facilities
  • Regularly check mappings

Testing:​

  • Test on different browsers
  • Test mobile view
  • Test with real shop data
  • Test navigation between floors

Support​

For questions or problems:

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/centerplan/quick-start