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

// 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

// 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:

// 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:

{
  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:

// 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

{
  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

<ProjectMap 
  coordinates="50.0647,19.9450" 
  projectName="Sample Project" 
/>

Map with Custom Default Layer

<ProjectMap 
  coordinates="50.0647,19.9450" 
  projectName="Sample Project"
  defaultLayer="Polish Geoportal Orthophoto"
  showLayerControl={true}
  mapHeight="h-96"
/>

Map without Layer Control

<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

// 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.