irrigation

🌱 نظام الري الذكي لملاعب كرة القدم في الرياض

AI-Powered Irrigation System for Football Stadiums in Riyadh

<div align="center">

نظام ذكي يستخدم تعلم الآلة للتنبؤ باحتياجات الري لملاعب كرة القدم في الرياض بناءً على بيانات الطقس.

An intelligent system using machine learning to predict irrigation needs for football stadiums in Riyadh based on weather data.

</div>

---

📑 جدول المحتويات / Table of Contents

• 🎯 المميزات الرئيسية
• 🚀 التشغيل السريع
  • الخطوة 1: تحميل المشروع
  • الخطوة 2: تثبيت المتطلبات
  • الخطوة 3: تشغيل المشروع
  • الخطوة 4: فتح الموقع
  • الخطوة 5: استخدام النظام
• 🔧 استكشاف الأخطاء
• 📡 API Endpoints
• 📊 البيانات
• 🛠️ التقنيات المستخدمة
• 📁 هيكل المشروع
• 📖 التوثيق
• 🎨 لقطات الشاشة
• 📄 الترخيص

---

🎯 المميزات الرئيسية / Key Features

🤖 نموذج تعلم آلي متقدم

• دقة 99.3% في التنبؤ باحتياجات الري
• استخدام خوارزمية Random Forest
• تدريب على 12+ سنة من بيانات الطقس (4,689 يوم)
• حساب ET0 و ETc باستخدام معادلة FAO Penman-Monteith

🌡️ بيانات طقس واقعية

• تغيرات يومية في درجة الحرارة والرطوبة
• احتمالية أمطار (5% في الشتاء، 1% في الصيف)
• محاكاة واقعية للظروف الجوية

⏰ أوقات ري ذكية

• 3 جلسات (05:00, 12:00, 19:00) - عندما تكون الحرارة > 40°C والرطوبة < 20%
• 2 جلسات (05:00, 19:00) - عندما تكون الحرارة > 35°C أو الرطوبة < 25%
• 1 جلسة (06:00) - في الظروف المعتدلة

📅 اختيار مرن للتواريخ

• عدة أيام: اختر 3، 7، 14، أو 30 يوم
• يوم محدد: اختر أي يوم حتى 30 يوم قادم
• عرض تفصيلي للطقس المتوقع لكل يوم

🏟️ مراقبة 6 ملاعب رئيسية

1. ملعب الملك فهد الدولي
2. ملعب الأمير فيصل بن فهد
3. ملعب الأمير عبدالله الفيصل
4. ملعب الملك سعود الجامعي
5. ملعب الأمير سعود بن جلوي
6. ملعب الأمير تركي بن عبدالعزيز

---

🚀 التشغيل السريع / Quick Start

الخطوة 1️⃣: تحميل المشروع / Download Project

الطريقة الأولى: استخدام Git

# Clone the repository
git clone https://github.com/M-craspo/riyadh-pitch-ai-irrigation.git

# الدخول إلى مجلد المشروع
cd riyadh-pitch-ai-irrigation

الطريقة الثانية: تحميل ZIP

1. اذهب إلى: https://github.com/M-craspo/riyadh-pitch-ai-irrigation
2. اضغط على الزر الأخضر "Code"
3. اختر "Download ZIP"
4. فك الضغط عن الملف
5. افتح Terminal/CMD في مجلد المشروع

---

الخطوة 2️⃣: تثبيت المتطلبات / Install Requirements

المتطلبات الأساسية / Prerequisites

تأكد من تثبيت:

• ✅ Python 3.8+ - تحميل Python
• ✅ Node.js 18+ - تحميل Node.js
• ✅ pip (يأتي مع Python)
• ✅ npm (يأتي مع Node.js)

تثبيت مكتبات Backend (Python)

# الدخول إلى مجلد Backend
cd irrigation_model

# تثبيت المكتبات المطلوبة
pip install -r requirements.txt

# أو استخدم pip3 إذا كان لديك Python 2 و 3
pip3 install -r requirements.txt

# العودة إلى المجلد الرئيسي
cd ..

المكتبات التي سيتم تثبيتها:

