SPIRAL - Teknofest 2025

SpirAi takımı tarafından geliştirilen, Teknofest 2025 Havacılıkta Yapay Zeka yarışması için nesne tespit ve pozisyon kestirim kütüphanesi.

📂 Proje Yapısı

spiral/
├── requirements.txt     # Bağımlılıklar
├── example/            # Kullanım örnekleri
│   ├── dataloader.py   # Veri yükleme araçları
│   ├── monitoring.py   # Görselleştirme araçları
│   └── usage.py        # Kullanım senaryoları
├── spiral_lib/         # Ana kütüphane
│   ├── config/         # Yapılandırma dosyaları
│   ├── object_detection/# Nesne tespiti modülü
│   ├── position_estimation/# Pozisyon kestirim modülü
│   ├── postprocessing/ # Sonuç işleme araçları
│   ├── preprocessing/  # Ön işleme araçları
│   └── utils/         # Yardımcı fonksiyonlar
└── tests/             # Test senaryoları
    ├── main/          # Ana pipeline testleri
    ├── object_detection/# Nesne tespiti testleri
    └── position_estimation/# Pozisyon kestirim testleri

🚀 Hızlı Başlangıç

Nesne Tespiti (ObjectDetectionPipeline)

Nesne tespiti için YOLO tabanlı güçlü bir pipeline sunulmaktadır:

from spiral_lib import ObjectDetectionPipeline
import cv2

# Pipeline başlatma
spiral_od = ObjectDetectionPipeline()

# Görüntü yükleme
frame = cv2.imread("goruntu.jpg")

# Nesne tespiti
nesneler = spiral_od.predict(frame, verbose=False)

# Her nesne şu bilgileri içerir:
# - Sınırlayıcı kutu koordinatları (normalize ve mutlak)
# - Güven skoru
# - Sınıf etiketi
# - Takip ID'si (varsa)

Pozisyon Kestirimi (PositionEstimationPipeline)

Pozisyon kestirimi için:

from spiral_lib import PositionEstimationPipeline

# Pipeline başlatma
spiral_pe = PositionEstimationPipeline(enable_pix2meter=True)

# Pozisyon kestirimi
frame = cv2.imread("goruntu.jpg")
health_status = True  # Sistem sağlık durumu
tahmin_edilen_pozisyon = spiral_pe.predict(frame, health_status)
x, y, z = tahmin_edilen_pozisyon

Ana Pipeline (Birleşik Kullanım)

Tüm işlemleri tek bir pipeline'da birleştirmek için:

from spiral_lib import MainPipeline

# Ana pipeline başlatma
spiral = MainPipeline()

# Görüntü işleme
frame = cv2.imread("goruntu.jpg")
health_status = True
nesneler, pozisyonlar = spiral.predict(
    frame,
    health_status,
    translation_x=0.0,
    translation_y=0.0,
    translation_z=0.0
)

🧪 Testler

Nesne Tespiti Testleri

tests/object_detection/ klasöründe:

# detection_pipeline.py örneği
from spiral.spiral_lib.object_detection.pipeline import ObjectDetectionPipeline
from spiral.spiral_lib.postprocessing.monitor_helper import MonitorHelper

model = ObjectDetectionPipeline()
TestPrediction.predict_image_list(model, goruntu_yollari, show=True)

Pozisyon Kestirimi Testleri

tests/position_estimation/ klasöründe test senaryoları bulunmaktadır.

📊 Görselleştirme

MonitorHelper sınıfı ile görselleştirme:

from spiral_lib.postprocessing.monitor_helper import MonitorHelper

monitor = MonitorHelper()
# Tespit edilen nesneleri görselleştirme
goruntu = monitor.paint_objects(goruntu, nesneler)
# Yörünge görselleştirme
goruntu = monitor.paint_values(goruntu, nesneler, pos_x, pos_y, pos_z)

⚙️ Yapılandırma

Yapılandırma dosyaları spiral_lib/config/ altında:

• object_detection.yaml: Nesne tespiti parametreleri
• position_estimation.yaml: Pozisyon kestirimi parametreleri
• postprocess.yaml: Sonrası işlem ayarları
• preprocess.yaml: Ön işlem ayarları

📝 Loglama

Sistem otomatik olarak önemli bilgileri loglar:

