Skip to content

samstars.features.seed_generation

samstars.features.seed_generation

SeedParams dataclass

Seed detection settings for aligned imagery-grid rasters.

Attributes:

Name Type Description
chm_raster Path

Canopy height GeoTIFF in meters.

den_raster Path

First-return counts or density GeoTIFF.

cost_raster Path

Boundary cost GeoTIFF on the same grid.

d_min float

Minimum peak value in both CHM and density; interpret against each raster's units.

min_dist_px int

Peak-search radius in pixels.

gauss_sigma int

Gaussian smoothing scale in pixels before peak detection.

merge_radius float

Candidate grouping distance in projected CRS units.

cost_weight float

Strength of the cost penalty between candidate seeds.

min_canopy_height float

Minimum canopy height in meters at a candidate seed.

Source code in samstars/features/seed_generation.py
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
@dataclass
class SeedParams:
    """Seed detection settings for aligned imagery-grid rasters.

    Attributes:
        chm_raster: Canopy height GeoTIFF in meters.
        den_raster: First-return counts or density GeoTIFF.
        cost_raster: Boundary cost GeoTIFF on the same grid.
        d_min: Minimum peak value in both CHM and density; interpret against each
            raster's units.
        min_dist_px: Peak-search radius in pixels.
        gauss_sigma: Gaussian smoothing scale in pixels before peak detection.
        merge_radius: Candidate grouping distance in projected CRS units.
        cost_weight: Strength of the cost penalty between candidate seeds.
        min_canopy_height: Minimum canopy height in meters at a candidate seed.
    """
    chm_raster: Path
    den_raster: Path
    cost_raster: Path
    d_min: float = 4.5
    min_dist_px: int = 4
    gauss_sigma: int = 2
    eps_scale: float = 0.15
    min_eps: float = 1.0
    max_eps: float = 6.0
    z_thresh: float = 1.0
    min_samples: int = 1
    merge_radius: float = 3.0
    cost_weight: float = 3.0
    xy_thresh: float = 0.3
    samples: int = 8
    dz_merge: float = 1.0
    min_canopy_height: float = 2.0
    debug_dist: bool = False

build_sparse_cost_graph(xs, ys, cost, tfm, weight, xy_thresh, merge_radius, samples=8)

Build sparse cost graph.

Source code in samstars/features/seed_generation.py
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def build_sparse_cost_graph(xs: np.ndarray,
                            ys: np.ndarray,
                            cost: np.ndarray,
                            tfm,
                            weight: float,
                            xy_thresh: float,
                            merge_radius: float,
                            samples: int = 8) -> "coo_matrix":
    """Build sparse cost graph."""
    n = len(xs)
    kd = cKDTree(np.c_[xs, ys])
    rows, cols, data = [], [], []
    ts = np.linspace(0., 1., samples + 2, dtype=np.float32)[1:-1]

    search_r = merge_radius + xy_thresh + 1e-6
    for i in range(n):
        xi, yi = xs[i], ys[i]
        neigh = kd.query_ball_point([xi, yi], search_r)
        neigh = [j for j in neigh if j > i]

        for j in neigh:
            dx, dy = xs[j] - xi, ys[j] - yi
            xy_dist = math.hypot(dx, dy)
            if xy_dist == 0.:
                continue

            if xy_dist <= xy_thresh or weight == 0.:
                d_eff = xy_dist
            else:
                xs_line = xi + ts * dx
                ys_line = yi + ts * dy
                rr, cc = rowcol(tfm, xs_line, ys_line, op=float)
                rr = np.clip(rr.round().astype(int), 0, cost.shape[0] - 1)
                cc = np.clip(cc.round().astype(int), 0, cost.shape[1] - 1)
                mean_cost = cost[rr, cc].mean()
                d_eff = xy_dist * (1. + weight * mean_cost)

            if d_eff <= merge_radius:
                rows.extend((i, j)); cols.extend((j, i))
                data.extend((d_eff, d_eff))

    return coo_matrix((data, (rows, cols)), shape=(n, n)).tocsr()

canonical_seeds(params)

Detect CHM and density peaks and return one point per candidate cluster.

Parameters:

Name Type Description Default
params SeedParams

Raster paths and detection controls. Rasters must share a CRS, pixel grid, and extent; use a projected CRS in meters.

required

Returns:

Type Description
GeoDataFrame

A GeoDataFrame with id and geometry columns in the input CRS. Save it

GeoDataFrame

with to_file to create seeds.gpkg. Raises SystemExit if no candidates

GeoDataFrame

survive detection and canopy-height filtering.

