shapelib.tools.lines.interlines package#

Submodules#

shapelib.tools.lines.interlines.core module#

Generate interpolated “interlines” between pairs of grouped lines.

This is a port of optimal-interlines’ InterlinesGenerator. It reuses the clustering engine from shapelib.tools.lines.grouping, then for each group pairs neighboring lines, interpolates an intermediate line scored by its deviation from a reference distance, and classifies the interlines into alternating classes. Generation and optimal selection are separate steps: generate_interlines() returns every interline, and choose_optimal_interlines() reduces each group to its better-scoring class.

shapelib.tools.lines.interlines.core.generate_interlines(lines, distance_threshold=1.5, reference_distance=1.5, include_point_scores=False)[source]#

Generate every interpolated interline between pairs of neighboring lines.

Lines are grouped (see shapelib.tools.lines.grouping.group_lines()), then within each group neighboring lines are paired and an intermediate line is interpolated midway between them. Each interline is scored by how far its sampled points deviate from reference_distance and classified into alternating classes (1 / -1). All interlines are returned; to keep only the better-scoring class per group, pass the result through choose_optimal_interlines(). Filtering lines by talhão is the caller’s responsibility — pass only the lines belonging to a single talhão to process them in isolation.

Parameters:

  • lines (GeoDataFrame) – Line geometries. Must be in a projected CRS (metres), since the distance parameters are in CRS units.

  • distance_threshold (float) – Maximum spacing for two lines to be paired/grouped (CRS units).

  • reference_distance (float) – Target spacing used to score each interline; deviations from it raise the (absolute) score.

  • include_point_scores (bool) – If True, attach a scores_per_point object column holding the per-vertex deviation list for each interline. This column cannot be written to most vector formats and should be dropped before export.

Returns:

One row per interline, carrying the source line’s original attributes plus:

  • group_id : integer id of the cluster the interline belongs to (unique within the call).

  • class_id : alternating class (1 / -1).

  • score : mean signed deviation from reference_distance.

  • abs_score : mean absolute deviation from reference_distance.

  • scores_per_point : per-vertex deviations (only if include_point_scores=True).

Return type:

GeoDataFrame

Examples

>>> import shapelib
>>> lines = shapelib.read_file("lines.shp")
>>> lines.to_utm()
>>> interlines = generate_interlines(lines, distance_threshold=3.5,
...                                  reference_distance=1.5)
>>> sorted(interlines["class_id"].unique())
[-1, 1]
>>> optimal = choose_optimal_interlines(interlines)
>>> sorted(optimal["class_id"].unique())
[1]
shapelib.tools.lines.interlines.core.choose_optimal_interlines(interlines)[source]#

Keep only the better-scoring interline class within each group.

The selection stage of the interlines pipeline: generate_interlines() produces every interline; this function reduces each group to its optimal class. Keeping the two stages separate lets callers inspect/adjust the full set before selecting.

For each group_id the class (1 / -1) with the lower mean abs_score is kept and the other is dropped (see _optimal_class()).

Parameters:

interlines (GeoDataFrame) – Interlines as returned by generate_interlines(). Must carry the group_id, class_id and abs_score columns.

Returns:

The subset holding, per group, only the optimal class. All columns and the CRS are preserved; the index is reset.

Return type:

GeoDataFrame

Raises:

ValueError – If any of the required columns is missing.

Examples

>>> interlines = generate_interlines(lines)
>>> optimal = choose_optimal_interlines(interlines)

shapelib.tools.lines.interlines.models module#

Internal value objects used by the interline generator.

_Interline and _Pair are private implementation details of shapelib.tools.lines.interlines. _Interline extends the grouping _GroupedLine with a per-vertex score and an alternating class; _Pair builds the interline interpolated between two grouped lines.