leaflet_svelte/DEBUGGING_WIND_LAYER.md

# Wind Layer Debugging Guide

## ✅ Fixes Applied

### 1. **Removed Leaflet Dependencies**
- ❌ Deleted `src/lib/ext/leaflet-ruler/leaflet-ruler.ts`
- This file was causing import errors for missing 'leaflet' module

### 2. **Fixed Type Definitions**
**File:** `src/lib/types.ts`

**Before:**
```typescript
export type LatLngTuple = [number, number];
```

**After:**
```typescript
export type LatLngTuple = [number, number] | [number, number, number]; // Support 2D and 3D
export interface LatLngLiteral {
	lat: number;
	lng: number;
	alt?: number; // Optional altitude
}
```

**Why:** Prediction and telemetry data includes altitude (3D coordinates), so types need to support `[lat, lng, alt]` tuples.

### 3. **Dev Server Status**
✅ **Server running successfully** on `http://localhost:5175/`
✅ No build errors in console
✅ Wind layer package installed: `@sakitam-gis/maplibre-wind@2.0.3`

---

## 🔍 Debugging 500 Internal Server Error

If you're still seeing a 500 error, check these areas:

### 1. **Check Browser Console**

Open browser DevTools (F12) and look for:

```javascript
// Expected success logs:
"WindVisualization mounted with MapLibre map"
"Wind data available: Array(2)"
"Wind data stats - U: [-21.32, 26.80], V: [-21.57, 21.42]"
"Wind layers initialized successfully"

// Error logs to watch for:
"Failed to process wind data"
"Error initializing wind layers:"
"Missing U or V wind components"
```

### 2. **Check Network Tab**

Look for failed requests:
- `/src/routes/testVelo.json` - Wind data file
- MapLibre GL CSS/JS assets
- Wind layer assets

### 3. **Verify Wind Data File**

```bash
# Check if file exists
ls -la src/routes/testVelo.json

# Check file size (should be ~76KB)
du -h src/routes/testVelo.json

# Verify JSON is valid
cat src/routes/testVelo.json | python -m json.tool > /dev/null && echo "Valid JSON" || echo "Invalid JSON"
```

### 4. **Check Map Component**

The Map component should pass both props:

```svelte
<WindVisualization {map} {windData} />
```

Verify in `src/lib/components/Map.svelte`:
- Line ~155-157: WindVisualization component exists
- `windData` is loaded from fetch
- `map` instance is created

### 5. **SSR (Server-Side Rendering) Issues**

MapLibre and wind-layer are client-only. Ensure:

```typescript
// In +page.ts or +page.server.ts
export const ssr = false;
```

Check: `src/routes/predict/+page.ts`

### 6. **Build Issues**

Try clearing cache and rebuilding:

```bash
# Clear SvelteKit cache
rm -rf .svelte-kit

# Clear node_modules (if needed)
rm -rf node_modules
npm install

# Restart dev server
npm run dev
```

---

## 🧪 Test Cases

### Test 1: Component Loads
1. Navigate to `/predict`
2. Open console (F12)
3. Look for "WindVisualization mounted" message
4. ✅ Success if no errors

### Test 2: Wind Data Loaded
1. Check console for "Wind data available: Array(2)"
2. Verify data has U-component (parameterNumber: 2)
3. Verify data has V-component (parameterNumber: 3)
4. ✅ Success if both components present

### Test 3: Layers Initialize
1. Look for "Wind layers initialized successfully"
2. Check map has particle animation visible
3. Toggle checkboxes work
4. ✅ Success if particles animate

### Test 4: No Console Errors
1. Check for any red errors in console
2. Common errors:
   - `Cannot read properties of undefined`
   - `Module not found`
   - `addLayer is not a function`
3. ✅ Success if no errors

---

## 🐛 Common Errors & Solutions

### Error: "Cannot find module '@sakitam-gis/maplibre-wind'"

**Solution:**
```bash
npm install @sakitam-gis/maplibre-wind --save
```

