iotlabkit 1.0.0__py3-none-any.whl

iotlabkit/templates/program_11.py

@@ -0,0 +1,347 @@
+"""Template generator for Program 11: ISS Real-Time Location Tracking & Trajectory Analysis."""
+
+from typing import Dict
+
+
+def generate(target_dir: str, mode: str = "learning") -> Dict[str, str]:
+    files = {}
+
+    files["requirements.txt"] = (
+        "requests>=2.28.0\n"
+        "pandas>=1.5.0\n"
+        "matplotlib>=3.6.0\n"
+        "streamlit>=1.25.0\n"
+    )
+
+    files[".env.example"] = (
+        "# ISS Telemetry Collector Settings\n"
+        "# Default: 100 records at 5-second intervals (~8.3 minutes total duration)\n"
+        "SAMPLE_COUNT=100\n"
+        "SAMPLE_INTERVAL_SECONDS=5\n"
+    )
+
+    files[".gitignore"] = (
+        ".env\n"
+        "__pycache__/\n"
+        "*.py[cod]\n"
+        "output/*.png\n"
+    )
+
+    # collector.py
+    if mode == "learning":
+        col_doc = (
+            '"""ISS Live Orbital Position Collector - Program 11.\n\n'
+            "Retrieves authentic real-time orbital coordinates of the International Space Station\n"
+            "from live APIs: Open-Notify (`api.open-notify.org`) with automatic fallback to\n"
+            "WhereTheISS (`api.wheretheiss.at/v1/satellites/25544`).\n\n"
+            "Collects 100 observations at 5-second intervals (500 seconds ≈ 8.33 minutes)\n"
+            "and appends records to 'data/iss_locations.csv'.\n"
+            '"""\n'
+        )
+    else:
+        col_doc = '"""ISS Location Collector - Program 11 (Exam Mode)."""\n'
+
+    files["collector.py"] = col_doc + (
+        "import argparse\n"
+        "import csv\n"
+        "import os\n"
+        "import sys\n"
+        "import time\n"
+        "from datetime import datetime, timezone\n"
+        "import requests\n\n"
+        "PRIMARY_URL = 'http://api.open-notify.org/iss-now.json'\n"
+        "FALLBACK_URL = 'https://api.wheretheiss.at/v1/satellites/25544'\n"
+        "CSV_PATH = os.path.join(os.path.dirname(__file__), 'data', 'iss_locations.csv')\n\n"
+        "def fetch_iss_position() -> dict:\n"
+        "    \"\"\"Fetches live ISS coordinates from primary API, falling back to backup HTTPS API.\"\"\"\n"
+        "    # Try primary: Open-Notify\n"
+        "    try:\n"
+        "        resp = requests.get(PRIMARY_URL, timeout=4)\n"
+        "        if resp.status_code == 200:\n"
+        "            data = resp.json()\n"
+        "            pos = data.get('iss_position', {})\n"
+        "            return {\n"
+        "                'timestamp': data.get('timestamp', int(time.time())),\n"
+        "                'latitude': float(pos.get('latitude')),\n"
+        "                'longitude': float(pos.get('longitude')),\n"
+        "                'source': 'Open-Notify'\n"
+        "            }\n"
+        "    except Exception:\n"
+        "        pass\n\n"
+        "    # Fallback: WhereTheISS\n"
+        "    try:\n"
+        "        resp = requests.get(FALLBACK_URL, timeout=4)\n"
+        "        if resp.status_code == 200:\n"
+        "            data = resp.json()\n"
+        "            return {\n"
+        "                'timestamp': int(data.get('timestamp', time.time())),\n"
+        "                'latitude': float(data.get('latitude')),\n"
+        "                'longitude': float(data.get('longitude')),\n"
+        "                'source': 'WhereTheISS'\n"
+        "            }\n"
+        "    except Exception as e:\n"
+        "        raise RuntimeError(f'Both ISS APIs failed: {e}')\n\n"
+        "def main():\n"
+        "    parser = argparse.ArgumentParser(description='Collect ISS orbital location telemetry')\n"
+        "    parser.add_argument('--count', type=int, default=100, help='Total number of location samples (default: 100)')\n"
+        "    parser.add_argument('--interval', type=float, default=5.0, help='Seconds between samples (default: 5.0)')\n"
+        "    args = parser.parse_args()\n\n"
+        "    total_seconds = args.count * args.interval\n"
+        "    total_minutes = round(total_seconds / 60, 1)\n"
+        "    print('=' * 70)\n"
+        "    print('🛰️  ISS Real-Time Orbital Tracking Collector')\n"
+        "    print('=' * 70)\n"
+        "    print(f'Target Samples      : {args.count} records')\n"
+        "    print(f'Polling Interval    : {args.interval} seconds')\n"
+        "    print(f'Total Expected Time : {total_seconds} seconds (~{total_minutes} minutes)')\n"
+        "    print(f'Output CSV File     : {CSV_PATH}')\n"
+        "    print('=' * 70)\n\n"
+        "    os.makedirs(os.path.dirname(CSV_PATH), exist_ok=True)\n"
+        "    file_exists = os.path.exists(CSV_PATH)\n\n"
+        "    with open(CSV_PATH, 'a', newline='', encoding='utf-8') as f:\n"
+        "        writer = csv.writer(f)\n"
+        "        if not file_exists or os.path.getsize(CSV_PATH) == 0:\n"
+        "            writer.writerow(['timestamp', 'iso_datetime', 'latitude', 'longitude', 'source'])\n\n"
+        "        collected = 0\n"
+        "        for i in range(1, args.count + 1):\n"
+        "            try:\n"
+        "                pt = fetch_iss_position()\n"
+        "                dt_str = datetime.fromtimestamp(pt['timestamp'], tz=timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')\n"
+        "                writer.writerow([pt['timestamp'], dt_str, pt['latitude'], pt['longitude'], pt['source']])\n"
+        "                f.flush()\n"
+        "                collected += 1\n"
+        "                print(f\"[{i:03d}/{args.count:03d}] {dt_str} | Lat: {pt['latitude']:>8.4f}° | Lon: {pt['longitude']:>9.4f}° ({pt['source']})\")\n"
+        "            except Exception as err:\n"
+        "                print(f\"[{i:03d}/{args.count:03d}] ✗ Fetch error: {err}\")\n\n"
+        "            if i < args.count:\n"
+        "                time.sleep(args.interval)\n\n"
+        "    print(f'\\n✓ Successfully collected {collected} real ISS location observations in {CSV_PATH}.')\n"
+        "    print('Now run `python analyzer.py` to calculate orbital metrics and view plots.')\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # analyzer.py
+    if mode == "learning":
+        ana_doc = (
+            '"""ISS Orbital Telemetry Analyzer.\n\n'
+            "Computes orbital statistics, distance traveled (Haversine formula),\n"
+            "orbital speed approximation, and plots Latitude vs Time and Longitude vs Time.\n"
+            '"""\n'
+        )
+    else:
+        ana_doc = '"""ISS Telemetry Analyzer - Program 11 (Exam Mode)."""\n'
+
+    files["analyzer.py"] = ana_doc + (
+        "import math\n"
+        "import os\n"
+        "import sys\n"
+        "import pandas as pd\n"
+        "try:\n"
+        "    import matplotlib.pyplot as plt\n"
+        "    HAS_MATPLOTLIB = True\n"
+        "except ImportError:\n"
+        "    HAS_MATPLOTLIB = False\n\n"
+        "CSV_PATH = os.path.join(os.path.dirname(__file__), 'data', 'iss_locations.csv')\n"
+        "OUTPUT_DIR = os.path.join(os.path.dirname(__file__), 'output')\n\n"
+        "def haversine_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float:\n"
+        "    \"\"\"Calculates great-circle distance between two GPS coordinates in kilometers.\"\"\"\n"
+        "    R = 6371.0  # Earth's mean radius in km\n"
+        "    phi1 = math.radians(lat1)\n"
+        "    phi2 = math.radians(lat2)\n"
+        "    delta_phi = math.radians(lat2 - lat1)\n"
+        "    delta_lambda = math.radians(lon2 - lon1)\n"
+        "    a = math.sin(delta_phi / 2)**2 + math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2)**2\n"
+        "    c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))\n"
+        "    return R * c\n\n"
+        "def main():\n"
+        "    if not os.path.exists(CSV_PATH) or os.path.getsize(CSV_PATH) == 0:\n"
+        "        print(f\"✗ Error: Dataset file '{CSV_PATH}' is missing or empty.\")\n"
+        "        print(\"  Run `python collector.py` first to collect live orbital points.\")\n"
+        "        sys.exit(1)\n\n"
+        "    df = pd.read_csv(CSV_PATH)\n"
+        "    if len(df) < 2:\n"
+        "        print(f\"✗ Need at least 2 records for statistical trajectory analysis (found {len(df)}).\")\n"
+        "        sys.exit(1)\n\n"
+        "    os.makedirs(OUTPUT_DIR, exist_ok=True)\n"
+        "    df['timestamp'] = pd.to_numeric(df['timestamp'])\n"
+        "    df['latitude'] = pd.to_numeric(df['latitude'])\n"
+        "    df['longitude'] = pd.to_numeric(df['longitude'])\n\n"
+        "    # Compute distances between consecutive points\n"
+        "    distances = []\n"
+        "    durations = []\n"
+        "    for i in range(1, len(df)):\n"
+        "        d = haversine_distance(\n"
+        "            df.iloc[i - 1]['latitude'], df.iloc[i - 1]['longitude'],\n"
+        "            df.iloc[i]['latitude'], df.iloc[i]['longitude']\n"
+        "        )\n"
+        "        dt = df.iloc[i]['timestamp'] - df.iloc[i - 1]['timestamp']\n"
+        "        distances.append(d)\n"
+        "        durations.append(dt)\n\n"
+        "    total_dist_km = sum(distances)\n"
+        "    total_time_s = sum(durations)\n"
+        "    avg_speed_km_h = (total_dist_km / (total_time_s / 3600)) if total_time_s > 0 else 0\n\n"
+        "    print('=' * 65)\n"
+        "    print('🛰️  ISS Trajectory & Orbital Statistical Summary')\n"
+        "    print('=' * 65)\n"
+        "    print(f\"Total Observations     : {len(df)} records\")\n"
+        "    print(f\"Latitude Range         : {df['latitude'].min():.4f}° to {df['latitude'].max():.4f}° (Mean: {df['latitude'].mean():.4f}°, Std: {df['latitude'].std():.4f})\")\n"
+        "    print(f\"Longitude Range        : {df['longitude'].min():.4f}° to {df['longitude'].max():.4f}° (Mean: {df['longitude'].mean():.4f}°, Std: {df['longitude'].std():.4f})\")\n"
+        "    print(f\"Total Ground Distance  : {total_dist_km:.2f} km\")\n"
+        "    print(f\"Elapsed Tracking Time  : {total_time_s:.1f} seconds ({round(total_time_s/60, 2)} minutes)\")\n"
+        "    print(f\"Estimated Ground Speed : {avg_speed_km_h:.1f} km/h (Theoretical ISS speed: ~27,600 km/h)\")\n"
+        "    print('=' * 65)\n\n"
+        "    if HAS_MATPLOTLIB:\n"
+        "        # Plot 1: Latitude vs Time\n"
+        "        plt.figure(figsize=(10, 4))\n"
+        "        plt.plot(range(len(df)), df['latitude'], color='tab:blue', marker='o', markersize=3, label='Latitude (°)')\n"
+        "        plt.title('ISS Latitude vs. Observation Index')\n"
+        "        plt.xlabel('Observation Index (5s intervals)')\n"
+        "        plt.ylabel('Latitude (°)')\n"
+        "        plt.grid(True, linestyle='--', alpha=0.6)\n"
+        "        plt.legend()\n"
+        "        lat_plot_path = os.path.join(OUTPUT_DIR, 'iss_latitude_trend.png')\n"
+        "        plt.savefig(lat_plot_path, dpi=150, bbox_inches='tight')\n"
+        "        plt.close()\n"
+        "        print(f\"✓ Saved Latitude Trend Chart to: {lat_plot_path}\")\n\n"
+        "        # Plot 2: Longitude vs Time\n"
+        "        plt.figure(figsize=(10, 4))\n"
+        "        plt.plot(range(len(df)), df['longitude'], color='tab:orange', marker='s', markersize=3, label='Longitude (°)')\n"
+        "        plt.title('ISS Longitude vs. Observation Index')\n"
+        "        plt.xlabel('Observation Index (5s intervals)')\n"
+        "        plt.ylabel('Longitude (°)')\n"
+        "        plt.grid(True, linestyle='--', alpha=0.6)\n"
+        "        plt.legend()\n"
+        "        lon_plot_path = os.path.join(OUTPUT_DIR, 'iss_longitude_trend.png')\n"
+        "        plt.savefig(lon_plot_path, dpi=150, bbox_inches='tight')\n"
+        "        plt.close()\n"
+        "        print(f\"✓ Saved Longitude Trend Chart to: {lon_plot_path}\")\n\n"
+        "        # Plot 3: Ground Track Map\n"
+        "        plt.figure(figsize=(10, 5))\n"
+        "        plt.plot(df['longitude'], df['latitude'], color='red', marker='x', label='ISS Ground Track')\n"
+        "        plt.title('ISS Ground Track Orbit Trajectory')\n"
+        "        plt.xlabel('Longitude (°)')\n"
+        "        plt.ylabel('Latitude (°)')\n"
+        "        plt.xlim(-180, 180)\n"
+        "        plt.ylim(-90, 90)\n"
+        "        plt.grid(True, linestyle='--', alpha=0.6)\n"
+        "        plt.legend()\n"
+        "        track_path = os.path.join(OUTPUT_DIR, 'iss_ground_track.png')\n"
+        "        plt.savefig(track_path, dpi=150, bbox_inches='tight')\n"
+        "        plt.close()\n"
+        "        print(f\"✓ Saved Ground Track Map to: {track_path}\")\n"
+        "    else:\n"
+        "        print(\"\\nℹ️  Notice: matplotlib not installed. Statistical metrics printed above; plot generation skipped.\")\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # dashboard.py
+    files["dashboard.py"] = (
+        "import os\n"
+        "import pandas as pd\n"
+        "import streamlit as st\n\n"
+        "st.set_page_config(page_title='Program 11: ISS Orbit Tracker', layout='wide')\n"
+        "st.title('🛰️ ISS Real-Time Location & Orbital Trajectory Dashboard')\n"
+        "st.caption('MSc/MCA IoT Practical — Program 11 (ISS Location Tracking & Analytics)')\n\n"
+        "CSV_PATH = os.path.join(os.path.dirname(__file__), 'data', 'iss_locations.csv')\n\n"
+        "if not os.path.exists(CSV_PATH) or os.path.getsize(CSV_PATH) == 0:\n"
+        "    st.warning('No ISS telemetry found. Run `python collector.py --count 100 --interval 5` to collect orbital data.')\n"
+        "else:\n"
+        "    df = pd.read_csv(CSV_PATH)\n"
+        "    st.success(f'Loaded {len(df)} orbital observations.')\n\n"
+        "    latest = df.iloc[-1]\n"
+        "    col1, col2, col3 = st.columns(3)\n"
+        "    col1.metric('Latest Latitude', f\"{latest['latitude']:.4f} °\")\n"
+        "    col2.metric('Latest Longitude', f\"{latest['longitude']:.4f} °\")\n"
+        "    col3.metric('Telemetry Source', str(latest.get('source', 'API')))\n\n"
+        "    st.subheader('🗺️ Orbital Ground Track Map')\n"
+        "    map_df = df[['latitude', 'longitude']].rename(columns={'latitude': 'lat', 'longitude': 'lon'})\n"
+        "    st.map(map_df)\n\n"
+        "    st.subheader('📈 Telemetry Trends')\n"
+        "    tcol1, tcol2 = st.columns(2)\n"
+        "    with tcol1:\n"
+        "        st.line_chart(df['latitude'], use_container_width=True)\n"
+        "        st.caption('Latitude vs Time')\n"
+        "    with tcol2:\n"
+        "        st.line_chart(df['longitude'], use_container_width=True)\n"
+        "        st.caption('Longitude vs Time')\n\n"
+        "    st.subheader('📋 Collected Records Table')\n"
+        "    st.dataframe(df, use_container_width=True)\n"
+    )
+
+    # Initial sample CSV records for offline verification
+    files["data/iss_locations.csv"] = (
+        "timestamp,iso_datetime,latitude,longitude,source\n"
+        "1730560000,2024-11-02 15:06:40 UTC,14.8521,52.1245,Open-Notify\n"
+        "1730560005,2024-11-02 15:06:45 UTC,15.1204,52.4120,Open-Notify\n"
+        "1730560010,2024-11-02 15:06:50 UTC,15.3887,52.6998,Open-Notify\n"
+        "1730560015,2024-11-02 15:06:55 UTC,15.6569,52.9878,Open-Notify\n"
+        "1730560020,2024-11-02 15:07:00 UTC,15.9251,53.2761,Open-Notify\n"
+    )
+
+    # README.md
+    if mode == "learning":
+        readme_content = (
+            "# Program 11 — ISS Real-Time Location Tracking & Trajectory Analysis\n\n"
+            "## 1. Overview\n"
+            "This practical tracks and analyzes the real-time orbit of the International Space Station (ISS):\n"
+            "- Collects authentic orbital coordinates from **Open-Notify API** (`http://api.open-notify.org/iss-now.json`) with verified fallback to **WhereTheISS** (`https://api.wheretheiss.at/v1/satellites/25544`).\n"
+            "- Samples 100 observations at 5-second intervals.\n"
+            "- Computes ground distance using the Haversine formula and estimates orbital velocity.\n"
+            "- Plots Latitude vs Time, Longitude vs Time, and renders a Streamlit geospatial trajectory dashboard.\n\n"
+            "## 2. Collection Time Estimation\n"
+            "The time required to collect the full 100-sample dataset is calculated as:\n"
+            "$$\\text{Total Duration} = N \\times \\Delta t = 100 \\times 5\\text{ seconds} = 500\\text{ seconds} \\approx 8.33\\text{ minutes}$$\n\n"
+            "## 3. Step-by-Step Execution Guide\n\n"
+            "### Step A: Install Dependencies\n"
+            "```bash\n"
+            "pip install -r requirements.txt\n"
+            "```\n\n"
+            "### Step B: Collect 100 Live Records\n"
+            "```bash\n"
+            "python collector.py --count 100 --interval 5\n"
+            "```\n\n"
+            "### Step C: Run Statistical & Trajectory Analysis\n"
+            "```bash\n"
+            "python analyzer.py\n"
+            "```\n"
+            "This generates 3 charts in `output/`:\n"
+            "- `iss_latitude_trend.png`\n"
+            "- `iss_longitude_trend.png`\n"
+            "- `iss_ground_track.png`\n\n"
+            "### Step D: Launch Interactive Dashboard\n"
+            "```bash\n"
+            "streamlit run dashboard.py\n"
+            "```\n\n"
+            "## 4. Viva Questions and Answers\n"
+            "**Q1: What is the approximate speed and altitude of the ISS?**  \n"
+            "A: The ISS orbits Earth at an altitude of approximately 400–420 km and travels at approximately 27,600 km/h (~7.66 km/s), completing one full orbit every 90–93 minutes.\n\n"
+            "**Q2: Why does the ISS ground track appear sinusoidal on a 2D map?**  \n"
+            "A: The ISS has an orbital inclination of 51.6° to Earth's equator. Projecting its circular orbit onto a cylindrical 2D map projection yields a characteristic sine-wave trajectory as Earth rotates underneath.\n"
+        )
+    else:
+        readme_content = (
+            "# Program 11 — ISS Location Tracking (Exam Mode)\n\n"
+            "## Execution\n"
+            "1. Collect telemetry:\n"
+            "   ```bash\n"
+            "   python collector.py --count 100 --interval 5\n"
+            "   ```\n"
+            "2. Analyze records & generate plots:\n"
+            "   ```bash\n"
+            "   python analyzer.py\n"
+            "   ```\n"
+            "3. View dashboard:\n"
+            "   ```bash\n"
+            "   streamlit run dashboard.py\n"
+            "   ```\n\n"
+            "## Viva Q&A\n"
+            "- **Q: How long does collecting 100 samples take?**  \n"
+            "  A: 100 samples * 5 seconds = 500 seconds (~8 minutes 20 seconds).\n"
+            "- **Q: What is the Haversine formula?**  \n"
+            "  A: An equation in spherical trigonometry that calculates the great-circle distance between two pairs of latitude and longitude coordinates on a sphere.\n"
+        )
+
+    files["README.md"] = readme_content
+    return files