Source code in samstars/features/seed_generation.py
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
def canonical_seeds(params: SeedParams) -> gpd.GeoDataFrame:
    """Detect CHM and density peaks and return one point per candidate cluster.

    Args:
        params: Raster paths and detection controls. Rasters must share a CRS,
            pixel grid, and extent; use a projected CRS in meters.

    Returns:
        A GeoDataFrame with id and geometry columns in the input CRS. Save it
        with to_file to create seeds.gpkg. Raises SystemExit if no candidates
        survive detection and canopy-height filtering.
    """
    chm_peaks = detect_peaks(params.chm_raster, "chm",
                             params.d_min, params.min_dist_px, params.gauss_sigma)
    den_peaks = detect_peaks(params.den_raster, "den",
                             params.d_min, params.min_dist_px, params.gauss_sigma)

    seeds = gpd.GeoDataFrame(pd.concat([chm_peaks, den_peaks], ignore_index=True),
                             geometry="geometry", crs=chm_peaks.crs)
    if seeds.empty:
        sys.exit("No seeds after CHM & density sampling.")

    seeds["x"], seeds["y"] = seeds.geometry.x, seeds.geometry.y
    seeds["canopy_height"] = _sample_raster_values(
        params.chm_raster,
        seeds["x"].to_numpy(),
        seeds["y"].to_numpy(),
    )
    seeds = seeds[np.isfinite(seeds["canopy_height"])]
    seeds = seeds[seeds["canopy_height"] >= params.min_canopy_height].reset_index(drop=True)
    if seeds.empty:
        sys.exit(
            "No seeds after applying the CHM canopy-height filter "
            f"(min_canopy_height={params.min_canopy_height})."
        )

    pts_xy = seeds[["x", "y"]].values

    kd = cKDTree(pts_xy)
    cluster = -np.ones(len(seeds), dtype=int)
    cid = 0
    for i in range(len(seeds)):
        if cluster[i] != -1:
            continue
        eps = float(np.clip(params.eps_scale * seeds.height.iloc[i],
                            params.min_eps, params.max_eps))
        idx = kd.query_ball_point(pts_xy[i], eps)
        if params.z_thresh >= 0 and np.ptp(seeds.height.iloc[idx]) > params.z_thresh:
            continue
        if len(idx) >= params.min_samples:
            cluster[idx] = cid
            cid += 1
    seeds["cluster1"] = cluster

    with rasterio.open(params.cost_raster) as src:
        cost = src.read(1).astype(np.float32)
        nodata = src.nodatavals[0] if src.nodatavals[0] is not None else np.nan
        cost[cost == nodata] = 1.0
        tfm = src.transform

    xs, ys = seeds["x"].values, seeds["y"].values
    G = build_sparse_cost_graph(xs, ys, cost, tfm,
                                params.cost_weight,
                                params.xy_thresh,
                                params.merge_radius,
                                samples=params.samples)

    if params.debug_dist and G.nnz:
        print(f"d_eff  min/median/max = "
              f"{G.data.min():.2f} / {np.median(G.data):.2f} / {G.data.max():.2f}")

    db2 = DBSCAN(eps=params.merge_radius, min_samples=1,
                 metric="precomputed", n_jobs=-1).fit(G)
    seeds["cluster"] = db2.labels_

    # optional height‑based split inside a cluster
    if params.dz_merge > 0:
        new_cl = np.empty_like(seeds["cluster"])
        new_id = 0
        for old_id, sub in seeds.groupby("cluster"):
            if np.ptp(sub.height) <= params.dz_merge:
                new_cl[sub.index] = new_id
                new_id += 1
            else:
                mid = sub.height.median()
                lo = sub[sub.height <= mid].index
                hi = sub[sub.height >  mid].index
                for idx in (lo, hi):
                    if idx.size:
                        new_cl[idx] = new_id
                        new_id += 1
        seeds["cluster"] = new_cl


    centres = (seeds
               .groupby("cluster", as_index=False)
               .agg(x=("x", "mean"),
                    y=("y", "mean"),
                    height=("height", "max")))
    centres["id"] = np.arange(len(centres))

    gdf_centres = gpd.GeoDataFrame(
        centres,
        geometry=gpd.points_from_xy(centres.x, centres.y),
        crs=seeds.crs
    )[["id", "geometry"]]
    return gdf_centres

detect_peaks(raster_path, origin, d_min, min_dist_px, sigma=0)

Detect peaks.

Source code in samstars/features/seed_generation.py
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def detect_peaks(raster_path: Path | str,
                 origin: str,
                 d_min: float,
                 min_dist_px: int,
                 sigma: int = 0) -> gpd.GeoDataFrame:
    """Detect peaks."""
    raster_path = Path(raster_path)
    if not raster_path.exists():
        raise FileNotFoundError(raster_path)

    with rasterio.open(raster_path) as src:
        arr = src.read(1, masked=True).astype(np.float32).filled(np.nan)
        tfm, crs = src.transform, src.crs

    if sigma > 0:
        arr = gaussian_filter(arr, sigma=sigma)

    mask_local_max = arr == maximum_filter(arr, size=2 * min_dist_px + 1)
    peaks = np.logical_and(mask_local_max, arr >= d_min)
    rows, cols = np.where(peaks)
    xs, ys = xy(tfm, rows, cols, offset="center")
    heights = arr[rows, cols]

    return gpd.GeoDataFrame(
        dict(id=np.arange(rows.size),
             height=heights,
             origin=origin),
        geometry=gpd.points_from_xy(xs, ys),
        crs=crs
    )