3D Heatmap Visualization

A beautiful 3D heatmap visualization app built with SwiftUI and Metal, designed to display GitHub-style contribution data in an interactive 3D environment.

Features

• 3D Interactive Visualization: Navigate through your data with intuitive gesture controls
• Trackball Rotation: Smooth rotation with inertia physics for natural interaction
• Pinch-to-Zoom: Scale the visualization to focus on specific areas
• Month Labels: Clear temporal indicators for better data understanding
• High Performance: Leverages Metal for smooth 60fps rendering
• Modern UI: Clean SwiftUI interface with gesture control toggles

Screenshots

Technical Highlights

• Metal Rendering: Custom Metal shaders for high-performance 3D graphics
• Trackball Algorithm: Intuitive 3D rotation mapping from 2D touch gestures
• Inertia Physics: Natural momentum-based rotation with configurable decay
• Texture-based Labels: Efficient text rendering using Metal textures
• Multi-sampling: 4x MSAA for smooth anti-aliased graphics

Requirements

• iOS 14.0+
• Xcode 12.0+
• Swift 5.0+
• Metal-compatible device

Installation

1. Clone the repository:

git clone https://github.com/linghugoogle/ThreeDHeatmap.git

2. Open ThreeDHeatmap.xcodeproj in Xcode
3. Build and run the project on your device or simulator

Usage

Basic Controls

• Drag: Rotate the 3D heatmap around its center
• Pinch: Zoom in/out to scale the visualization
• Toggle: Use the gesture control switch to enable/disable interactions

Data Structure

The heatmap displays a 52×7 grid representing:

• Weeks: 52 weeks of the year (X-axis)
• Days: 7 days of the week (Y-axis)
• Intensity: Height and color represent data values (Z-axis)

Architecture

Core Components

• MetalRenderer: Main rendering engine handling 3D graphics
• HeatmapView: SwiftUI wrapper for Metal view with gesture handling
• Shaders.metal: Custom Metal shaders for vertex and fragment processing
• ContentView: Main UI with controls and layout

Key Algorithms

• Trackball Mapping: Converts 2D screen coordinates to 3D rotation vectors
• Matrix Transformations: Model-View-Projection pipeline for 3D rendering
• Inertia System: Physics-based momentum for natural interaction feel

Customization

Modifying Data

Edit the generateHeatmapData() method in MetalRenderer.swift:

private func generateHeatmapData() {
    // Customize your data generation logic here
    for week in 0..<52 {
        var weekData: [Float] = []
        for day in 0..<7 {
            let intensity = Float.random(in: 0...1)
            weekData.append(intensity)
        }
        heatmapData.append(weekData)
    }
}

Adjusting Colors

Modify the colorForIntensity() method to change the color scheme:

private func colorForIntensity(_ intensity: Float) -> simd_float4 {
    // Customize your color mapping here
    return simd_float4(intensity, 0.5, 1.0 - intensity, 1.0)
}

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by GitHub's contribution graph
• Built with Apple's Metal framework
• Uses SwiftUI for modern iOS development

Contact

• GitHub: @linghugoogle
• Email: [email protected]

---

Note: This project demonstrates advanced iOS development techniques including Metal rendering, 3D mathematics, and gesture handling. It's perfect for learning about high-performance graphics programming on iOS.