gtfs-segmenter 0.1.0__py3-none-any.whl

gtfs_segmenter-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: gtfs-segmenter
+Version: 0.1.0
+Summary: Segment GTFS shapes into stop-to-stop route segments with loop-aware projection
+Project-URL: Homepage, https://github.com/lizobst/gtfs-segments
+Project-URL: Issues, https://github.com/lizobst/gtfs-segments/issues
+Author: Liz Obst
+License: MIT
+License-File: LICENSE
+Keywords: geopandas,geospatial,gtfs,transit,transportation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Requires-Dist: geopandas>=0.12
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: shapely>=2.0
+Provides-Extra: dev
+Requires-Dist: folium>=0.14; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: viz
+Requires-Dist: folium>=0.14; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# gtfs-segments
+
+Segment GTFS shapes into stop-to-stop route segments that follow the original road geometry.
+
+Most GTFS tools use Shapely's `.project()` to snap stops to shapes, which breaks on routes with loops, lollipop turnarounds, and out-and-back corridors. This library uses sequential projection with candidate-aware selection to handle complex route geometries correctly.
+
+## Install
+
+```bash
+pip install gtfs-segments
+```
+
+For interactive map visualization:
+
+```bash
+pip install gtfs-segments[viz]
+```
+
+## Quick Start
+
+### Segment an entire feed
+
+```python
+from gtfs_segments import segment_feed
+
+result = segment_feed("path/to/gtfs")
+
+segments = result['segments']       # GeoDataFrame of all stop-to-stop segments
+diagnostics = result['diagnostics'] # per-shape stats (offsets, degenerates)
+failures = result['failures']       # any shapes that failed
+```
+
+### Segment a single shape
+
+```python
+import pandas as pd
+from gtfs_segments import segment_shape
+
+shapes = pd.read_csv("gtfs/shapes.txt")
+trips = pd.read_csv("gtfs/trips.txt")
+stops = pd.read_csv("gtfs/stops.txt")
+stop_times = pd.read_csv("gtfs/stop_times.txt")
+
+result = segment_shape(shapes, trips, stops, stop_times, shape_id=232864)
+
+segments = result['segments']
+projected = result['projected_stops']
+ruler = result['ruler']
+diag = result['diagnostics']
+```
+
+### Low-level control
+
+```python
+from gtfs_segments import ShapeRuler, project_stops_sequential, segment_route
+
+ruler = ShapeRuler(shapes, shape_id=232864)
+
+# Get stop visit order from stop_times
+trip_id = trips[trips['shape_id'] == 232864]['trip_id'].iloc[0]
+st = stop_times[stop_times['trip_id'] == trip_id].sort_values('stop_sequence')
+stop_sequence = st['stop_id'].tolist()
+route_stops = stops[stops['stop_id'].isin(stop_sequence)].copy()
+
+# Project stops onto shape and build segments
+projected = project_stops_sequential(ruler, route_stops, stop_sequence)
+segments = segment_route(ruler, projected)
+```
+
+## How It Works
+
+### The Problem
+
+Shapely's `.project()` finds the globally nearest point on a LineString. On a route that doubles back on itself, a stop at the base of a loop has two valid projection points — the entry and the exit. `.project()` picks whichever is geometrically closer, often the exit, which causes every stop inside the loop to collapse to the same distance.
+
+### The Solution
+
+1. **ShapeRuler** converts the shape to a metric CRS, builds a cumulative distance ruler, and indexes every segment for fast searching.
+
+2. **find_candidates** scans every segment and collects all positions where a stop projects within tolerance (default 50m). A stop at a loop base gets candidates at both entry and exit.
+
+3. **project_stops_sequential** processes stops in visit order (from `stop_times`), enforcing monotonic distances. For each stop, it picks the **earliest** candidate with a reasonable offset — biasing toward forward progress along the route rather than jumping ahead to a later occurrence.
+
+4. **segment_route** slices the shape between consecutive stop distances, including all original vertices so segments follow the actual road geometry.
+
+### CRS Auto-Detection
+
+If no CRS is provided, the library auto-detects the UTM zone from the median longitude of the shape coordinates. Override with `metric_crs="EPSG:32614"` if needed.
+
+## Diagnostics
+
+The `diagnostics` DataFrame flags potential issues:
+
+- **max_offset_m**: Largest perpendicular distance between a stop and the shape. Over 30m usually means the stop is set back from the road (transit centers, park-and-rides) or assigned to the wrong shape.
+- **n_high_offset**: Count of stops with offset > 30m.
+- **n_degenerate**: Count of segments shorter than 5m. Usually near-side/far-side stop pairs at intersections.
+
+## Requirements
+
+- Python ≥ 3.9
+- geopandas ≥ 0.12
+- shapely ≥ 2.0
+- pandas ≥ 1.5
+- numpy ≥ 1.23
+
+## License
+
+MIT

