Add placeholder support for TMS baseUrl with {x}, {y}, {z} tokens

[Copilot]

Overview

This PR adds support for URL templates with {x}, {y}, and {z} placeholders in the TMS (Tile Map Service) provider's baseUrl parameter, enabling more flexible tile URL patterns while maintaining full backward compatibility.

Problem

Previously, the TMS provider only supported a simple base URL format where the tile coordinates were manually appended:

// Old format only
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "tms",
  baseUrl: "https://tile.example.com/tiles",
  extension: "png"
});
// Generated URL: https://tile.example.com/tiles/18/123/456.png

This approach was inflexible for tile servers that use different URL patterns or require the coordinates in a specific order.

Solution

The TMS provider now supports URL templates with placeholders, allowing users to specify the exact URL format their tile server expects:

// New placeholder format (recommended)
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "tms",
  baseUrl: "https://tile.example.com/tiles/{z}/{x}/{y}.png"
});

// Custom ordering also supported
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "tms",
  baseUrl: "https://tile.example.com/map/{x}/{y}/{z}.png"
});

// Legacy format still works
const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
  provider: "tms",
  baseUrl: "https://tile.example.com/tiles",
  extension: "png"
});

Implementation Details

• Detection: Checks if baseUrl contains {x}, {y}, or {z} placeholders
• Replacement: Uses replaceAll() to handle edge cases where placeholders appear multiple times
• Backward Compatibility: Falls back to legacy path construction if no placeholders are detected
• TMS Coordinate System: Properly handles TMS Y-coordinate flipping (bottom-left origin) in both formats

Changes

Core Implementation (src/data_providers/tms.ts)

• Modified getTileUrlFromTileCoords() to detect and handle placeholder-based URLs
• Used replaceAll() for robust placeholder replacement
• Maintained backward compatibility with existing simple baseUrl format

Test Coverage (test/tms.test.ts)

Added 5 comprehensive test cases covering:

• Standard placeholder format: {z}/{x}/{y}.png
• Different file extensions in placeholders
• API key handling with placeholders
• Custom placeholder ordering: {x}/{y}/{z}.png
• URLs without file extensions

Documentation (README.md)

• Added clear examples demonstrating both placeholder and legacy formats
• Marked placeholder format as recommended approach

Testing

All tests pass, including:

• ✅ New placeholder format tests (5 test cases)
• ✅ Existing legacy format tests (backward compatibility)
• ✅ TMS Y-coordinate flipping verification
• ✅ API key parameter handling
• ✅ Edge cases (multiple placeholders, custom ordering)

Benefits

• Flexibility: Supports any URL template pattern tile servers may use
• Compatibility: Existing code continues to work without modifications
• Robustness: Handles edge cases like multiple placeholder occurrences
• Standards: Aligns with common tile URL templating conventions used by OpenStreetMap, Leaflet, and other mapping libraries

Original prompt

将tms的baseUrl，改成带有{x}、{y}、{z}的占位符路径

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[sabman]

Hi thanks for this @CandyACE do you wanna make a PR back to the main repo? if not we can merge them ourselves as well.