• Flask (REST API)
• scikit-learn (Machine Learning)
• pandas (Data Processing)
• numpy (Numerical Computing)
• flask-cors (CORS Support)

تثبيت مكتبات Frontend (Node.js)

# الدخول إلى مجلد Frontend
cd frontend

# تثبيت المكتبات المطلوبة
npm install

# العودة إلى المجلد الرئيسي
cd ..

المكتبات التي سيتم تثبيتها:

• React 18
• TypeScript
• Vite
• TanStack Query
• Tailwind CSS
• shadcn/ui components
• Lucide React (Icons)

---

الخطوة 3️⃣: تشغيل المشروع / Run Project

✨ الطريقة الأولى: سكريبت تلقائي (الأسهل)

على macOS/Linux:

# إعطاء صلاحية التنفيذ
chmod +x start.sh

# تشغيل السكريبت
./start.sh

على Windows:

# تشغيل Backend
start cmd /k "cd irrigation_model && python api.py"

# تشغيل Frontend (في نافذة جديدة)
start cmd /k "cd frontend && npm run dev"

🔧 الطريقة الثانية: يدوياً (خطوة بخطوة)

1. تشغيل Backend (نافذة Terminal أولى):

# الدخول إلى مجلد Backend
cd irrigation_model

# تشغيل API Server
python3 api.py

# أو استخدم python بدلاً من python3
python api.py

✅ ستظهر رسالة:

 * Running on http://127.0.0.1:5001
 * Model loaded successfully!
 * Ready to serve predictions

الخادم سيعمل على: http://localhost:5001

2. تشغيل Frontend (نافذة Terminal ثانية - جديدة):

# افتح نافذة Terminal جديدة
# الدخول إلى مجلد Frontend
cd frontend

# تشغيل Development Server
npm run dev

✅ ستظهر رسالة:

  VITE v5.4.19  ready in 170 ms

  ➜  Local:   http://localhost:8080/
  ➜  Network: http://192.168.x.x:8080/

الموقع سيعمل على: http://localhost:8080

---

الخطوة 4️⃣: فتح الموقع / Open Website

1. افتح المتصفح (Chrome, Firefox, Safari, Edge)
2. اذهب إلى: http://localhost:8080
3. ستظهر لك واجهة نظام الري الذكي! 🎉

---

الخطوة 5️⃣: استخدام النظام / Use System

📊 عرض البيانات الحالية

• ستجد 6 بطاقات لملاعب الرياض الرئيسية
• كل بطاقة تعرض:
  • 🌡️ درجة الحرارة الحالية
  • 💧 الرطوبة الحالية
  • 💦 احتياجات المياه (m³ ولتر)
  • ⏰ جلسات الري (الوقت، الكمية، المدة)

📅 اختيار التاريخ

في كل بطاقة ملعب، ستجد قسم "جدول الري المستقبلي":

خيار 1: عدة أيام

1. اضغط على زر "عدة أيام"
2. اختر عدد الأيام: 3، 7، 14، أو 30 يوم
3. اضغط "عرض الجدول"
4. ستظهر جدول تفصيلي لكل يوم مع:
   • التاريخ واليوم
   • الطقس المتوقع (حرارة، رطوبة، أمطار)
   • احتياجات المياه
   • جلسات الري

خيار 2: يوم محدد

1. اضغط على زر "يوم محدد"
2. اختر التاريخ من التقويم (حتى 30 يوم قادم)
3. اضغط "عرض التنبؤ"
4. ستظهر تفاصيل اليوم المحدد فقط

---

🛑 إيقاف التشغيل / Stop Running

لإيقاف الخوادم:

• اضغط Ctrl + C في كل نافذة Terminal
• أو أغلق نوافذ Terminal مباشرة

---

🔧 استكشاف الأخطاء / Troubleshooting

❌ مشكلة: Backend لا يعمل

الخطأ: ModuleNotFoundError: No module named 'flask'

الحل:

cd irrigation_model
pip install -r requirements.txt

---

الخطأ: Port 5001 is already in use

الحل:

# على macOS/Linux
lsof -ti:5001 | xargs kill -9

# على Windows
netstat -ano | findstr :5001
taskkill /PID <PID_NUMBER> /F