gtfs_segmenter-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+gtfs_segments/__init__.py,sha256=z8rs-uL9_np4NOjEnn68H00M_t10jF_fIwLojH8I7is,1005
+gtfs_segments/feed.py,sha256=w5jVqdyxPQvZ091yjhCzcSYfRbEmJ6pa0CCVq2mICjw,6241
+gtfs_segments/projection.py,sha256=90Hk08BvgV26gUTh-DDIcQapuMVo3J7M8DfAuPazjhs,2714
+gtfs_segments/ruler.py,sha256=hnUEA_Q3InUSDSh9Q6QN91PFainZL9OrkyHG0Pz_HpY,5829
+gtfs_segments/segmentation.py,sha256=pFq76rmEpNyKUMyWeDP1hsnWKt_fCZsG5b_Ik8C1dTo,1643
+gtfs_segmenter-0.1.0.dist-info/METADATA,sha256=JZKkFdJgJRods4ZLWtWaOL1QQ_q88xX0ZKgIigvxtZQ,4893
+gtfs_segmenter-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gtfs_segmenter-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+gtfs_segmenter-0.1.0.dist-info/RECORD,,

gtfs_segmenter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gtfs_segmenter-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gtfs_segments/__init__.py

@@ -0,0 +1,35 @@
+"""
+gtfs-segments: Segment GTFS shapes into stop-to-stop route segments.
+
+Handles complex route geometries including loops, lollipop turnarounds,
+and out-and-back corridors using sequential projection with
+candidate-aware selection.
+
+Quick start:
+    from gtfs_segments import segment_feed
+    result = segment_feed("path/to/gtfs")
+    segments = result['segments']  # GeoDataFrame of all segments
+
+For single shapes:
+    from gtfs_segments import segment_shape
+    result = segment_shape(shapes_df, trips_df, stops_df, stop_times_df,
+                           shape_id=232864)
+
+For low-level control:
+    from gtfs_segments import ShapeRuler, project_stops_sequential, segment_route
+"""
+
+from .ruler import ShapeRuler
+from .projection import project_stops_sequential
+from .segmentation import segment_route
+from .feed import segment_feed, segment_shape
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ShapeRuler",
+    "project_stops_sequential",
+    "segment_route",
+    "segment_feed",
+    "segment_shape",
+]

gtfs_segments/feed.py

