Atlas of Stories

An interactive cultural guide for travellers. Start on a 3D globe, pick a city, then explore a landmark in three ways, each on its own page:

• Time travel (timetravel.html): drag a slider through the landmark's eras and watch historical photos fade into modern ones, or compare two eras side by side.
• Stories (stories.html): short narrated chapters on history, legends and culture, with a highlighted transcript.
• Visit (visit.html): opening hours with a live "Open now" badge (in the landmark's own time zone), etiquette dos and don'ts, local tips, and a filterable map.

Pages

Page	What it is
index.html	Home: the 3D globe, with search, the World / Vietnam atlases and "Through time"
city.html?id=hanoi	City or province guide with a satellite map of its landmarks
timetravel.html?id=eiffel-tower	Landmark: Time travel (&era=2 opens a given era)
stories.html?id=eiffel-tower	Landmark: narrated stories
visit.html?id=eiffel-tower	Landmark: visitor guide
landmark.html	Redirect that keeps older links (landmark.html?id=…#story) working

The globe has two atlases, switched with the World / Vietnam buttons:

• World: six cities, each with one fully built landmark. They are Hanoi (Ho Chi Minh Mausoleum), Paris (Eiffel Tower), Cairo (Pyramids of Giza), Kyoto (Kinkaku-ji), Rome (Colosseum) and New York (Statue of Liberty).
• Vietnam: all 34 provinces and centrally run cities on the administrative map that took effect on 1 July 2025. Each has a province page, a flagship landmark with Time travel, Stories and Visit pages, and a timeline for "Through time". Provinces merged in 2025 can also be found by their former names, e.g. "Hà Giang" finds Tuyên Quang.

Tech stack

Part	Choice
Build tool	Vite. Each page is built as a classic script so the site opens straight from disk (see below)
UI	Bootstrap 5 compiled from Sass with Material 3–style tokens, Roboto Flex, Material Symbols (only the icons in use are downloaded)
Language	Plain JavaScript (ES modules), HTML5, CSS
3D globe	CesiumJS, no key needed. Its images and star map load from the jsDelivr CDN. Far away it shows Sentinel-2 cloudless imagery by EOX (true colour, CC BY-NC-SA 4.0, so non-commercial use only); close up it switches to Esri World Imagery. Esri 3D terrain and a borders/labels layer are added on top. It renders at full screen resolution with MSAA. An optional Cesium ion token or Google Maps key adds photorealistic 3D buildings.
Maps	Leaflet with Esri tiles: street map (light/dark) and satellite with labels
Narration	Each chapter's own audio/video file, or the browser's built-in text-to-speech
Data	Static JSON in public/data/ (no backend)
Images	Wikimedia Commons, credited automatically on every page

Getting started

You need Node.js 20 or newer.

npm install
npm run dev        # http://localhost:5173
npm run build      # production build in dist/
npm run preview    # serve the production build
npm run package    # check + build, then copy to submission/website/ (plus readable source)

dist/ is a static site. It works on GitHub Pages or any web server, and also straight from disk: double-click dist/index.html. An internet connection is still needed for map tiles, fonts and photos.

Browsers block three things on pages opened from disk (file://), so the build avoids them:

• Module scripts. Each page is built separately as a classic script with defer (scripts/build.mjs).
• fetch() of the JSON files. scripts/bundle-data.mjs packs every file in public/data into one plain script, data/atlas-data.js, and getJSON reads from it first.
• Web Workers loaded from files or other sites. Cesium's own prebuilt bundle of all its workers is embedded in the page, and Cesium's TaskProcessor is patched at build time to start each worker with that code inside it. See cesiumEmbeddedWorkers in vite.config.js.

Deploy

The site is published to GitHub Pages by .github/workflows/deploy.yml. Every push to main checks the data, builds, and deploys automatically in about 1–2 minutes.

• First-time setup: in the repo, go to Settings → Pages and set "Source" to GitHub Actions.
• Optional 3D buildings: add VITE_CESIUM_ION_TOKEN or VITE_GOOGLE_MAPS_API_KEY under Settings → Secrets and variables → Actions, then re-run the workflow.

Optional: photorealistic 3D cities

The globe works without any account: satellite imagery, 3D terrain, borders and labels all come from Esri's public services. For real 3D buildings, like Google Earth's 3D cities, add one of these to a .env file (see .env.example):

VITE_CESIUM_ION_TOKEN=...      # free token from https://ion.cesium.com (also gives Cesium World Terrain)
VITE_GOOGLE_MAPS_API_KEY=...   # a Google Maps Platform key with the Map Tiles API enabled

With either one, the globe loads Google Photorealistic 3D Tiles. This path hasn't been tested without a key, so check it once you have one.

How the globe works

The design follows Google Earth: a search box, a knowledge card on the left, map controls on the right (compass, 2D/3D tilt, zoom, whole globe), a strip of featured landmarks, and a status bar with cursor coordinates and camera height. Clicking a city or landmark (on the globe, in the list, in search or in the strip) flies the camera there and opens its card. The card links to the full city guide or landmark page. You can link straight to a place with index.html#kyoto or index.html#colosseum. The back arrow on the city page uses this to return to the same spot.

The world in one year ("Through time")

Museums tell the story of one place through time. This feature tells history across places: pick a year and the whole globe shows what each city was like at that moment. For example, in 1889 the Eiffel Tower has just opened, Kyoto is in the Meiji era and Hanoi is under French rule.

• Press Through time (top right). A world timeline bar replaces the landmark strip.
• Drag the slider from 2600 BCE to today. The scale is stretched so recent centuries get more room. Or press ▶ for a guided tour of the key moments: the globe turns to where history is happening.
• Each city gets a floating card with what was going on there. Cities with something happening that very year (within 5 years) have pulsing red pins.
• The side card lists every city for that year, with each landmark's state: either "its story begins in …", or a link that opens the landmark's Time travel page at the matching era (timetravel.html?id=eiffel-tower&era=2).
• Share a year with index.html#year=1889. It also works on the 2D map used on devices without WebGL.

Project structure

index.html, city.html,                 page shells (the five page types)
timetravel.html, stories.html, visit.html
src/
  scss/main.scss          Bootstrap theme + all custom styles
  js/common.js            data loading, image credits, theme switch, navbar
  js/cesium-base.js       Cesium setup: embedded workers, CDN base URL, WebGL 1 fix
  js/hours.js             opening-hours / "Open now" logic (time-zone aware)
  js/map.js               Leaflet helpers and map categories
  js/world-year.js        "Through time": year scale, per-year snapshot, world timeline bar
  js/pages/               globe.js, city.js, timetravel.js, stories.js, visit.js (one per page)
  js/landmark/            shell.js (shared landmark header + page switcher),
                          timeline.js, story.js, guide.js (the three landmark views)
public/
  landmark.html           redirect for older landmark links
public/data/
  cities.json             list of cities shown on the globe
  cities/<id>.json        city intro, facts, etiquette, "coming soon" landmarks, timeline
  world-moments.json      key moments and periods for the World timeline
  vietnam-moments.json    key moments, periods and year scale for the Vietnam timeline
  landmarks/<id>.json     eras, story chapters, visitor guide
  media.json              generated: image URLs + credits (don't edit by hand)
  atlas-data.js           generated: all the JSON above in one script (not in git)
scripts/
  resolve-media.mjs       npm run media: looks up images on Wikimedia Commons
  check-data.mjs          npm run check: validates all the data files
  bundle-data.mjs         npm run data: builds public/data/atlas-data.js
  build.mjs               npm run build: builds each page as a classic script
  package.mjs             npm run package: copies the build + source to submission/website/

Adding a new city

No code changes are needed.

1. Add the city to public/data/cities.json:

   { "id": "istanbul", "name": "Istanbul", "country": "Türkiye", "continent": "Europe",
     "lat": 41.0082, "lon": 28.9784, "timezone": "Europe/Istanbul",
     "tagline": "Where two continents meet", "landmarks": ["hagia-sophia"] }
   

   timezone must be an IANA name. It drives the local clock and the "Open now" badge. Optional fields:

   • collections: the atlases the place appears in, e.g. ["world"], ["vietnam"] or both. Defaults to ["world"].
   • region: needed for atlases with groups, e.g. "North", "Central" or "South" for Vietnam.
   • kind: "City" or "Province". Cities' names win when labels overlap on the map.
   • formerly: older names that search should also find.

   The atlases themselves are defined in collections at the top of cities.json. Each has a home view (plus bounds for the 2D map), a moments file for "Through time", its groups, and "cards": "events" to show floating cards only for places with an event that year.

2. Create public/data/cities/istanbul.json. Copy an existing city file and change hero, facts, sections, etiquette and, optionally, planned. Also give it a timeline for the world timeline. Use about 10–15 entries in year order:

   { "year": 1453, "text": "Ottoman Sultan Mehmed II takes Constantinople." },
   { "year": 537, "text": "Hagia Sophia is completed.", "landmark": "hagia-sophia", "era": 0 }
   

   year is negative for BCE, and "approx": true shows it as "c. …". landmark + era (an index into that landmark's eras) link the entry to the landmark's Time travel. An optional image uses the same format as elsewhere.

3. Create public/data/landmarks/hagia-sophia.json. Copy an existing landmark and edit it. The key fields:

   Field	Notes
   eras[]

The new city will appear on the globe, in the Cities menu and in the city list.

Design notes

• The time slider steps through eras, not years. Eras are spaced evenly so that a 4,500-year history (Giza) and a 140-year one (Statue of Liberty) are equally easy to explore. While you drag, neighbouring images cross-fade. On release, the slider snaps to the nearest era.
• Opening hours are always calculated in the landmark's time zone, so a visitor browsing from anywhere sees the correct status.
• Content and code are separate. Every landmark uses the same template, filled from JSON, so the JSON could later come from a CMS or an API without changing the pages.
• Prototype notes. Where the prototype differs from the planned product (recorded narration, more landmarks per city), a dashed "Prototype note" box says so.
• One layout for every page: a content panel next to a large viewport (satellite map, era photos, story media or visitor map), as in Google Earth. On phones the viewport sits on top and the panel scrolls below.
• Accessibility: skip link, keyboard-operable slider (arrows, Home and End), keyboard search with arrow keys, labelled controls, live region for era changes, transcripts for all narration, reduced-motion support, and light and dark themes.

Content disclaimer

Opening hours, prices and map marker positions are approximate prototype data. Check official sources before travelling. Images come from Wikimedia Commons under their stated licences, and each page lists its image credits.