Create Seamlines

polygonal_intersection(a, b, buffer_eps=1e-08)

Returns only the polygonal portion of a ∩ b. If the intersection is line-like or point-like, it buffers slightly to form a polygon.

Parameters:

Name	Type	Description	Default
a	Polygon	Input geometries.	required
b	Polygon	Input geometries.	required
buffer_eps	float	Small buffer distance to 'inflate' line/point intersections.	1e-08

Returns:

Type	Description
	Polygon or MultiPolygon

Source code in spectralmatch/seamline/voronoi_center_seamline.py

def polygonal_intersection(a: Polygon, b: Polygon, buffer_eps: float = 1e-8):
    """
    Returns only the polygonal portion of a ∩ b. If the intersection is line-like or point-like, it buffers slightly to form a polygon.

    Args:
        a (Polygon): Input geometries.
        b (Polygon): Input geometries.
        buffer_eps (float): Small buffer distance to 'inflate' line/point intersections.

    Returns:
        Polygon or MultiPolygon
    """
    inter = a.intersection(b)

    # Case 1: already polygonal
    if inter.geom_type in ("Polygon", "MultiPolygon"):
        return inter

    # Case 2: geometry collection — extract polygonal parts
    if inter.geom_type == "GeometryCollection":
        polys = [g for g in inter.geoms if g.geom_type in ("Polygon", "MultiPolygon")]
        if polys:
            return unary_union(polys)

    # Case 3: line or point — buffer to small polygon
    if not inter.is_empty:
        # use small fraction of bbox size as buffer
        eps = max(a.bounds[2] - a.bounds[0], a.bounds[3] - a.bounds[1]) * buffer_eps
        return inter.buffer(eps).buffer(0)

    # Case 4: no overlap
    return Polygon()

voronoi_center_seamline(input_images, output_mask, *, aoi_path=None, image_field_name='image', min_point_spacing=10, min_cut_length=0, debug_logs=False, debug_vectors_path=None)

Generates a Voronoi-based seamline mask from edge-matching polygons (EMPs) and writes the result to a vector file.

Parameters:

Name	Type	Description	Default
input_images	(str | List[str], required)	Defines input files from a glob path, folder, or list of paths. Specify like: "/input/files/.tif", "/input/folder" (assumes .tif), ["/input/one.tif", "/input/two.tif"].	required
output_mask	str	Output path for the final seamline polygon vector file.	required
aoi_path	str	Path to an AOI vector file to clip overlapping image polygons; default is None.	None
min_point_spacing	float	Minimum spacing between Voronoi seed points; default is 10.	10
min_cut_length	float	Minimum cutline segment length to retain; default is 0.	0
debug_logs	DebugLogs	Enables debug print statements if True; default is False.	False
image_field_name	str	Name of the attribute field for image ID in output; default is 'image'.	'image'
debug_vectors_path	str | None	Optional path to save debug layers (cutlines, intersections).	None

Outputs

Saves a polygon seamline layer to output_mask, and optionally saves intermediate cutlines to debug_vectors_path.

Source code in spectralmatch/seamline/voronoi_center_seamline.py

def voronoi_center_seamline(
    input_images: Universal.CreateInFolderOrListFiles,
    output_mask: str,
    *,
    aoi_path: str | None = None,
    image_field_name: str = "image",
    min_point_spacing: float = 10,
    min_cut_length: float = 0,
    debug_logs: Universal.DebugLogs = False,
    debug_vectors_path: str | None = None,
) -> None:
    """
    Generates a Voronoi-based seamline mask from edge-matching polygons (EMPs) and writes the result to a vector file.

    Args:
        input_images (str | List[str], required): Defines input files from a glob path, folder, or list of paths. Specify like: "/input/files/*.tif", "/input/folder" (assumes *.tif), ["/input/one.tif", "/input/two.tif"].
        output_mask (str): Output path for the final seamline polygon vector file.
        aoi_path (str, optional): Path to an AOI vector file to clip overlapping image polygons; default is None.
        min_point_spacing (float, optional): Minimum spacing between Voronoi seed points; default is 10.
        min_cut_length (float, optional): Minimum cutline segment length to retain; default is 0.
        debug_logs (Universal.DebugLogs, optional): Enables debug print statements if True; default is False.
        image_field_name (str, optional): Name of the attribute field for image ID in output; default is 'image'.
        debug_vectors_path (str | None, optional): Optional path to save debug layers (cutlines, intersections).

    Outputs:
        Saves a polygon seamline layer to `output_mask`, and optionally saves intermediate cutlines to `debug_vectors_path`.
    """

    print("Start voronoi center seamline")

    Universal.validate(
        input_images=input_images,
    )
    input_image_paths = _resolve_paths(
        "search", input_images, kwargs={"default_file_pattern": "*.tif"}
    )

    emps = []
    crs = None
    for path in input_image_paths:
        emp = _emp_polygon_from_image(path)
        emps.append(emp)
        if crs is None:
            ds = gdal.Open(path, gdal.GA_ReadOnly)
            crs = ds.GetProjectionRef()
            ds = None

    for i, emp in enumerate(emps):
        if debug_logs:
            print(f"EMP{i}: area={emp.area:.2f}, bounds={emp.bounds}")

    if debug_vectors_path:
        if os.path.exists(debug_vectors_path): os.remove(debug_vectors_path)
        _save_emp_outlines(
            emps,
            input_image_paths,
            debug_vectors_path,
            crs,
            image_field_name=image_field_name,
        )

    cuts: List[LineString] = []
    for i, (a, b) in enumerate(combinations(emps, 2)):
        ov = a.intersection(b)
        if debug_logs:
            print(f"Overlap {i} area: {ov.area:.2f}")
        if not ov.is_empty:
            if debug_vectors_path:
                _save_intersection_points(a, b, debug_vectors_path, crs, f"{i}")
            cut = _compute_centerline(
                a,
                b,
                min_point_spacing,
                min_cut_length,
                debug_logs,
                crs,
                debug_vectors_path,
            )
            cuts.append(cut)

    # Optionally save cutlines
    if debug_vectors_path:
        schema = {"geometry": "LineString", "properties": {"pair_id": "str"}}
        with fiona.open(
            debug_vectors_path,
            "w",
            driver="GPKG",
            crs_wkt=crs,
            schema=schema,
            layer="cutlines",
        ) as dst:
            for idx, line in enumerate(cuts):
                dst.write(
                    {
                        "geometry": mapping(line),
                        "properties": {"pair_id": f"{idx}"},
                    }
                )

    segmented: List[Polygon] = []
    for idx, emp in enumerate(emps):
        relevant = [c for c in cuts if emp.intersects(c)]
        seg = _segment_emp(emp, relevant, debug_logs)
        if debug_logs:
            print(
                f"EMP{idx} has {len(relevant)} intersecting cuts and {seg.area:.2f} segmented area"
            )
        segmented.append(seg)

    if aoi_path is not None:
        segmented = _mask_by_aoi(segmented, aoi_path)

    schema = {"geometry": "Polygon", "properties": {image_field_name: "str"}}
    with fiona.open(
        output_mask, "w", driver="GPKG", crs_wkt=crs, schema=schema, layer="seamlines"
    ) as dst:
        for img, poly in zip(input_image_paths, segmented):
            dst.write(
                {
                    "geometry": mapping(poly),
                    "properties": {
                        image_field_name: os.path.splitext(os.path.basename(img))[0]
                    },
                }
            )