@@ -0,0 +1,190 @@
+"""
+Feed-level processing: load a GTFS directory and segment all shapes.
+"""
+
+import pandas as pd
+import geopandas as gpd
+from pathlib import Path
+
+from .ruler import ShapeRuler
+from .projection import project_stops_sequential
+from .segmentation import segment_route
+
+
+def _load_gtfs(gtfs_path):
+    """Load required GTFS tables from a directory."""
+    p = Path(gtfs_path)
+    if not p.is_dir():
+        raise FileNotFoundError(f"GTFS directory not found: {gtfs_path}")
+
+    required = ['shapes.txt', 'trips.txt', 'stops.txt', 'stop_times.txt']
+    for f in required:
+        if not (p / f).exists():
+            raise FileNotFoundError(f"Missing {f} in {gtfs_path}")
+
+    return {
+        'shapes': pd.read_csv(p / 'shapes.txt'),
+        'trips': pd.read_csv(p / 'trips.txt'),
+        'stops': pd.read_csv(p / 'stops.txt'),
+        'stop_times': pd.read_csv(p / 'stop_times.txt'),
+    }
+
+
+def segment_shape(shapes_df, trips_df, stops_df, stop_times_df,
+                  shape_id, metric_crs=None, tolerance_m=50):
+    """
+    Segment a single shape into stop-to-stop segments.
+
+    Parameters
+    ----------
+    shapes_df, trips_df, stops_df, stop_times_df : DataFrame
+        GTFS tables
+    shape_id : int or str
+        Target shape ID
+    metric_crs : str or None
+        Projected CRS. Auto-detects UTM zone if None.
+    tolerance_m : float
+        Max perpendicular distance for candidate projection (default 50m)
+
+    Returns
+    -------
+    dict with:
+        - segments : GeoDataFrame of stop-to-stop segments (WGS84)
+        - projected_stops : GeoDataFrame of projected stop positions
+        - ruler : ShapeRuler instance
+        - diagnostics : dict with summary stats
+    """
+    ruler = ShapeRuler(shapes_df, shape_id, metric_crs=metric_crs)
+
+    # Find a trip that uses this shape
+    matching_trips = trips_df[trips_df['shape_id'] == shape_id]
+    if matching_trips.empty:
+        raise ValueError(f"No trips found for shape {shape_id}")
+
+    trip_id = matching_trips['trip_id'].iloc[0]
+
+    # Get stop sequence from stop_times
+    st = (stop_times_df[stop_times_df['trip_id'] == trip_id]
+          .sort_values('stop_sequence'))
+    stop_sequence = st['stop_id'].tolist()
+
+    if not stop_sequence:
+        raise ValueError(
+            f"No stops found for trip {trip_id} (shape {shape_id})")
+
+    # Filter to stops in this trip
+    route_stops = stops_df[stops_df['stop_id'].isin(stop_sequence)].copy()
+
+    # Project and segment
+    projected = project_stops_sequential(
+        ruler, route_stops, stop_sequence, tolerance_m=tolerance_m)
+    segments = segment_route(ruler, projected)
+
+    # Diagnostics
+    diagnostics = {
+        'shape_id': shape_id,
+        'length_m': ruler.length,
+        'n_stops': len(projected),
+        'n_segments': len(segments),
+        'max_offset_m': projected['offset_m'].max() if len(projected) > 0 else 0,
+        'n_high_offset': int((projected['offset_m'] > 30).sum()) if len(projected) > 0 else 0,
+        'n_degenerate': int((segments['segment_dist_m'] < 5).sum()) if len(segments) > 0 else 0,
+    }
+
+    return {
+        'segments': segments,
+        'projected_stops': projected,
+        'ruler': ruler,
+        'diagnostics': diagnostics,
+    }
+
+
+def segment_feed(gtfs_path, shape_ids=None, metric_crs=None,
+                 tolerance_m=50, verbose=True):
+    """
+    Segment an entire GTFS feed into stop-to-stop segments.
+
+    Parameters
+    ----------
+    gtfs_path : str or Path
+        Path to directory containing GTFS .txt files
+    shape_ids : list or None
+        Specific shape IDs to process. If None, processes all shapes.
+    metric_crs : str or None
+        Projected CRS. Auto-detects UTM zone if None.
+    tolerance_m : float
+        Max perpendicular distance for candidate projection (default 50m)
+    verbose : bool
+        Print progress (default True)
+
+    Returns
+    -------
+    dict with:
+        - segments : GeoDataFrame of all segments across all shapes
+        - diagnostics : DataFrame with per-shape summary stats
+        - failures : DataFrame of shapes that failed with error messages
+    """
+    gtfs = _load_gtfs(gtfs_path)
+    shapes_df = gtfs['shapes']
+    trips_df = gtfs['trips']
+    stops_df = gtfs['stops']
+    stop_times_df = gtfs['stop_times']
+
+    # Determine which shapes to process
+    if shape_ids is None:
+        # Get shapes that have at least one trip
+        shape_ids = (trips_df[trips_df['shape_id'].isin(
+                        shapes_df['shape_id'].unique())]
+                     ['shape_id'].unique().tolist())
+
+    all_segments = []
+    all_diagnostics = []
+    failures = []
+
+    for i, shape_id in enumerate(shape_ids):
+        if verbose and (i + 1) % 50 == 0:
+            print(f"  Processing shape {i + 1}/{len(shape_ids)}...")
+
+        try:
+            result = segment_shape(
+                shapes_df, trips_df, stops_df, stop_times_df,
+                shape_id, metric_crs=metric_crs, tolerance_m=tolerance_m)
+
+            if len(result['segments']) > 0:
+                all_segments.append(result['segments'])
+            all_diagnostics.append(result['diagnostics'])
+
+        except Exception as e:
+            failures.append({'shape_id': shape_id, 'error': str(e)})
+
+    # Combine results
+    if all_segments:
+        combined_segments = gpd.GeoDataFrame(
+            pd.concat(all_segments, ignore_index=True),
+            crs="EPSG:4326"
+        )
+    else:
+        combined_segments = gpd.GeoDataFrame()
+
+    diagnostics_df = pd.DataFrame(all_diagnostics)
+    failures_df = pd.DataFrame(failures)
+
+    if verbose:
+        n = len(diagnostics_df)
+        n_fail = len(failures_df)
+        n_high = (diagnostics_df['n_high_offset'] > 0).sum() if n > 0 else 0
+        n_degen = (diagnostics_df['n_degenerate'] > 0).sum() if n > 0 else 0
+        n_segs = len(combined_segments)
+        print(f"  Processed {n} shapes → {n_segs} segments")
+        if n_fail > 0:
+            print(f"  Failed: {n_fail}")
+        if n_high > 0:
+            print(f"  High offset (>30m): {n_high} shapes")
+        if n_degen > 0:
+            print(f"  Degenerate (<5m): {n_degen} shapes")
+
+    return {
+        'segments': combined_segments,
+        'diagnostics': diagnostics_df,
+        'failures': failures_df,
+    }

