Wayfinding App

The Revel Digital Wayfinding App provides interactive, 3D indoor navigation for your digital signage displays. Visitors can search for a room, office, or amenity and see an animated walking route from a "You Are Here" starting point to their destination — including across multiple floors via elevators and stairwells.

This guide walks you through generating a wayfinding configuration, hosting your assets, and adding the wayfinding gadget to your signage templates.

How It Works

The wayfinding app is powered by a JSON configuration file that defines two things:

1. Locations — The searchable destinations in your building (rooms, offices, conference rooms, amenities, etc.).
2. Floors — One entry per floor, each containing a floor plan image and a waypoint navigation graph used for route calculation.

When a visitor selects a destination, the app computes the shortest path through the waypoint graph and renders a 3D ribbon route overlaid on your floor plan images. Multi-floor buildings are displayed as stacked 3D planes with vertical connectors between floors.

What You'll Need

• Floor plan images — One image per floor in PNG or SVG format. These should be clean architectural floor plans showing room layouts, corridors, and labels.
• A hosting location for your JSON and images — The app loads these at runtime, so they must be available via public URLs (see Hosting Options below).
• A Revel Digital account — To add the wayfinding gadget to your signage templates.

Step 1: Generate the Wayfinding Configuration

The wayfinding configuration is a JSON file that pairs your floor plan images with a waypoint navigation graph. There are several ways to create it:

Option A: Wayfinding Editor (Recommended)

The Wayfinding Editor is a browser-based visual tool for creating and refining your configuration. You can:

• Upload your floor plan images
• Point-and-click to place waypoints directly on the floor plan
• Draw connections between waypoints to define walkable paths
• Add and edit locations (rooms, offices, amenities) with categories, descriptions, and icons
• Configure multi-floor transport connections (elevators, stairwells)
• Set the "You Are Here" starting position for each floor
• Export the finished configuration as a JSON file

The editor is the best option for hands-on refinement of waypoint positions and connections, and is the recommended workflow for production deployments.

Option B: Claude AI Skill (Quick Start)

If you'd like to jumpstart the process, the Revel Digital Wayfinding Skill for Claude can generate an initial configuration from a floor plan image or a text description of your building layout. The skill analyzes your floor plan, identifies rooms and corridors, places waypoints, and outputs a complete JSON configuration along with a visual preview.

To install the skill:

1. Download the latest release ZIP from the GitHub Releases page.
2. In Claude, navigate to Settings → Features → Skills.
3. Click Add Custom Skill and upload the ZIP file.
4. Ensure Code Execution is enabled in Settings → Capabilities.

Once installed, upload your floor plan image and ask Claude to generate a wayfinding configuration. The skill produces a floorplan.json file and a visual overlay preview so you can verify waypoint placement. From there, you can load the generated JSON into the Wayfinding Editor for fine-tuning.

Note: AI-generated waypoint coordinates are best-effort estimates based on visual analysis. The Wayfinding Editor should be used to review and adjust positions before deploying to production signage.

Option C: Manual JSON Authoring

You can also author the JSON configuration by hand. The complete schema documentation is available in the Floorplan Configuration Guide. This approach gives you full control but requires understanding the waypoint coordinate system and connection graph structure.

Step 2: Understand the Configuration Format

The JSON configuration has two top-level arrays: locations and floors. Here's a brief overview — refer to the full schema documentation for complete details.

Locations

Each location represents a searchable destination in your building. Key fields include:

Floors

Each floor entry ties together a floor plan image, the visitor's starting position, and the waypoint navigation graph. The waypoints array defines nodes placed at corridor intersections, room doorways, and transport points (elevators/stairwells), with bidirectional connections forming the walkable path network.

All waypoint coordinates are in image-pixel space, where (0, 0) is the top-left corner of the floor plan image. This means the imageSize field must match the actual pixel dimensions of your floor plan image.

Step 3: Host Your Assets

The wayfinding app loads the JSON configuration and floor plan images at runtime, so both must be accessible via public URLs. Here are some common hosting approaches:

Amazon S3 / Cloud Storage

Upload your floorplan.json and floor plan images to an S3 bucket (or equivalent cloud storage) with public read access. Make sure CORS headers are configured to allow requests from your signage player's domain. This is a good option for organizations already using AWS or similar cloud infrastructure.

GitHub Pages

Create a GitHub repository for your wayfinding assets and enable GitHub Pages. Place your JSON and images in the repository, and they'll be served at https://<username>.github.io/<repo>/. This is a simple, free option that works well for smaller deployments.

Your Own Web Server

If you already have a web server or CDN, simply host the files there. Ensure CORS headers allow cross-origin requests if the files are on a different domain than your signage player.

Important: After hosting, update the image URLs in your floorplan.json to point to the actual hosted image locations.

Step 4: Add the Wayfinding Gadget to Your Signage

The wayfinding app is distributed as a Revel Digital gadget. To add it to your signage:

1. Log in to the Revel Digital CMS.
2. Open the template where you want to add wayfinding (or create a new template).
3. Add a new Gadget zone to your template.
4. In the gadget URL field, enter the following gadget definition URL: 
   
   https://reveldigital.github.io/wayfinding-app/wayfinding-app.xml
5. Once added, configure the gadget preferences:
   • Floorplan JSON URL — The public URL to your hosted floorplan.json configuration file.
6. Save the template and publish to your device(s).

The gadget will load your configuration at runtime and present visitors with a searchable directory and 3D wayfinding routes.

Tips and Best Practices

• Start with the AI skill, refine in the editor. Using the Claude skill to generate an initial layout from your floor plan image saves significant time. Load the output into the Wayfinding Editor to fine-tune waypoint positions and connections before going live.
• Use SVG floor plans when possible. SVG images scale cleanly to any screen resolution and tend to produce better results in the 3D rendering.
• Test with the live preview. The Wayfinding Editor includes a live preview — use it to verify that routes render correctly and all locations are reachable before deploying to signage.
• Keep descriptions visitor-friendly. Location descriptions appear in the search UI. Include practical details like hours of operation, services offered, or capacity.
• Verify bidirectional connections. The most common configuration error is one-way connections in the waypoint graph. If waypoint A connects to B, then B must also connect back to A. The validation tooling will catch these issues.

Resources

• Wayfinding Editor — Visual editor for creating and refining configurations
• Floorplan Configuration Guide — Complete JSON schema documentation
• Wayfinding Skill for Claude — AI-powered configuration generator
• Gadget Definition XML — URL for adding the wayfinding gadget to templates