panel/docs/MAP_LAYERS.md

# Map Layers Configuration

This document explains how to add and configure map layers using proper WMTS GetCapabilities discovery.

## Current Implementation

The map system supports multiple base layers using Leaflet and React-Leaflet with proper WMTS service discovery via GetCapabilities requests.

### File Structure
- **`ProjectMap.js`**: Main map component used in the project pages
- **`LeafletMap.js`**: Core Leaflet map component with layer support
- **`mapLayers.js`**: Configuration file for all available layers
- **`wmtsCapabilities.js`**: WMTS service discovery and configuration utilities

## Using GetCapabilities for WMTS Services

Instead of hardcoding WMTS URLs, we use the standard OGC approach:

### 1. Query Service Capabilities
```javascript
// Get capabilities for Polish Geoportal Orthophoto
const capabilitiesUrl = "https://mapy.geoportal.gov.pl/wss/service/PZGIK/ORTO/WMTS/StandardResolution?Service=WMTS&Request=GetCapabilities";
```

### 2. Parse Available Layers
The GetCapabilities response provides:
- Available layers and their identifiers
- Supported coordinate reference systems (TileMatrixSets)
- Available formats (image/png, image/jpeg, etc.)
- Supported styles
- Zoom level ranges
- Service metadata

### 3. Build Proper WMTS URLs
```javascript
// Standard WMTS RESTful URL pattern
const tileUrl = `${baseUrl}/tile/{version}/{layer}/{style}/{tilematrixSet}/{z}/{y}/{x}.{format}`;
```

### Base Layers (Mutually Exclusive)
- **OpenStreetMap**: Standard street map
- **Polish Geoportal Orthophoto**: Aerial imagery from Polish national geoportal
- **Polish Land Records Integration**: Land records and cadastral data from GUGiK
- **Satellite (Esri)**: High-resolution satellite imagery
- **Topographic**: Topographic style map

### Layer Control
Users can switch between layers using the layer control widget (📚 icon) in the top-right corner of the map.

## Adding New Layers

### 1. Standard Tile Layers (XYZ)

To add a new tile layer, edit `src/components/ui/mapLayers.js`:

```javascript
// Add to the base array
{
  name: "Your Layer Name",
  attribution: '&copy; <a href="https://example.com">Provider</a>',
  url: "https://example.com/{z}/{x}/{y}.png",
  maxZoom: 19
}
```

### 2. WMTS Layers

For WMTS (Web Map Tile Service) layers like the Polish Geoportal:

```javascript
{
  name: "WMTS Layer",
  attribution: '&copy; <a href="https://provider.com">Provider</a>',
  url: "https://provider.com/wmts/service/Layer/{z}/{y}/{x}.jpg",
  maxZoom: 19,
  tileSize: 256
}
```

### 3. WMS Overlay Layers

For WMS (Web Map Service) overlay layers:

```javascript
// Add to the overlay array in mapLayers.js
{
  name: "Overlay Layer",
  attribution: '&copy; <a href="https://provider.com">Provider</a>',
  url: "https://provider.com/wms",
  format: "image/png",
  transparent: true,
  layers: "layer_name"
}
```

## Discovering New WMTS Services

### Step 1: Find the GetCapabilities URL
```
https://your-wmts-service.com/wmts?Service=WMTS&Request=GetCapabilities
```

### Step 2: Analyze the Response
Look for these key elements in the XML:
- `<Layer>` elements with their `<ows:Identifier>`
- `<TileMatrixSet>` supported coordinate systems
- `<Format>` supported image formats
- `<Style>` available styling options

### Step 3: Build the Configuration
```javascript
{
  name: "Your Service Name",
  attribution: '&copy; <a href="https://provider.com">Provider</a>',
  url: buildWMTSTileUrl({
    baseUrl: "https://your-wmts-service.com/wmts",
    layer: "LayerIdentifier", // from GetCapabilities
    style: "default",
    tilematrixSet: "EPSG:3857", // or EPSG:2180 for Polish services
    format: "image/png"
  }),
  maxZoom: 19
}
```

### Polish Services Discovery

**Polish Geoportal Orthophoto:**
```
https://mapy.geoportal.gov.pl/wss/service/PZGIK/ORTO/WMTS/StandardResolution?Service=WMTS&Request=GetCapabilities
```

**GUGiK Land Records** (Note: This is actually WMS, not WMTS):
```
https://integracja.gugik.gov.pl/cgi-bin/KrajowaIntegracjaEwidencjiGruntow?Service=WMS&Request=GetCapabilities
```

## Usage Examples

### Basic Map with Default Layers
```jsx
<ProjectMap 
  coordinates="50.0647,19.9450" 
  projectName="Sample Project" 
/>
```

### Map with Custom Default Layer
```jsx
<ProjectMap 
  coordinates="50.0647,19.9450" 
  projectName="Sample Project"
  defaultLayer="Polish Geoportal Orthophoto"
  showLayerControl={true}
  mapHeight="h-96"
/>
```

### Map without Layer Control
```jsx
<ProjectMap 
  coordinates="50.0647,19.9450" 
  projectName="Sample Project"
  showLayerControl={false}
/>
```

## Technical Notes

1. **WMTS vs XYZ**: WMTS follows OGC standards but can often be accessed via XYZ tile patterns
2. **CRS Support**: Polish layers use EPSG:2180, while international layers use EPSG:3857 (Web Mercator)
3. **Attribution**: Always include proper attribution for map data providers
4. **CORS**: Some services may require proxy configuration for CORS issues

## Adding More Polish Services

To add more services from the Polish National Geoportal:

1. Visit: https://www.geoportal.gov.pl/
2. Check their WMS/WMTS services documentation
3. Test the service URLs in the browser
4. Add to the layer configuration following the patterns above

## Example: Adding a New GUGiK WMTS Layer

```javascript
// In mapLayers.js base array
{
  name: "Polish Land Records",
  attribution: '&copy; <a href="https://www.gugik.gov.pl/">GUGiK</a>',
  url: "https://integracja.gugik.gov.pl/cgi-bin/KrajowaIntegracjaEwidencjiGruntow/wmts.cgi?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=EGiB&STYLE=default&TILEMATRIXSET=EPSG:2180&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=image/png",
  maxZoom: 19,
  tileSize: 256
}
```

**Important**: Polish services use EPSG:2180 coordinate system, not the standard Web Mercator EPSG:3857.