### Error: "map.addLayer is not a function"

**Cause:** Map not fully initialized

**Solution:** Component already waits for map load:
```javascript
if (map.loaded()) {
    initializeWindLayers();
} else {
    map.on('load', initializeWindLayers);
}
```

### Error: "Missing U or V wind components"

**Cause:** Wind data file corrupted or wrong format

**Solution:** Verify `testVelo.json` has 2 objects with:
- First: `header.parameterNumber: 2` (U-component)
- Second: `header.parameterNumber: 3` (V-component)

### Error: "Failed to process wind data"

**Cause:** Data structure doesn't match expected format

**Solution:** Check data has:
```javascript
{
  header: { nx, ny, parameterNumber },
  data: [/* array of numbers */]
}
```

### Error: Layer already exists

**Cause:** Trying to add layer that's already on map

**Solution:** Component checks before adding:
```javascript
if (!map.getLayer('wind-particles')) {
    map.addLayer(particleLayer);
}
```

---

## 📊 Expected Console Output

### Successful Load:
```
WindVisualization mounted with MapLibre map
Wind data available: Array(2) [{header: {…}, data: Array(65160)}, {header: {…}, data: Array(65160)}]
Wind data stats - U: [-21.32, 26.80], V: [-21.57, 21.42]
Processed wind data: {uMin: -21.32, uMax: 26.8, vMin: -21.57, vMax: 21.42, rows: 181, cols: 360, data: Array(2)}
Wind layers initialized successfully
```

### Layer Toggle:
```
// When unchecking particle layer
(Removes layer from map)

// When checking particle layer
(Adds layer back to map)
```

---

## 🔧 Manual Testing

### Test in Browser Console

```javascript
// 1. Check if map has wind layers
map.getLayer('wind-particles')  // Should return layer object
map.getLayer('wind-heatmap')    // Should return layer object

// 2. Check if map instance is valid
map.loaded()  // Should return true

// 3. Manually toggle layers
map.removeLayer('wind-particles')
map.addLayer(particleLayer)  // If you have reference
```

---

## 📝 Code Review Checklist

### WindVisualisation.svelte
- [x] Uses `$props()` (Svelte 5 syntax)
- [x] Has `prepareWindData()` function
- [x] Waits for map load
- [x] Has error handling (try/catch)
- [x] Cleans up on destroy
- [x] Reactive `$effect()` for toggles

### Map.svelte
- [x] Imports WindVisualization component
- [x] Fetches wind data from testVelo.json
- [x] Passes `map` and `windData` props
- [x] Renders WindVisualization component

### types.ts
- [x] Supports 3D coordinates `[lat, lng, alt]`
- [x] Optional `alt` in LatLngLiteral
- [x] Proper LatLngExpression type

---

## 🚀 Performance Notes

### Particle Count Impact

```javascript
// High performance (2000-3000 particles)
numParticles: 2000

// Balanced (5000 particles) - Default
numParticles: 5000

// High quality (10000+ particles) - May lag on slower devices
numParticles: 10000
```

### Large Datasets

Current dataset: 65,160 points (360 × 181 grid)
- Should render in <1 second
- GPU-accelerated via WebGL
- No lag on modern browsers

---

## 📚 Additional Resources

- **Wind Layer Repo:** https://github.com/sakitam-fdd/wind-layer
- **MapLibre Docs:** https://maplibre.org/maplibre-gl-js/docs/
- **Issue Tracker:** Report bugs in wind-layer repo

---

## ✅ Final Checklist

Before reporting an issue, verify:

- [ ] Dev server running (`npm run dev`)
- [ ] No errors in terminal
- [ ] Browser console open (F12)
- [ ] No red errors in console
- [ ] testVelo.json file exists
- [ ] MapLibre GL loaded correctly
- [ ] Wind layer package installed
- [ ] Component props passed correctly
- [ ] SSR disabled for map routes

---

**Last Updated:** December 2025
**Status:** ✅ Implementation Complete
**Known Issues:** None