Improve create_isochrone() to allow multi centers / thresholds and refactor concave_hull_knn

[yu-ta-sato]

Description

This PR expands isochrone generation to support richer routing scenarios while preserving backward compatibility for existing scalar-threshold usage.

1) Multi-center support

• Added support for passing multiple origins as:
  • Sequence of Point
  • GeoSeries
  • GeoDataFrame
• Reachability is computed as the union across all centers.

2) Layered isochrones from multiple thresholds

• create_isochrone now accepts threshold as either:
  • scalar float (legacy behavior)
  • sequence of floats (new layered output)
• Scalar threshold still returns the legacy single-row geometry-only GeoDataFrame.
• Sequence threshold returns one row per threshold with columns:
  • threshold
  • geometry
• Distance computation is performed once and reused across all threshold layers for efficiency.

3) Internal refactor for performance and clarity

• Centralized center normalization and shortest-path distance computation.
• Added reusable helpers for:
  • threshold normalization
  • center normalization
  • reachable subgraph construction
  • final geometry construction
• Updated concave_hull_knn path to operate on coordinate arrays more directly.
• Adjusted/defaulted concave hull parameters:
  • k default updated to 50
  • alpha hull ratio default updated to 0.0

4) Validation and error handling improvements

• Added explicit validation for empty threshold sequences.
• Added type validation for invalid center sequence entries.
• Preserved expected empty-result behavior for empty center inputs.

Tests

• Extended test coverage in test_utils for:
  • multi-center sequence union behavior
  • layered thresholds and output schema
  • empty layer preservation
  • layered + cut edge type behavior
  • layered output with nodes/edges GeoDataFrame inputs
  • distance computation reuse (single compute call)
  • invalid input handling for threshold and center types
  • concave_hull_knn retry/fallback paths
• Full suite result:
  • 628 passed
  • 0 failed

Backward Compatibility

• Existing scalar-threshold create_isochrone behavior is preserved (single-row geometry output).
• New behavior is additive for sequence thresholds and sequence center inputs.

Notes

• There are additional local notebook/docs changes in the working tree that are not part of the two committed utility/test commits. These should be split into a separate docs PR unless intentionally included.

Related Issues

NA

Checklist

• I have read the Contributing Guide.
• I have updated the documentation, if necessary.
• I have added tests to cover my changes.
• All new and existing tests passed.
• Pre-commit checks passed locally.

[codecov]

Codecov Report

❌ Patch coverage is 98.06763% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
city2graph/utils.py	98.06%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!