---

الخطأ: python: command not found

الحل:

• استخدم python3 بدلاً من python
• أو قم بتثبيت Python من: https://www.python.org/downloads/

---

❌ مشكلة: Frontend لا يعمل

الخطأ: npm: command not found

الحل:

• قم بتثبيت Node.js من: https://nodejs.org/

---

الخطأ: Port 8080 is already in use

الحل:

# على macOS/Linux
lsof -ti:8080 | xargs kill -9

# على Windows
netstat -ano | findstr :8080
taskkill /PID <PID_NUMBER> /F

أو غيّر المنفذ في frontend/vite.config.ts:

server: {
  port: 3000, // غيّر إلى منفذ آخر
}

---

الخطأ: Failed to fetch في المتصفح

الحل:

• تأكد من تشغيل Backend على http://localhost:5001
• افتح http://localhost:5001/api/health في المتصفح
• يجب أن ترى: {"status": "healthy", "model_loaded": true}

---

❌ مشكلة: البيانات لا تظهر

الحل:

1. افتح Developer Tools في المتصفح (F12)
2. اذهب إلى تبويب Console
3. ابحث عن أخطاء باللون الأحمر
4. تأكد من أن Backend يعمل
5. تأكد من أن Frontend متصل بـ Backend

---

❌ مشكلة: التاريخ المحدد لا يعمل

الحل:

• تأكد من اختيار تاريخ بين اليوم و 30 يوم قادم
• تأكد من الضغط على زر "عرض التنبؤ"
• تحقق من Console في المتصفح

---

📞 الدعم / Support

إذا واجهت أي مشكلة:

1. تحقق من قسم استكشاف الأخطاء أعلاه
2. افتح Issue على GitHub: https://github.com/M-craspo/riyadh-pitch-ai-irrigation/issues
3. قدم معلومات عن:
   • نظام التشغيل (Windows/macOS/Linux)
   • إصدار Python (python --version)
   • إصدار Node.js (node --version)
   • رسالة الخطأ الكاملة
   • لقطة شاشة إن أمكن

---

📡 API Endpoints

1. التنبؤ ليوم واحد

POST /api/predict
Content-Type: application/json

{
  "T2M_MIN": 20,
  "T2M_MAX": 39,
  "RH2M": 20,
  "WS2M": 2.5
}

2. جدول عدة أيام

POST /api/schedule
Content-Type: application/json

{
  "days": 7,
  "current_weather": {
    "T2M_MIN": 20,
    "T2M_MAX": 39,
    "RH2M": 20,
    "WS2M": 2.5
  }
}

3. التنبؤ بيوم محدد

POST /api/predict-date
Content-Type: application/json

{
  "date": "2025-11-30",
  "current_weather": {
    "T2M_MIN": 20,
    "T2M_MAX": 39,
    "RH2M": 20,
    "WS2M": 2.5
  }
}

4. فحص صحة النظام

GET /api/health

5. إحصائيات النموذج

GET /api/stats

Response:

{
  "success": true,
  "stats": {
    "model_type": "RandomForestRegressor",
    "accuracy": 99.3,
    "training_samples": 4689,
    "features": ["T2M_MIN", "T2M_MAX", "RH2M", "WS2M", "PRECTOTCORR", "ALLSKY_SFC_SW_DWN"]
  }
}

---

💡 أمثلة الاستخدام / Usage Examples

مثال 1: الحصول على تنبؤ ليوم واحد

curl -X POST http://localhost:5001/api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "T2M_MIN": 25,
    "T2M_MAX": 42,
    "RH2M": 18,
    "WS2M": 3.2
  }'

النتيجة:

{
  "success": true,
  "irrigation_m3": 71.58,
  "irrigation_liters": 71580,
  "sessions": [
    {"time": "05:00", "water_m3": 35.79, "duration_minutes": 30},
    {"time": "19:00", "water_m3": 35.79, "duration_minutes": 30}
  ]
}

---

مثال 2: الحصول على جدول 7 أيام

