X-EasyGo 🏫

X-EasyGo is a mobile-first campus tour web system for Xi'an Jiaotong-Liverpool University. It helps new students and visitors explore the SIP campus through live positioning, AR storytelling links, audio narration, OCR scanning, digital stamp collection, and a leaderboard.

🔗 Links

• Portfolio: https://mazetracer.github.io/CPT208/
• App: https://wonder239239.github.io/Campus-Tour-Guide/

✨ Core Features

• 🌐 Chinese and English language switching.
• 🔐 Supabase username and password registration/login.
• 👤 User identity selection for new students and visitors.
• 🗺️ Campus map with live positioning for FB, CB, and SD.
• 📍 Distance display from the user to each target building.
• 🎧 Manual Enter Narration flow after the user enters a building range.
• 🖼️ Virtual guide page with location-specific images.
• 🔊 Manual Play Narration and Stop Narration controls.
• 🕶️ Location-specific Enter AR Demonstration links powered by Kivicube.
• 🔎 OCR scanning for building recognition and stamp collection.
• ✅ Center-screen OCR success toast that disappears automatically after 2 seconds.
• 🏅 Digital stamp book and stamp leaderboard.

🛠️ Setup Instructions

1. Clone the repository.

git clone https://github.com/Wonder239239/Campus-Tour-Guide.git
cd Campus-Tour-Guide

2. Check Supabase configuration.

This project uses Supabase for authentication and cloud data storage. The Supabase project configuration has already been set in supabase-config.js.

3. Create the database tables.

Open the Supabase SQL Editor and run the SQL script in supabase-schema.sql.

4. Run the project locally.

python3 -m http.server 4173

Then open:

http://localhost:4173

5. Test on mobile.

For live positioning and camera scanning, use a mobile browser such as Safari or Chrome. Location and camera permissions must be allowed. When deployed online, HTTPS is required for reliable geolocation and camera access.

🧰 Technologies Used

• HTML5: page structure.
• CSS3: responsive layout, mobile styling, animation, and toast feedback.
• JavaScript: application flow, map logic, narration controls, OCR handling, and UI state.
• Leaflet: interactive campus map.
• OpenStreetMap: map tile provider.
• Supabase: authentication, user profile storage, stamp records, messages, and leaderboard data.
• Tesseract.js: OCR recognition for building signs and stamp scanning.
• Web Speech API: browser-based audio narration.
• Geolocation API: live user positioning.
• MediaDevices API: camera access for OCR scanning.
• Kivicube: external AR demonstration scenes.
• GitHub Pages: static web deployment.

This project does not require React or Three.js. It is implemented as a vanilla HTML/CSS/JavaScript web application with external libraries and cloud services.

📍 Campus Locations

• FB (Foundation Building): 31.2765683, 120.7337931
• CB (Central Building): 31.2749451, 120.7339179
• SD (Science Building D): 31.274314, 120.735793

The recognition radius is configured in app.js and can be adjusted for on-site testing.

🚶 User Flow

1. Select language.
2. Register or log in.
3. Select user identity.
4. Open the campus map and start live positioning.
5. Enter narration after reaching a target location.
6. Play or stop narration manually.
7. Enter the AR demonstration for the current location.
8. Scan building signs to collect stamps.
9. View the stamp book and leaderboard.

🕶️ AR Demonstration Links

• FB: Kivicube scene for Foundation Building.
• CB: Kivicube scene for Central Building.
• SD: Kivicube scene for Science Building D.

The button on the virtual guide page opens the AR scene based on the current active location.

🔐 Authentication And Database

The project uses Supabase to store:

• username mappings;
• user identity;
• collected stamps;
• message board entries;
• leaderboard data.

Required files:

• supabase-config.js: Supabase project configuration.
• supabase-schema.sql: database tables and policies.
• supabase-auth.js: authentication and data access helpers.

🚀 Deployment

The project can be deployed as a static site, for example through GitHub Pages:

https://wonder239239.github.io/Campus-Tour-Guide/

Recommended deployment steps:

git status
git add README.md ai-logs/README.md ai-logs/primary-prompts.md index.html styles.css app.js supabase-auth.js supabase-config.js supabase-schema.sql assets/*.jpg assets/*.png assets/*.svg assets/*.glb
git commit -m "update campus tour project"
git push origin main

Do not commit local .DS_Store files.

🤖 AI Logs

The folder ai-logs/ contains the primary prompts used to generate or refine core components of the system. See ai-logs/README.md.

📁 Main Files

• index.html: page structure and screen layout.
• styles.css: visual design, responsive styling, AR guide layout, and OCR success toast.
• app.js: application flow, map positioning, narration, AR links, OCR scanning, stamp collection, and leaderboard logic.
• supabase-auth.js: Supabase authentication and data access functions.
• supabase-schema.sql: Supabase database schema and access policies.
• assets/: images and visual assets used by the interface.