gtfs_segments/projection.py

@@ -0,0 +1,84 @@
+"""
+Sequential stop-to-shape projection with candidate-aware loop handling.
+"""
+
+import geopandas as gpd
+
+
+def project_stops_sequential(ruler, stops_df, stop_sequence, tolerance_m=50):
+    """
+    Project stops onto a shape in visit order with monotonic enforcement.
+
+    For each stop, finds all candidate projection points within tolerance,
+    then picks the earliest one with a reasonable offset. This handles
+    loops where a stop could match the entry or exit of a loop.
+
+    Parameters
+    ----------
+    ruler : ShapeRuler
+        Built for the target shape
+    stops_df : DataFrame
+        Stop locations with columns: stop_id, stop_name, stop_lat, stop_lon
+    stop_sequence : list
+        stop_ids in visit order (from stop_times sorted by stop_sequence)
+    tolerance_m : float
+        Max perpendicular distance for candidate detection (default 50m)
+
+    Returns
+    -------
+    GeoDataFrame in metric CRS with columns:
+        stop_id, stop_name, shape_dist_traveled, offset_m,
+        snapped_geom, original_geom, n_candidates
+    """
+    gdf = gpd.GeoDataFrame(
+        stops_df.copy(),
+        geometry=gpd.points_from_xy(stops_df.stop_lon, stops_df.stop_lat),
+        crs="EPSG:4326"
+    ).to_crs(ruler.metric_crs)
+
+    results = []
+    min_dist = 0.0
+
+    for stop_id in stop_sequence:
+        row = gdf[gdf['stop_id'] == stop_id]
+        if row.empty:
+            continue
+        row = row.iloc[0]
+
+        candidates = ruler.find_candidates(
+            row.geometry, after=min_dist, tolerance_m=tolerance_m)
+
+        if candidates:
+            best_offset = min(c['offset'] for c in candidates)
+
+            # Accept earliest candidate whose offset is within 2x of best
+            # or within 15m absolute, whichever is more generous.
+            threshold = max(best_offset * 2, 15)
+
+            chosen = None
+            for c in candidates:  # sorted by dist
+                if c['offset'] <= threshold:
+                    chosen = c
+                    break
+
+            if chosen is None:
+                chosen = min(candidates, key=lambda c: c['offset'])
+        else:
+            chosen = ruler.project(row.geometry, after=min_dist)
+
+        snapped = ruler.line.interpolate(chosen['dist'])
+
+        results.append({
+            'stop_id': stop_id,
+            'stop_name': row.get('stop_name', ''),
+            'shape_dist_traveled': chosen['dist'],
+            'offset_m': chosen['offset'],
+            'snapped_geom': snapped,
+            'original_geom': row.geometry,
+            'n_candidates': len(candidates) if candidates else 0,
+        })
+
+        min_dist = chosen['dist']
+
+    return gpd.GeoDataFrame(
+        results, geometry='snapped_geom', crs=ruler.metric_crs)

