Skip to content
Aisland-SJLPublic

About

⭐ StarMap — your personal star-charted travel atlas: footprints, photos, and drone panoramas on an interactive Cesium globe.

Topics

Resources

Stars

119 stars

Watchers

0 watching

Forks

Latest commit

 

History

21 Commits

Folders and files

Repository files navigation

English · 简体中文

StarMap

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.

Product preview

StarMap globe overview Explore the whole globe

Start from a complete world view and travel to any corner of the Earth. Visited countries, cities, and journey routes remain visible on the globe.
Meteor shower, Milky Way, and close globe view From the Milky Way to ground tiles

Move closer to see the meteor shower and Milky Way, then continue zooming toward detailed terrain and imagery tiles on the surface.
City panel with precise photo and drone positions City-level media positions

Open a city panel to locate photographs and drone media by their precise coordinates and altitude, while browsing the city's photos and media entries.
Drone 360 panorama Viewer Drone 360° panorama Viewer

Open aerial panoramas inside the built-in Viewer for an immersive, zoomable view without leaving the atlas.

Highlights

  • 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.

Quick start

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:public

Open 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.

Map credentials — start here

StarMap can start without a token by using its bundled low-resolution Natural Earth II fallback. For Cesium ion online global imagery:

  1. Sign in or create an account at Cesium ion.
  2. Open Access Tokens and create an app-specific public token.
  3. For the easiest local start, keep the normal public scopes, including geocode if 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.
  4. Open your private layer's config/.env.local and enter the value after VITE_CESIUM_ION_TOKEN=.
  5. 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, and 01_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 configuring VITE_MAP_SOURCE, VITE_CESIUM_ION_TOKEN, and VITE_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's config/.env.local, verify only non-secret presence and live map behavior, then start npm run dev:personal and explain the basic controls. Never copy private data into the source repository.

Switch between Cesium and Tianditu

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.

Add your journeys and media

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:import

The 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.

Build and verify

From 01_Web/:

npm run lint
npm run build:public
npm run privacy:check
npm run media:check

npm 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.

Updates

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.

Project layout

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

Privacy and security

  • 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.
  • .gitignore is a second safety net, not the primary separation mechanism.
  • Run npm run release:check before every public release; never push .env.local, private media, personal catalogs, or credentials.

License

MIT

About

⭐ StarMap — your personal star-charted travel atlas: footprints, photos, and drone panoramas on an interactive Cesium globe.

Topics

Resources

Stars

119 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages