Project Aletheia is an Intelligence Digital Twin that consolidates and visualizes various dynamic global data feeds—such as aircraft, satellites, vessels, and live cameras—onto a unified 3D globe. Inspired by "Tactical FUI" (Futuristic User Interface) and HUD designs found in cyberpunk and sci-fi media, the application features a high-contrast dark theme with cyan and red accents, utilizing glassmorphism for a premium operational feel.
Each entity layer is implemented using optimized methods to bypass API rate limits and minimize browser performance overhead.
- Tech: CesiumJS (
resium) / Google Photorealistic 3D Tiles - Approach: Renders high-fidelity 3D tile data from Google Maps using the Cesium engine. Custom post-processing (HDR, scanlines, atmospheric effects) is applied to achieve a "cyber" look and feel.
- Tech: OpenSky Network API
- Approach: Polls the REST API (
https://opensky-network.org/api/states/all) every 10 seconds. To prevent API rate-limiting and bandwidth spikes, the app dynamically calculates the "Camera Bounding Box" (viewport bounds) and requests only the aircraft currently visible to the user.
- Tech:
satellite.js/ Cesium Primitive API / Local TLE Data - Approach: Instead of polling external APIs every second, the app maintains a local database of orbital elements (TLE: Two-Line Element) in the
public/tle/directory. Real-time positions for thousands of satellites are calculated client-side usingsatellite.jsbased on the current system time. - Offline Reliability: Shifting TLE data from live fetches to static local files prevents Cloudflare blocks and CORS issues from CelesTrak. TLE data remains accurate for several days/weeks, allowing the space layer to function without an internet connection once data is cached.
- Performance: Utilizes the low-level Cesium
PointPrimitiveCollectionrather than standard Entities, allowing 60fps rendering of 5,000+ satellites (including Starlink and ISS) with minimal latency via LOD spatial indexing.
- Tech:
aisstream.ioReal-time WebSocket - Approach: Processes live position data streamed via WebSocket.
- CORS/Security: AISStream blocks direct browser connections to protect API keys. To bypass this, we implemented a WebSocket Proxy on the Vite dev server (
vite.config.ts) under the/ws/aisstreamendpoint, ensuring secure communication through a local backend.
- Tech: Static spatial filtering of scraped data (Webcamera24)
- Approach: Includes a static database of over 3,800 cameras globally in
src/data/webcamera24.json. Features a 3-tier LOD (Level of Detail) system based on altitude-based visibility and distance-based spatial bucketing to maintain near-zero CPU overhead even with thousands of markers.
- Frontend Framework: React 18, TypeScript, Vite
- 3D Geospatial Engine: CesiumJS (React wrapper:
resium) - Styling: Tailwind CSS v4, Vanilla CSS (Glassmorphism & animations)
- State Management: Zustand (Lightweight and high-performance)
- Icons: Lucide React
- Data Protocols: REST (OpenSky), WebSocket (AISStream), SGP4 Model (satellite.js)
To enable all features, obtain the following keys and place them in your .env.local file:
| Variable | Provider | Purpose |
|---|---|---|
VITE_GOOGLE_TILES_API_KEY |
Google Cloud (Map Tiles API) | Photorealistic 3D cities and terrain. |
VITE_CESIUM_ION_TOKEN |
Cesium Ion | Base map assets and streaming infrastructure. |
VITE_AISSTREAM_API_KEY |
aisstream.io | Real-time maritime AIS data via WebSocket. |
# 1. Clone the repository
git clone <repository_url>
cd project-aletheia
# 2. Install dependencies
npm install
# 3. Configure environment variables
# Create .env.local and add your API keys (see above)
# 4. Start Development Server
# This also initializes the AIS WebSocket proxy
npm run devDue to CelesTrak's anti-scraping policies, the app uses local TLE files. Please place the downloaded .txt files properly sorted into the following public/tle/ subdirectory structure. Over 50 TLE categories are supported:
1_SpecialInterest/(iss, stations, active debris...)2_WeatherEarthResources/(weather, noaa, goes...)3_Communications/(starlink, oneweb, iridium...)4_Navigation/(gps, glonass, galileo...)5_Scientific/(science, engineering, geodetic...)6_misc/(military, radar, cubesats...)
App will be available at http://localhost:5173.
Currently, aircraft move in discrete "spots" every 10 seconds. We plan to implement frame-by-frame linear interpolation using velocity and heading data to achieve smooth, fluid real-time movement.
Transition the current Vite-based WebSocket proxy to a dedicated Node.js (Express/Hono) BFF for better local secret management, caching, and resilience.
- Earthquake Data: Real-time 3D ripple effects using USGS/P2P earthquake API feeds.
- Weather Overlay: Voxel/Heatmap mapping of cloud cover and precipitation using OpenWeatherMap.
project-aletheia/
├── dist/ # Build output for production (Git ignored)
├── public/ # Static assets hosted directly
│ └── tle/ # 6-group orbital TLE dataset (Local files)
│ └── [1-6] directories/ # Grouped .txt elements
├── src/
│ ├── components/
│ │ ├── Map/
│ │ │ └── CesiumMap.tsx # Core 3D Logic: Aircraft, Ships, Satellites
│ │ └── UI/
│ │ ├── Sidebar.tsx # Target Detail Panel
│ │ └── SystemTicker.tsx # Bottom Live Activity Feed
│ ├── services/
│ │ ├── trafficService.ts # Aviation: OpenSky API
│ │ ├── maritimeService.ts # Maritime: AISStream WebSocket
│ │ └── satelliteService.ts # Space: SGP4 Propagation logic
│ └── workers/
│ └── satelliteWorker.ts # SGP4 propagation (Off-main-thread)
├── scripts/ # Data manufacturing tools (Git ignored)
├── SPEC.md # Technical specification & Checklist
├── .env.local # Local API Keys (Git ignored)
└── vite.config.ts # Vite Configuration (Cesium, WS Proxy)
This project is built upon various open-source libraries and public data feeds. Please refer to CREDITS.md for full license and attribution details.
Project Aletheia は、地球上の様々な動的データ（航空機、人工衛星、船舶、ライブカメラなど）を 3D グローブ上に一元的にマッシュアップ・可視化する「インテリジェンス・デジタルツイン」です。 サイバーパンクやSF映画に登場する Tactical FUI (Futuristic User Interface) / HUD をモチーフにしており、ダークテーマとシアン・レッドのアクセントカラー、グラスモーフィズムを取り入れたUIを採用しています。
各エンティティレイヤーは、API制限やブラウザのパフォーマンス限界を回避するため、それぞれ最適な手法で実装されています。
- 技術要素: CesiumJS (
resium) / Google Photorealistic 3D Tiles - 手法: Google Maps の 高精細な3DタイルデータをCesiumのエンジンで描画し、PostProcess（HDR、スキャンライン、大気表現など）でサイバーなルックアンドフィールに味付けしています。
- 技術要素: OpenSky Network API
- 手法: REST API (
https://opensky-network.org/api/states/all) を10秒間隔でポーリング。APIエラーや通信量爆発を防ぐため、「現在ユーザーが画面で見ているカメラの緯度・経度範囲（BoundingBox）」を動的に計算し、その範囲内の航空機のみを取得しています。
- 技術要素:
satellite.js/ Cesium Primitive API / ローカルTLEデータ - 手法: 外部APIを起動のたびに叩くのではなく、最新の軌道計算要素（TLE: Two-Line Element）を
public/tle/フォルダ内のローカルファイルとして保持しています。クライアントサイド（ブラウザ内）でsatellite.jsを駆使し、現在時刻から数千基の衛星の現在位置をリアルタイムに計算します。 - オフライン動作と安定性: 起動時の CelesTrak API 取得を廃止しローカル静的ファイル化することで、APIのアクセス制限やCORSエラーに左右されない堅牢なシステムとなりました。軌道要素は数週間程度の精度を維持するため、一度データを配置すればオフラインでも動作します。
- パフォーマンス最適化: 単純な Entity ではなく、低レイヤーの Cesium
PointPrimitiveCollectionを利用することで、StarlinkやISSを含む5,000基以上の衛星を 60fps で遅延なく描画します。
- 技術要素:
aisstream.io完全リアルタイム WebSocket - 手法: WebSocket通信を用い、API側からリアルタイムに送られてくる位置情報を処理しています。
- CORS・セキュリティ回避: AISStream側はAPIキー保護のため、ブラウザからの直接接続を防ぐ仕様（CORSブロック）になっています。これを回避するため、Viteのローカル開発サーバー（
vite.config.ts）にWebSocketプロキシ (/ws/aisstream) を構築し、ローカルバックエンド経由で安全に外部と疎通する設計を採用しています。
- 技術要素: Webcamera24 等のスクレイピング静的データによる空間フィルタリング
- 手法: 世界中・日本国内の約3,800箇所以上のカメラ情報を
src/data/webcamera24.jsonなどのローカルアセットとして同梱しています。「カメラ高度による一括Hidden」および「中心座標からの距離に基づく空間バケツ（Spatial Indexing）判定」の 3段階の強力なLOD（Level of Detail）制御 を実装し、数千個のマーカーがあってもCPU負荷を極小化しています。
- Frontend Framework: React 18, TypeScript, Vite
- 3D Geospatial Engine: CesiumJS (React wrapper:
resium) - Styling: Tailwind CSS v4, Vanilla CSS (Glassmorphism & animations)
- State Management: Zustand (軽量かつ高速なグローバル状態管理)
- Icons: Lucide React
- Data Protocols: REST (OpenSky), WebSocket (AISStream), SGP4 Model (satellite.js)
本アプリケーションを完全に動作させるためには、以下のAPIキーを発行し、プロジェクトルートの .env.local に記述する必要があります。
| 環境変数名 | 発行元 / サービス | 用途 |
|---|---|---|
VITE_GOOGLE_TILES_API_KEY |
Google Cloud (Map Tiles API) | 高精細な 3D 都市モデル・地形（Photorealistic 3D Tiles）の読み込み。 |
VITE_CESIUM_ION_TOKEN |
Cesium Ion | Cesiumデフォルトのベースマップアセット等のストリーミング用。 |
VITE_AISSTREAM_API_KEY |
aisstream.io | 船舶のリアルタイムAIS情報（位置・速度・ヘディング）を受信するためのWebSocket認証キー。 |
# 1. リポジトリのクローン
git clone <repository_url>
cd project-aletheia
# 2. インストール
npm install
# 3. 起動
npm run devCelesTrak のアクセス制限を回避するため、本アプリはローカルの TLE ファイルを使用します。初回起動時またはデータ更新時は、抽出した .txt ファイル群を以下の public/tle/ 内の各ディレクトリに配置してください。本アプリは50種類以上のTLEカテゴリに対応しています。
1_SpecialInterest/(ISS, 宇宙ステーション, スペースデブリ等)2_WeatherEarthResources/(気象衛星, 地球観測衛星, NOAA等)3_Communications/(Starlink, OneWeb, Iridium等の通信衛星)4_Navigation/(GPS, Galileo, GLONASS等の測位衛星)5_Scientific/(科学観測, 工学実験・測地衛星等)6_misc/(軍事衛星, キューブサット, レーダー等)
アプリは http://localhost:5173 で起動します。
現在、航空機などのトラッカーはAPIの更新間隔（10秒）ごとにスポットで移動しています。これを、各機体の「速度（Velocity）」や「進行方向（Heading）」パラメータを用いて、ブラウザの描画フレーム（RequestAnimationFrame）ごとに座標を線形補間（Dead Reckoning）し、ヌルヌルと自走するような完全なリアルタイム体験へと昇華させます。
現在は Vite の dev server が WebSocketプロキシを担っていますが、本番デプロイを見据え、Node.js (Express または Hono) による軽量な BFF（Backend For Frontend）を構築します。これにより、APIキーの完全隠蔽、内部でのキャッシュ最適化、外部API障害への堅牢性向上を図ります。
- 地震データ: USGS または 国内P2P地震情報の JSON/WebSocket API と組み合わせて、震央に波紋状の3Dエフェクトを即時投射します。
- 気象データ: OpenWeatherMap API 等を利用し、降雨レーダーや雲を表現するボクセル/ヒートマップをCesium上で半透明レイヤーとしてマッピングします。
project-aletheia/
├── dist/ # 本番用ビルド成果物 (Git管理対象外)
├── public/ # 静的アセットのホスト
│ └── tle/ # 6カテゴリーに分類された軌道要素データ
│ └── [1-6] フォルダ/ # 各衛星群の .txt ファイル
├── src/
│ ├── components/
│ │ ├── Map/
│ │ │ └── CesiumMap.tsx # 3Dマップ主軸。航空機・船舶・衛星の全描画ロジックを集約
│ │ └── UI/
│ │ ├── Sidebar.tsx # ターゲット詳細パネル
│ │ └── SystemTicker.tsx # 下部を流れるライブログ
│ ├── services/
│ │ ├── trafficService.ts # 航空機: OpenSky API
│ │ ├── maritimeService.ts # 船舶: AISStream WebSocket
│ │ └── satelliteService.ts # 人工衛星: SGP4位置演算
│ └── workers/
│ └── satelliteWorker.ts # 軌道計算用 Web Worker (メインスレッド分離)
├── scripts/ # データ生成用スクリプト群 (Git管理対象外)
├── SPEC.md # 技術仕様書 & 実装リファレンス
├── .env.local # 各種APIキー（Git管理外）
└── vite.config.ts # Vite 設定ファイル (Cesiumプラグイン, WSプロキシ)
本プロジェクトは多くのオープンソースソフトウェアおよび公開データソースによって支えられています。詳細な出典およびライセンス表記については CREDITS.md をご参照ください。