curl -X POST http://localhost:5001/api/schedule \
  -H "Content-Type: application/json" \
  -d '{
    "days": 7,
    "current_weather": {
      "T2M_MIN": 25,
      "T2M_MAX": 42,
      "RH2M": 18,
      "WS2M": 3.2
    }
  }'

---

مثال 3: التنبؤ بيوم محدد

curl -X POST http://localhost:5001/api/predict-date \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2025-12-01",
    "current_weather": {
      "T2M_MIN": 20,
      "T2M_MAX": 35,
      "RH2M": 30,
      "WS2M": 2.5
    }
  }'

---

مثال 4: استخدام من JavaScript

// الحصول على تنبؤ
async function getPrediction() {
  const response = await fetch('http://localhost:5001/api/predict', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      T2M_MIN: 25,
      T2M_MAX: 42,
      RH2M: 18,
      WS2M: 3.2
    })
  });

  const data = await response.json();
  console.log('احتياجات المياه:', data.irrigation_liters, 'لتر');
  console.log('عدد الجلسات:', data.sessions.length);
}

getPrediction();

---

مثال 5: استخدام من Python

import requests
import json

# الحصول على جدول 14 يوم
url = 'http://localhost:5001/api/schedule'
data = {
    'days': 14,
    'current_weather': {
        'T2M_MIN': 25,
        'T2M_MAX': 42,
        'RH2M': 18,
        'WS2M': 3.2
    }
}

response = requests.post(url, json=data)
result = response.json()

if result['success']:
    for day in result['schedule']:
        print(f"التاريخ: {day['date']}")
        print(f"المياه: {day['irrigation_liters']:,} لتر")
        print(f"الجلسات: {len(day['sessions'])}")
        print("---")

---

📊 البيانات / Data

• مصدر البيانات: NASA POWER API
• الفترة الزمنية: 2013-2025 (12+ سنة)
• عدد السجلات: 4,689 يوم
• الموقع: الرياض (24.71°N, 46.71°E)

المتغيرات المستخدمة:

• T2M_MIN: درجة الحرارة الصغرى (°C)
• T2M_MAX: درجة الحرارة العظمى (°C)
• RH2M: الرطوبة النسبية (%)
• WS2M: سرعة الرياح (m/s)
• PRECTOTCORR: الأمطار (mm)
• ALLSKY_SFC_SW_DWN: الإشعاع الشمسي (MJ/m²/day)

---

🛠️ التقنيات المستخدمة / Technologies

Backend

• Python 3.x
• Flask - REST API
• scikit-learn - Random Forest Model
• pandas & NumPy - Data Processing
• FAO Penman-Monteith - ET Calculation

Frontend

• React 18 with TypeScript
• Vite - Build Tool
• TanStack Query - Data Fetching
• Tailwind CSS - Styling (RTL Support)
• shadcn/ui - UI Components
• Lucide React - Icons

---

📁 هيكل المشروع / Project Structure

riyadh-pitch-ai-irrigation/
├── irrigation_model/          # Backend (Python/Flask)
│   ├── api.py                # REST API
│   ├── irrigation_predictor.py  # ML Model
│   ├── data_preprocessing.py    # Data Processing
│   ├── train_model.py        # Model Training
│   ├── trained_model.pkl     # Trained Model
│   └── requirements.txt      # Python Dependencies
│
├── frontend/                 # Frontend (React/TypeScript)
│   ├── src/
│   │   ├── components/       # React Components
│   │   ├── services/         # API Services
│   │   └── pages/            # Pages
│   └── package.json          # Node Dependencies
│
├── POWER_Point_Daily_*.xlsx  # NASA Weather Data
├── Riyadh_sprinkler_*.xlsx   # Irrigation Data
├── start.sh                  # Startup Script
└── README.md                 # This File

---

📖 التوثيق / Documentation

• REALISTIC_IRRIGATION_UPDATE.md - شرح تفصيلي للنظام الواقعي
• تقرير_نظام_الري_الذكي.docx - التقرير الكامل بالعربية
• irrigation_model/README.md - توثيق Backend
• frontend/README.md - توثيق Frontend

---

🎨 لقطات الشاشة / Screenshots

الموقع يعرض:

