English · 简体中文
An open-source, local-first 3D travel atlas for turning places, journeys, photographs, and aerial media into an interactive personal map.
StarMap is built with React, TypeScript, Vite, and Cesium. A clean clone opens with neutral sample data. Your own journeys, media, editor state, and environment values stay in Git-ignored local files by default.
- Interactive Cesium globe with country, city, route, and camera navigation.
- Map and Journey views with responsive glass UI.
- Local editor for countries, cities, ordering, visibility, city photos, and drone media.
- EXIF-first drone import: selected files are inspected immediately for date, GPS coordinates, absolute altitude, relative altitude, and camera information.
- Missing metadata is requested only when needed. The date is required; coordinates and altitude remain optional.
- Aspect-ratio-safe photo gallery for both landscape and portrait images.
- Three-tier private media pipeline: lightweight thumbnails, viewer previews, and preserved originals.
- One-click meteor shower and an in-app GitHub Release update guide.
- Privacy audit and public/private data separation designed for open-source reuse.
Requirements: Git and a current Node.js LTS release compatible with Vite 8.
git clone https://github.com/Aisland-SJL/StarMap.git
cd StarMap/01_Web
npm ci
npm run dev:publicOpen http://127.0.0.1:5173/. This public profile uses only neutral sample data and needs no credential.
For a personal atlas, create an external private layer next to the source repository (the official maintenance workspace uses StarMap/06_private/), copy .env.example to its config/.env.local, and run npm run dev:personal. In a standalone clone, set STARMAP_PRIVATE_ROOT to any private folder or use the ignored StarMap/06_private/ fallback. Personal configuration, journeys, media, and editor state remain physically outside the source repository.
StarMap can start without a token by using its bundled low-resolution Natural Earth II fallback. For Cesium ion online global imagery:
- Sign in or create an account at Cesium ion.
- Open Access Tokens and create an app-specific public token.
- For the easiest local start, keep the normal public scopes, including
geocodeif you want city-name search; keep every private scope disabled. For a production site, restrict Allowed URLs and accessible assets to what the deployment actually needs. - Open your private layer's
config/.env.localand enter the value afterVITE_CESIUM_ION_TOKEN=. - Restart the development server.
Never commit a token or paste it into an AI chat, issue, screenshot, log, or README. A browser-side production token is observable by visitors, so use a separate production token with URL and asset restrictions.
If you want AI assistance, give your Agent this prompt:
Read
AGENTS.md,README.md,01_Web/AGENTS.md,01_Web/README.md, and01_Web/.env.example. Explain the three StarMap imagery sources and ask whether I need Cesium ion, Tianditu, or only the bundled local fallback. Guide me through obtaining any credentials I choose and configuringVITE_MAP_SOURCE,VITE_CESIUM_ION_TOKEN, andVITE_TIANDITU_TOKEN. Never ask me to paste or reveal a complete token or key; tell me exactly where I should enter it in the external private layer'sconfig/.env.local, verify only non-secret presence and live map behavior, then startnpm run dev:personaland explain the basic controls. Never copy private data into the source repository.
Cesium remains StarMap's 3D globe engine. The source switch changes only the imagery drawn on that globe. Users who need a mainland-China-accessible source can apply for their own key at Tianditu Developer Resources and keep both credentials in the private layer's config/.env.local:
VITE_MAP_SOURCE=tianditu
VITE_CESIUM_ION_TOKEN=
VITE_TIANDITU_TOKEN=
VITE_MAP_SOURCE accepts auto, cesium, tianditu, or local. The Layers button always lists Cesium, Tianditu, and the bundled local fallback. A steady green light means the required value is present (or the local source is built in); a red light means the online source is not configured and cannot be selected. This check never displays or validates the credential itself. The browser remembers the selected available source. Changing .env.local still requires restarting the development server. Both online values are public-client credentials in a built static site, so use app-specific keys and apply the provider's production restrictions.
Development mode includes local editing controls. Use them to add or reorder countries and cities, hide or restore items, choose photo covers, and import city or drone media. Production builds do not include these write controls.
City creation uses Cesium ion geocoding first when the personal token is configured with the geocode public scope. If ion is unavailable, has no result, or exceeds nine seconds, StarMap falls back to an explicitly triggered, country-filtered OpenStreetMap lookup. The interface never spins indefinitely: users can retry with the local/English city name or switch to manual latitude and longitude entry.
When drone files are selected, StarMap immediately reads available EXIF/XMP metadata and displays it per file. Values found in the file are locked as file-derived facts. Only missing values become editable; a missing date must be supplied, while coordinates and altitude can be left blank.
For bulk media, follow the tracked 02_Assets/MediaInbox/ template but place real source files under the external private layer's MediaInbox/, then run:
npm run media:check
npm run media:importThe importer never rewrites Inbox originals. Personal source media, generated derivatives, local travel records, editor state, and .env.local stay in the external private layer and never enter the source repository.
From 01_Web/:
npm run lint
npm run build:public
npm run privacy:check
npm run media:checknpm run build:public creates a static public-display build in 01_Web/dist/. npm run release:check goes further: it requires a clean worktree, archives only Git-tracked files into a temporary clean room, installs dependencies, lints, and rebuilds there. This proves an external private layer cannot leak into a public release. Use build:personal only for a private deployment you control.
The bottom-right version button checks the latest GitHub Release at most once every 12 hours. A newer unseen version activates a breathing light and shows release notes plus a guarded AI-update prompt. It never overwrites your project automatically.
The button is reversible: click once to open the update page, then click it again to return to the Map or Journey view you were using.
Forks can point the checker at their own Releases by setting VITE_GITHUB_REPOSITORY=owner/repository.
| Path | Purpose |
|---|---|
01_Web/ |
React, TypeScript, Vite, and Cesium application |
02_Assets/MediaInbox/ |
Tracked neutral template for the external private Inbox |
03_Reference/ |
Architecture, privacy, and media workflow references |
05_Test/ |
Verification guidance |
- Real tokens belong only in the external private layer or hosting environment configuration.
- Personal travel data and user media belong only in the external private layer, outside the Git repository.
.gitignoreis a second safety net, not the primary separation mechanism.- Run
npm run release:checkbefore every public release; never push.env.local, private media, personal catalogs, or credentials.