gtfs_segments/ruler.py

@@ -0,0 +1,165 @@
+"""
+Shape ruler: wraps a GTFS shape as a metric LineString with cumulative
+distance, providing sequential projection and segment slicing.
+"""
+
+import numpy as np
+import geopandas as gpd
+from shapely.geometry import LineString
+
+
+def _utm_crs_from_lon(lon):
+    """Derive UTM EPSG code from a longitude value."""
+    zone = int((lon + 180) / 6) + 1
+    return f"EPSG:326{zone:02d}" if zone <= 60 else "EPSG:32660"
+
+
+class ShapeRuler:
+    """
+    Wraps a GTFS shape as a metric LineString with cumulative distance.
+
+    Parameters
+    ----------
+    shapes_df : DataFrame
+        Full shapes.txt with columns: shape_id, shape_pt_sequence,
+        shape_pt_lat, shape_pt_lon
+    shape_id : int or str
+        Target shape to build the ruler for
+    metric_crs : str or None
+        Projected CRS for distance calculations. If None, auto-detects
+        the UTM zone from the shape's median longitude.
+    """
+
+    def __init__(self, shapes_df, shape_id, metric_crs=None):
+        df = (shapes_df[shapes_df['shape_id'] == shape_id]
+              .sort_values('shape_pt_sequence')
+              .copy())
+        if df.empty:
+            raise ValueError(f"Shape {shape_id} not found in shapes_df")
+
+        self.shape_id = shape_id
+
+        # Auto-detect UTM zone if no CRS provided
+        if metric_crs is None:
+            median_lon = df['shape_pt_lon'].median()
+            metric_crs = _utm_crs_from_lon(median_lon)
+        self.metric_crs = metric_crs
+
+        # Build metric GeoDataFrame of shape vertices
+        self.vertices = gpd.GeoDataFrame(
+            df,
+            geometry=gpd.points_from_xy(df.shape_pt_lon, df.shape_pt_lat),
+            crs="EPSG:4326"
+        ).to_crs(metric_crs).reset_index(drop=True)
+
+        # Cumulative distance at each vertex
+        self.vertices['dist_cum'] = (
+            self.vertices.geometry
+            .distance(self.vertices.geometry.shift())
+            .fillna(0)
+            .cumsum()
+        )
+
+        # Full line in metric CRS
+        self.line = LineString(self.vertices.geometry.tolist())
+        self.length = self.line.length
+
+        # Pre-build segment index for fast windowed search
+        self._seg_starts = []
+        self._seg_lines = []
+        for i in range(len(self.vertices) - 1):
+            self._seg_starts.append(self.vertices['dist_cum'].iloc[i])
+            self._seg_lines.append(
+                LineString([self.vertices.geometry.iloc[i],
+                            self.vertices.geometry.iloc[i + 1]])
+            )
+        self._seg_starts = np.array(self._seg_starts)
+
+    def project(self, point_geom, after=0.0):
+        """
+        Project a point onto the shape, searching only after a minimum
+        distance. Returns dict with dist, offset, snapped.
+        """
+        best_dist = None
+        best_offset = float('inf')
+
+        for seg_start, seg_line in zip(self._seg_starts, self._seg_lines):
+            seg_end = seg_start + seg_line.length
+            if seg_end < after:
+                continue
+            local_proj = seg_line.project(point_geom)
+            global_proj = max(seg_start + local_proj, after)
+            snapped = self.line.interpolate(global_proj)
+            offset = point_geom.distance(snapped)
+            if offset < best_offset:
+                best_offset = offset
+                best_dist = global_proj
+
+        if best_dist is None:
+            best_dist = self.length
+            best_offset = point_geom.distance(
+                self.line.interpolate(self.length))
+
+        snapped = self.line.interpolate(best_dist)
+        return {'dist': best_dist, 'offset': best_offset, 'snapped': snapped}
+
+    def find_candidates(self, point_geom, after=0.0, tolerance_m=50):
+        """
+        Find all distinct positions where a point projects within tolerance.
+
+        A stop at the base of a loop will have candidates at both the entry
+        and exit. Nearby candidates (within 30m along shape) are merged.
+
+        Returns list of dict {dist, offset}, sorted by distance.
+        """
+        raw = []
+        for seg_start, seg_line in zip(self._seg_starts, self._seg_lines):
+            seg_end = seg_start + seg_line.length
+            if seg_end < after:
+                continue
+            local_proj = seg_line.project(point_geom)
+            global_proj = max(seg_start + local_proj, after)
+            snapped = self.line.interpolate(global_proj)
+            offset = point_geom.distance(snapped)
+            if offset <= tolerance_m:
+                raw.append({'dist': global_proj, 'offset': offset})
+
+        if not raw:
+            return []
+
+        # Merge candidates within 30m (keep best offset)
+        raw.sort(key=lambda c: c['dist'])
+        merged = [raw[0]]
+        for c in raw[1:]:
+            if c['dist'] - merged[-1]['dist'] > 30:
+                merged.append(c)
+            elif c['offset'] < merged[-1]['offset']:
+                merged[-1] = c
+        return merged
+
+    def slice(self, d_start, d_end):
+        """
+        Extract the shape geometry between two distances.
+        Returns LineString in metric CRS, or None if degenerate.
+        """
+        if d_end <= d_start:
+            return None
+
+        p1 = self.line.interpolate(d_start)
+        p2 = self.line.interpolate(d_end)
+
+        mask = ((self.vertices['dist_cum'] > d_start) &
+                (self.vertices['dist_cum'] < d_end))
+        inner = self.vertices[mask].geometry.tolist()
+
+        coords = ([(p1.x, p1.y)] +
+                  [(pt.x, pt.y) for pt in inner] +
+                  [(p2.x, p2.y)])
+
+        return LineString(coords) if len(coords) >= 2 else None
+
+    def __repr__(self):
+        return (f"ShapeRuler(shape_id={self.shape_id}, "
+                f"length={self.length:.0f}m, "
+                f"vertices={len(self.vertices)}, "
+                f"crs={self.metric_crs})")

