boc/quixzoom-video-pipeline/README.md

# QUIXZOOM Urban Video Ingestion Pipeline

Skalbar pipeline för att upptäcka, indexera och processa publikt tillgängliga city walking videos för urban intelligence och infrastrukturanalys.

## Arkitektur

```
Discovery (YouTube API)
    │
    ▼
Video Index (Redis)
    │
    ▼
Download Queue
    │
    ▼
Frame Extractor (FFmpeg)
    ├── Time-based (var 5:e sekund)
    ├── Scene change detection
    └── Motion-based
    │
    ▼
AI Annotator (15 modeller)
    ├── Scene Classification
    ├── Semantic Segmentation
    ├── OCR
    ├── Object Detection
    ├── Traffic Sign Detection
    ├── Building Detection
    ├── Road Surface Analysis
    ├── Sidewalk Analysis
    ├── Pole Detection
    ├── Utility Box Detection
    ├── Pavement Crack Detection
    ├── Vegetation Detection
    ├── Lighting Detection
    ├── Storefront Detection
    └── Accessibility Detection
    │
    ▼
Dataset Builder
    ├── Roads
    ├── Sidewalks
    ├── Crosswalks
    ├── Buildings
    ├── Trees
    ├── Utility Infrastructure
    ├── Traffic Infrastructure
    ├── Signage
    ├── Lighting
    ├── Accessibility
    ├── Commercial Areas
    └── Urban Density
    │
    ▼
Training Dataset (JSONL)
```

## Komponenter

### 1. Discovery (`discovery/youtube-discovery.js`)

Söker efter city walking videos på YouTube:
- 25 söktermer (generella + stadsspecifika)
- Filtrerar endast Creative Commons-licensierade videos
- Extraherar stad och land från titel/beskrivning
- Indexerar i Redis

**Söktermer:**
```javascript
'4K City Walk', 'Walking Tour', 'Street Walk',
'Bangkok Walk', 'Tokyo Walk', 'London Walk',
'Walking Downtown', 'Night Walk', 'POV Walk'
```

### 2. Frame Extractor (`processing/frame-extractor.js`)

Extraherar frames med 3 strategier:
- **Time-based:** Var 5:e sekund
- **Scene change:** Vid scenförändringar (threshold: 0.3)
- **Motion-based:** Vid hög rörelse

Deduplicering: Tar bort frames < 2 sekunder från varandra.

### 3. AI Annotator (`processing/ai-annotator.js`)

15 AI-modeller körs på varje frame:

| Modell | Funktion |
|--------|----------|
| Scene Classification | 20 scener (road, commercial, park, etc.) |
| Semantic Segmentation | Pixel-nivå klassificering |
| OCR | Text-extraktion (eng+tha+deu+fra+spa) |
| Object Detection | 80 COCO-klasser |
| Traffic Sign Detection | 13 skylttyper |
| Building Detection | Typ, höjd, position |
| Road Surface Analysis | 10 yt-typer + sprickor |
| Sidewalk Analysis | Bredd, skick, tillgänglighet |
| Pole Detection | 6 pol-typer |
| Utility Box Detection | El/telecom/trafik |
| Crack Detection | Antal, längd, allvarlighet |
| Vegetation Detection | Träd, täckning, hälsa |
| Lighting Detection | Gatlampor, tid på dygnet |
| Storefront Detection | 10 affärstyper |
| Accessibility Detection | Rullstolsramp, ledstråk, etc. |

### 4. Dataset Builder (`dataset-builder/builder.js`)

Bygger 12 specialiserade dataset i JSONL-format:

| Dataset | Innehåll |
|---------|----------|
| roads.jsonl | Vägtyp, skick, sprickor |
| sidewalks.jsonl | Bredd, skick, tillgänglighet |
| crosswalks.jsonl | Övergångsställen, trafikljus |
| buildings.jsonl | Byggnader, höjd, typ |
| trees.jsonl | Träd, täckning, hälsa |
| utility_infrastructure.jsonl | Elstolpar, skåp, kablage |
| traffic_infrastructure.jsonl | Trafikljus, skyltar |
| signage.jsonl | OCR-text, affärer |
| lighting.jsonl | Belysning, tid på dygnet |
| accessibility.jsonl | Tillgänglighetsfunktioner |
| commercial_areas.jsonl | Affärer, restauranger, hotell |
| urban_density.jsonl | Folk- och fordonsdensitet |

## Snabbstart

### 1. Installation

```bash
git clone https://github.com/quixzoom/video-pipeline.git
cd quixzoom-video-pipeline
npm install
```

### 2. Konfiguration

```bash
cp .env.example .env
# Redigera .env med dina värden
```

### 3. Kör discovery

```bash
npm run discover
```

### 4. Extrahera frames

```bash
npm run extract -- --video=/path/to/video.mp4 --output=./frames
```

### 5. Kör AI-analys

```bash
npm run annotate -- --input=./frames --output=./annotations
```

### 6. Bygg dataset

```bash
npm run build-dataset -- --input=./annotations --output=./datasets
```

## Miljövariabler

| Variabel | Beskrivning |
|----------|-------------|
| `YOUTUBE_API_KEY` | YouTube Data API v3 key |
| `REDIS_HOST` | Redis host |
| `REDIS_PORT` | Redis port |
| `REDIS_PASSWORD` | Redis password |

## Datakällor

**Prioriterade källor:**
1. YouTube City Walk channels (Creative Commons)
2. QUIXZOOM user captures (egen data)
3. Öppna dataset (Cityscapes, etc.)
4. OpenStreetMap
5. Offentliga geodata

**Juridisk hänsyn:**
- Endast Creative Commons-licensierade videos
- Egeninsamlad data från QUIXZOOM
- Respektera upphovsrätt

## Output-format

### JSONL-exempel (roads.jsonl)

```json
{
  "image": "/path/to/frame_001.jpg",
  "labels": {
    "surface_type": "asphalt_fair",
    "surface_confidence": 0.82,
    "has_cracks": true,
    "crack_severity": "medium",
    "road_pixels": 34.5
  },
  "metadata": {
    "city": "Bangkok",
    "country": "Thailand",
    "timestamp": "2026-06-28T08:15:30Z"
  }
}
```

## Licens

MIT © LandveX Inc.