# Wikipedia3D (legacy revival)

A 2011-era WebGL + Semantic Web mashup that renders Wikipedia/DBpedia entities in a navigable 3D space, with map-based discovery and a rich UI for favourites, blacklisting, and exploration. This repo contains the original PHP/JS frontend and lightweight proxy scripts used for API calls.

---

## Quick assessment (what you have today)

**Strengths**
- Unique concept still feels fresh: spatial exploration of knowledge, fast discovery loop (search → spawn 3D item → navigate → branch).
- Feature-rich UX: favourites, blacklist, keyboard navigation, skybox themes, map-driven discovery.
- Fully client-driven rendering with Three.js and simple PHP utilities—no heavy backend required.

**Pain points / risks**
- **Very old JS stack** (jQuery 1.6, MooTools, ancient Three.js) and global namespace design.
- **Deprecated APIs**: Google Maps “panoramio” library is discontinued; AlchemyAPI is defunct.
- **Hard-coded domain URLs** (`wikipedia3d.world.eu.org`) break local use and make the app fragile.
- **Mixed-content/HTTP**: many endpoints are `http://` which modern browsers block on `https://`.
- **CORS + proxy reliance**: API calls are routed via PHP proxies; security + reliability needs care.

---

## Quick local hosting (FastAPI replacement)

The legacy PHP proxy has been replaced by a small FastAPI app that also serves the static site.

```bash
cd /home/lucky/.openclaw/workspace/wikipedia3d
python3 -m venv .venv
source .venv/bin/activate
pip install -r server/requirements.txt
uvicorn server.app:app --reload --port 8088
```

Open:
- Landing page: **http://localhost:8088/**
- App itself: **http://localhost:8088/wikipedia3d/**

> ⚠️ For best results run over **HTTP**, not HTTPS, because the code uses legacy HTTP endpoints.

### What changed
- `server/app.py` implements `/proxy` (replacement for `ba-simple-proxy.php`).
- `wikipedia3d/index.html` and `/index.html` are static HTML replacements for the old PHP pages.
- Proxy + icon URLs now point to relative paths to work locally.

---

## Outlook: modernizing while keeping the soul

**Goal:** Preserve the core experience (3D exploration + semantic discovery + map-driven expansion) while upgrading to a modern, maintainable stack.

### Phase 1 — Stabilize (lowest effort, highest payoff)
- Replace hard-coded URLs with relative paths.
- Add `.env` or config file for API endpoints/keys (Google Maps, GeoNames).
- Move inline scripts to files; reduce global pollution.
- Add a tiny local dev server script (Node or PHP).

### Phase 2 — Modern frontend
- Upgrade to a current Three.js and refactor rendering to ES modules.
- Replace MooTools and legacy jQuery usage with vanilla JS or a minimal modern library.
- Use `fetch()` + async/await instead of jQuery AJAX.
- Replace the deprecated Google Maps bits (Panoramio) with Maps JS API + Places/StreetView or Mapbox.

### Phase 3 — Data + semantics refresh
- Migrate from DBpedia-only to **Wikidata SPARQL** as primary, keep DBpedia as fallback.
- Replace AlchemyAPI (dead) with modern entity extraction or just remove it.
- Add caching and rate limiting in the proxy.

### Phase 4 — Experience upgrade (keep the magic)
- Improved camera controls (orbit + FPS toggle).
- Smooth item layout + collision avoidance.
- Mini-map + bookmarks + “topic trails” visualization.
- Optional VR/WebXR mode while retaining keyboard-first navigation.

---

## Key dependencies (legacy)
- jQuery 1.6.2, jQuery UI 1.8
- MooTools 1.3
- Three.js (very old build)
- Google Maps JS API (panoramio library deprecated)
- DBpedia SPARQL, Wikipedia API, GeoNames
- PHP proxy scripts (ba-simple-proxy.php)

---

## Next steps (suggested)
1. Confirm the app runs locally with the PHP server.
2. Apply the URL fixes above.
3. Decide on a modern map provider (Google Maps w/ key vs Mapbox).
4. I can then create a clean “modernization branch” with ES modules + updated Three.js while preserving the UI flow.

---

If you want, I can start a staged refactor plan and implement Phase 1 and Phase 2 step-by-step.