Project Stormchaser 🌀

Project Stormchaser is an animation engine that visualizes real-time tropical storm data of the past. It scrapes data from the IBTRACS website and filters the information by year and basin according to user input. It then displays an animation of tropical storms paths as they occur at the current time, accurate to every 3-hour interval.

Stormchaser is also available bundled as a Windows executable. Please see releases for app installation.

🌟 Features

• Supports 5 Different Regions: Northern Atlantic, Eastern & Western Pacific, Northern & Southern Indian
• Real-time Typhoon Tracking: Visualizes typhoon paths with smooth animations
• Dynamic Color Coding: Changes typhoon colors based on intensity categories
• Landfall Detection: Automatically detects and marks typhoon landfall points
• Detailed Information Display: Shows typhoon names, wind speeds, and pressure data
• Interactive Timeline: Includes a time display that matches the simulation accurately
• UI Elements: Play / Pause, Skip 1 Week, and Return to Main Menu
• Data Caching: Stores previously webscraped data to your computer for faster retrieval

🛠 Technical Components

Map Generation (map_maker.py)

• Creates high-resolution maps of tropcial storm basins
• Utilizes Cartopy for accurate geographical projections
• Supports both detailed and simplified map versions
• Features include land masses, ocean, country borders, and basic elevation data

Typhoon Data Scraper (typhoon_scraper.py)

• Scrapes typhoon data from Digital Typhoon database
• Extracts detailed track information including:
  • Position (latitude/longitude)
  • Wind speeds
  • Pressure data
  • Timestamps
• Caches data as a .JSON to root/data folder

Visualization Engine (stormchaser.py)

• Built with Pygame for smooth real-time animations
• Features include:
  • Rotating typhoon symbols
  • Color-coded intensity levels
  • Dynamic fade in/out effects
  • Landfall detection and marking
  • Time scaling for visualization
  • Pause / Play
  • Skip 1 Week

🎨 Visualization Features

Typhoon Representation

• Symbol: Animated rotating spiral with center dot
• Color Coding:

  category_colors = {
      0: (135, 206, 235),  # Light Blue
      1: (100, 238, 100),  # Light Green
      2: (225, 225, 0),    # Yellow
      3: (255, 130, 0),    # Orange
      4: (255, 0, 0),      # Red
      5: (255, 0, 255)     # Purple
  }

• Information Display: Shows name, wind speed (kt), and pressure (hPa)

Animation Effects

• Smooth fade-in/fade-out transitions
• Constant speed movement between track points
• Rotating blade animation
• Dynamic landfall markers with zoom effects

🚀 Getting Started

Cloning the Project

git clone https://github.com/TreacherousDev/Stormchaser

Installing Prerequisites

pip install -r requirements.txt

Required packages:

• pygame
• requests
• beautifulsoup4
• cartopy
• matplotlib
• numpy

Running the Application

1. Generate the map (first run only):

   python scripts/map_maker.py

2. Start the visualization:

   python scripts/stormchaser.py

Controls

• Click the "Play" button to start the animation
• Click the "Pause" button to pause the animation
• Click the "Skip 1 Week" button to jump 1 week forward into the timeline
• Click the "Return to Menu" button to regenerate an animation
• Close window to exit

📊 Data Structure

Typhoon Object Format

{
    "name": str,            # Typhoon name
    "path": [{
        "time": str,        # Format: "YYYY-MM-DD HH:MM"
        "lat": float,       # Latitude
        "long": float,      # Longitude
        "class": int,       # Intensity category (0-5)
        "speed": str,       # Wind speed in km/h
        "pressure": int     # Pressure in hPa
    }],
    "start_time": int       # Animation start time offset
}

⚙️ Configuration

Key parameters that can be adjusted:

# Time scaling
TIME_SCALE_FACTOR = 1 / (12 * 60 * 60)  # 1 second = 12 hours

# Screen dimensions
SCREEN_WIDTH, SCREEN_HEIGHT = 1200, 900

# Animation parameters
fade_in_duration = 1
fade_out_duration = 0.5
fps_target = 120

🛠️ Building from Source

1. Install pyinstaller

pip install pyinstaller

2. Navigate to the root folder (example):

cd C:\Users\User\Documents\GitHub\Project Stormchaser

3. Run the following command:

pyinstaller --add-data "resources/*;resources" --add-data "data/*;data" --noconsole --icon=resources\_stormchaser.ico scripts/stormchaser.py

4. View the output dist folder in file explorer and go inside _internals

5. Move both the data and resources folder outside, so the structure will look like this:

─dist
│   └───stormchaser
│       ├───data
│       ├───resources
│       └───_internal
│           ├───cartopy
│           ├───certifi
│           ├───...other

6. Launch the executable located inside stormchaser, and ensure it is working correctly.

7. You can now package stormchaser as a ZIP, or use software installer setups like Inno Setup Compiler

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🙏 Acknowledgments

• Data source: IBTRACS
• Map data: Natural Earth via Cartopy
• Compilation: Hispano @zk12-dev