• ✅ معلومات كل ملعب بشكل منفصل
• ✅ الظروف الجوية الحالية والمتوقعة
• ✅ احتياجات المياه (m³ ولتر)
• ✅ جدول جلسات الري (الوقت، الكمية، المدة)
• ✅ اختيار يوم محدد أو عدة أيام
• ✅ واجهة عربية 100% مع أرقام إنجليزية

---

❓ الأسئلة الشائعة / FAQ

س1: هل يعمل النظام بدون إنترنت؟

ج: نعم! بعد تحميل المشروع وتثبيت المكتبات، يعمل النظام بالكامل على جهازك المحلي بدون الحاجة للإنترنت.

س2: كيف يتم حساب احتياجات المياه؟

ج: النظام يستخدم:

1. معادلة FAO Penman-Monteith لحساب ET0 (التبخر المرجعي)
2. معامل المحصول (Kc) للعشب = 0.85
3. مساحة الملعب = 7,140 m²
4. نموذج Random Forest المدرب على 12+ سنة من البيانات

س3: ما مدى دقة التنبؤات؟

ج: النموذج حقق دقة 99.3% على بيانات الاختبار، مع:

• R² Score: 0.993
• MAE: 0.42 m³
• RMSE: 0.58 m³

س4: لماذا تختلف أوقات الري؟

ج: النظام يحدد عدد الجلسات بناءً على الظروف الجوية:

• حار جداً (>40°C، <20% رطوبة): 3 جلسات (05:00, 12:00, 19:00)
• حار (>35°C، <25% رطوبة): 2 جلسات (05:00, 19:00)
• معتدل: 1 جلسة (06:00)

س5: هل يمكن إضافة ملاعب جديدة؟

ج: نعم! يمكنك تعديل ملف frontend/src/components/sections/EnhancedDashboardSection.tsx وإضافة ملاعب جديدة بنفس الصيغة.

س6: هل يمكن تغيير مساحة الملعب؟

ج: نعم! في ملف irrigation_model/irrigation_predictor.py، غيّر قيمة:

self.field_area_m2 = 7140  # غيّر هذا الرقم

س7: كيف أحدّث بيانات الطقس؟

ج: يمكنك:

1. تحميل بيانات جديدة من NASA POWER
2. استبدال ملف POWER_Point_Daily_*.xlsx
3. إعادة تدريب النموذج: python irrigation_model/train_model.py

س8: هل يدعم النظام لغات أخرى؟

ج: حالياً النظام بالعربية فقط. لإضافة لغات أخرى، يمكنك:

1. إضافة ملفات ترجمة في frontend/src/locales/
2. استخدام مكتبة i18next للترجمة

س9: كيف أنشر النظام على الإنترنت؟

ج: يمكنك استخدام:

• Backend: Heroku, Railway, Render, DigitalOcean
• Frontend: Vercel, Netlify, GitHub Pages
• الكل معاً: Docker + AWS/Azure/GCP

س10: هل يمكن استخدام النظام لمحاصيل أخرى؟

ج: نعم! غيّر معامل المحصول (Kc) في irrigation_predictor.py:

self.kc = 0.85  # للعشب
# self.kc = 1.15  # للطماطم
# self.kc = 0.60  # للقمح

---

🔄 التحديثات المستقبلية / Future Updates

• إضافة دعم لأجهزة الاستشعار (IoT)
• تطبيق موبايل (React Native)
• إشعارات تلقائية (Push Notifications)
• تقارير PDF قابلة للتحميل
• دعم متعدد اللغات (إنجليزي، فرنسي)
• تكامل مع أنظمة الري الآلية
• لوحة تحكم للمسؤولين
• تحليلات متقدمة وإحصائيات
• دعم قواعد بيانات (PostgreSQL/MongoDB)
• API Authentication (JWT)

---

🤝 المساهمة / Contributing

نرحب بالمساهمات! إذا كنت تريد المساهمة:

1. Fork المشروع
2. أنشئ Branch جديد (git checkout -b feature/amazing-feature)
3. Commit تغييراتك (git commit -m 'Add amazing feature')
4. Push إلى Branch (git push origin feature/amazing-feature)
5. افتح Pull Request

إرشادات المساهمة:

• اكتب كود نظيف ومنظم
• أضف تعليقات توضيحية
• اختبر التغييرات قبل الـ Push
• اتبع نمط الكود الموجود
• حدّث التوثيق إذا لزم الأمر

---

🙏 شكر وتقدير / Acknowledgments

• NASA POWER - بيانات الطقس المجانية
• FAO - معادلات حساب ET
• scikit-learn - مكتبة Machine Learning
• React - مكتبة واجهات المستخدم
• shadcn/ui - مكونات الواجهة الجميلة
• Tailwind CSS - إطار عمل CSS
• Vite - أداة البناء السريعة
• Flask - إطار عمل Python

---

🔗 روابط مفيدة / Useful Links

المشروع

• 🏠 GitHub Repository: https://github.com/M-craspo/riyadh-pitch-ai-irrigation
• 📝 Issues: https://github.com/M-craspo/riyadh-pitch-ai-irrigation/issues
• 🔀 Pull Requests: https://github.com/M-craspo/riyadh-pitch-ai-irrigation/pulls

التوثيق

• 📖 README الرئيسي: README.md
• 📄 توثيق Backend: irrigation_model/README.md
• 📄 توثيق Frontend: frontend/README.md
• 📊 التحديث الواقعي: REALISTIC_IRRIGATION_UPDATE.md

المراجع العلمية

• 📚 FAO Penman-Monteith: http://www.fao.org/3/x0490e/x0490e00.htm
• 📚 Crop Evapotranspiration: http://www.fao.org/3/x0490e/x0490e06.htm
• 📚 NASA POWER Documentation: https://power.larc.nasa.gov/docs/
• 📚 Random Forest Algorithm: https://scikit-learn.org/stable/modules/ensemble.html#forest

الأدوات والمكتبات

• 🐍 Python: https://www.python.org/
• 📦 pip: https://pip.pypa.io/
• 🟢 Node.js: https://nodejs.org/
• 📦 npm: https://www.npmjs.com/
• ⚛️ React: https://react.dev/
• 🎨 Tailwind CSS: https://tailwindcss.com/
• 🧩 shadcn/ui: https://ui.shadcn.com/

---

📊 الإحصائيات / Statistics

<div align="center"> </div>

---

📸 معرض الصور / Gallery

واجهة النظام

┌─────────────────────────────────────────────────────────┐
│  🌱 نظام الري الذكي لملاعب كرة القدم في الرياض        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  ملعب الملك فهد الدولي                 ✅ مثالي │  │
│  ├──────────────────────────────────────────────────┤  │
│  │  🌡️ الحرارة: 39°C    💧 الرطوبة: 20%          │  │
│  │                                                  │  │
│  │  💧 احتياجات المياه                             │  │
│  │  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │  │
│  │  إجمالي المياه: 68.5 m³ (68,550 لتر)          │  │
│  │                                                  │  │
│  │  ⏰ جلسات الري (2 جلسات)                       │  │
│  │  ┌────────────────────────────────────────────┐ │  │
│  │  │ 🕔 05:00 | 💧 34.3 m³ | ⏱️ 30 دقيقة      │ │  │
│  │  │ 🕖 19:00 | 💧 34.3 m³ | ⏱️ 30 دقيقة      │ │  │
│  │  └────────────────────────────────────────────┘ │  │
│  │                                                  │  │
│  │  📅 جدول الري المستقبلي                        │  │
│  │  [عدة أيام] [يوم محدد]                         │  │
│  │  اختر: [3] [7] [14] [30] يوم  [عرض الجدول]   │  │
│  └──────────────────────────────────────────────────┘  │
│                                                         │
│  [5 ملاعب أخرى...]                                    │
└─────────────────────────────────────────────────────────┘

---

🎓 تعلم المزيد / Learn More

للمبتدئين

• 📖 دليل Python للمبتدئين
• 📖 دليل React للمبتدئين
• 📖 أساسيات Machine Learning

للمتقدمين

• 📖 Flask Advanced Patterns
• 📖 React Performance
• 📖 scikit-learn Advanced

الري والزراعة

• 📖 FAO Irrigation Manual
• 📖 Turfgrass Irrigation
• 📖 Smart Irrigation

---