gtfs_segments/segmentation.py

@@ -0,0 +1,56 @@
+"""
+Segment builder: cuts a shape into stop-to-stop segments following
+the original road geometry.
+"""
+
+import geopandas as gpd
+
+
+def segment_route(ruler, projected_stops, output_crs="EPSG:4326"):
+    """
+    Build stop-to-stop segments following the shape geometry.
+
+    Parameters
+    ----------
+    ruler : ShapeRuler
+    projected_stops : GeoDataFrame
+        Output of project_stops_sequential
+    output_crs : str
+        CRS for output (default WGS84)
+
+    Returns
+    -------
+    GeoDataFrame with columns:
+        segment_idx, from_stop_id, to_stop_id, from_stop_name,
+        to_stop_name, segment_dist_m, geometry
+    """
+    sorted_stops = (projected_stops
+                    .sort_values('shape_dist_traveled')
+                    .reset_index(drop=True))
+    segments = []
+
+    for i in range(len(sorted_stops) - 1):
+        sa = sorted_stops.iloc[i]
+        sb = sorted_stops.iloc[i + 1]
+
+        geom = ruler.slice(sa['shape_dist_traveled'],
+                           sb['shape_dist_traveled'])
+        if geom is None:
+            continue
+
+        segments.append({
+            'segment_idx': i,
+            'shape_id': ruler.shape_id,
+            'from_stop_id': sa['stop_id'],
+            'to_stop_id': sb['stop_id'],
+            'from_stop_name': sa.get('stop_name', ''),
+            'to_stop_name': sb.get('stop_name', ''),
+            'segment_dist_m': (sb['shape_dist_traveled'] -
+                               sa['shape_dist_traveled']),
+            'geometry': geom,
+        })
+
+    if not segments:
+        return gpd.GeoDataFrame()
+
+    return gpd.GeoDataFrame(segments, crs=ruler.metric_crs).to_crs(output_crs)