• Log dosyaları spiral_lib/logs/ altında
• Zaman damgalı detaylı çalışma bilgileri
• Farklı log seviyeleri (INFO, WARNING, vb.)

🔧 Gereksinimler

Temel bağımlılıklar:

• OpenCV (cv2)
• PyTorch
• Ultralytics YOLO
• NumPy
• OmegaConf

Tüm bağımlılıklar için requirements.txt dosyasına bakınız.

---

Daha detaylı örnekler için example/ dizini ve test dosyalarını inceleyebilirsiniz.

---

SPIRAL - Teknofest 2025 [English]

Object detection and position estimation library developed by the SpirAi team for the Teknofest 2025 Artificial Intelligence in Aviation competition.

📂 Project Structure

spiral/
├── requirements.txt     # Dependencies
├── example/            # Usage examples
│   ├── dataloader.py   # Data loading tools
│   ├── monitoring.py   # Visualization tools
│   └── usage.py        # Usage scenarios
├── spiral_lib/         # Main library
│   ├── config/         # Configuration files
│   ├── object_detection/# Object detection module
│   ├── position_estimation/# Position estimation module
│   ├── postprocessing/ # Result processing tools
│   ├── preprocessing/  # Preprocessing tools
│   └── utils/         # Helper functions
└── tests/             # Test scenarios
    ├── main/          # Main pipeline tests
    ├── object_detection/# Object detection tests
    └── position_estimation/# Position estimation tests

🚀 Quick Start

Object Detection (ObjectDetectionPipeline)

A powerful YOLO-based pipeline for object detection:

from spiral_lib import ObjectDetectionPipeline
import cv2

# Initialize pipeline
spiral_od = ObjectDetectionPipeline()

# Load image
frame = cv2.imread("image.jpg")

# Object detection
objects = spiral_od.predict(frame, verbose=False)

# Each object contains:
# - Bounding box coordinates (normalized and absolute)
# - Confidence score
# - Class label
# - Tracking ID (if available)

Position Estimation (PositionEstimationPipeline)

For position estimation:

from spiral_lib import PositionEstimationPipeline

# Initialize pipeline
spiral_pe = PositionEstimationPipeline(enable_pix2meter=True)

# Position estimation
frame = cv2.imread("image.jpg")
health_status = True  # System health status
estimated_position = spiral_pe.predict(frame, health_status)
x, y, z = estimated_position

Main Pipeline (Combined Usage)

To combine all operations in a single pipeline:

from spiral_lib import MainPipeline

# Initialize main pipeline
spiral = MainPipeline()

# Image processing
frame = cv2.imread("image.jpg")
health_status = True
objects, positions = spiral.predict(
    frame,
    health_status,
    translation_x=0.0,
    translation_y=0.0,
    translation_z=0.0
)

🧪 Tests

Object Detection Tests

In the tests/object_detection/ directory:

# detection_pipeline.py example
from spiral.spiral_lib.object_detection.pipeline import ObjectDetectionPipeline
from spiral.spiral_lib.postprocessing.monitor_helper import MonitorHelper

model = ObjectDetectionPipeline()
TestPrediction.predict_image_list(model, image_paths, show=True)

Position Estimation Tests

Test scenarios are available in the tests/position_estimation/ directory.

📊 Visualization

Visualization with MonitorHelper class:

from spiral_lib.postprocessing.monitor_helper import MonitorHelper

monitor = MonitorHelper()
# Visualize detected objects
image = monitor.paint_objects(image, objects)
# Visualize trajectory
image = monitor.paint_values(image, objects, pos_x, pos_y, pos_z)

⚙️ Configuration

Configuration files under spiral_lib/config/:

• object_detection.yaml: Object detection parameters
• position_estimation.yaml: Position estimation parameters
• postprocess.yaml: Post-processing settings
• preprocess.yaml: Preprocessing settings

📝 Logging

The system automatically logs important information:

• Log files under spiral_lib/logs/
• Timestamped detailed operation information
• Different log levels (INFO, WARNING, etc.)

🔧 Requirements

Core dependencies:

• OpenCV (cv2)
• PyTorch
• Ultralytics YOLO
• NumPy
• OmegaConf

For all dependencies, please refer to the requirements.txt file.

---

For more detailed examples, check the example/ directory and test files.