Skip to content

samstars.data.tiling

samstars.data.tiling

Prepare aligned imagery, canopy heights, cost rasters, and crown seeds.

build_single_tile(*, img, chm, den, crowns=None, rgb_bands=None, nir_band=None, texture_band=None, slic=None, out=Path('tiles'), tile_name='tile_000_000', cost_weights=(0.4, 0.3, 0.3, 0.0), seed_params=None, thin_seeds=True, thin_dist=0.8, seed_d_min=4.5, seed_min_dist_px=4, seed_gauss_sigma=2, seed_min_samples=1, seed_merge_radius=3.0, seed_min_canopy_height=2.0, write_den=False, skip_existing=True)

Prepare one scene as a tile and return its parent directory.

Uses the same band selection, alignment, and seed controls as build_tiles. crowns, when supplied, is copied into the tile as crowns.gpkg for training. The entire scene is processed as one tile; use build_tiles for larger areas.

Source code in samstars/data/tiling.py
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
def build_single_tile(*,
                      img: Path,
                      chm: Path,
                      den: Path,
                      crowns: Path | None = None,
                      rgb_bands: tuple[int, int, int] | None = None,
                      nir_band: int | None = None,
                      texture_band: int | None = None,
                      slic: Path | None = None,
                      out: Path = Path("tiles"),
                      tile_name: str = "tile_000_000",
                      cost_weights: tuple[float, float, float, float] = (0.4, 0.3, 0.3, 0.0),
                      seed_params: SeedParams | None = None,
                      thin_seeds: bool = True,
                      thin_dist: float = 0.8,
                      seed_d_min: float = 4.5,
                      seed_min_dist_px: int = 4,
                      seed_gauss_sigma: int = 2,
                      seed_min_samples: int = 1,
                      seed_merge_radius: float = 3.0,
                      seed_min_canopy_height: float = 2.0,
                      write_den: bool = False,
                      skip_existing: bool = True) -> Path:
    """Prepare one scene as a tile and return its parent directory.

    Uses the same band selection, alignment, and seed controls as `build_tiles`.
    `crowns`, when supplied, is copied into the tile as `crowns.gpkg` for training.
    The entire scene is processed as one tile; use `build_tiles` for larger areas.
    """
    out = Path(out)
    out.mkdir(parents=True, exist_ok=True)

    with rasterio.open(img) as img_ds:
        res = abs(img_ds.transform.a)
        assert abs(res - abs(img_ds.transform.e)) < 1e-6, "non-square pixels"

        rgb_bands = _resolve_image_bands(img_ds.count, rgb_bands, nir_band, texture_band)
        base_meta = img_ds.profile | {
            "driver": "GTiff",
            "count": 3,
            "compress": "deflate",
            "predictor": 2,
            "zlevel": 6,
        }
        img_tfm, img_crs = img_ds.transform, img_ds.crs
        chm_ds, chm_raw = _align_to_img(chm, img_ds)
        den_ds, den_raw = _align_to_img(den, img_ds)
        try:
            tile_dir = out / tile_name
            win = Window(0, 0, img_ds.width, img_ds.height)
            written = _prepare_tile(
                tile_dir=tile_dir,
                img_ds=img_ds,
                chm_ds=chm_ds,
                den_ds=den_ds,
                img_tfm=img_tfm,
                img_crs=img_crs,
                rgb_bands=rgb_bands,
                nir_band=nir_band,
                texture_band=texture_band,
                base_meta=base_meta,
                win=win,
                h=img_ds.height,
                w=img_ds.width,
                res=res,
                slic=slic,
                cost_weights=cost_weights,
                seed_params=seed_params,
                seed_d_min=seed_d_min,
                seed_min_dist_px=seed_min_dist_px,
                seed_gauss_sigma=seed_gauss_sigma,
                seed_min_samples=seed_min_samples,
                seed_merge_radius=seed_merge_radius,
                seed_min_canopy_height=seed_min_canopy_height,
                thin_seeds=thin_seeds,
                thin_dist=thin_dist,
                write_den=write_den,
                skip_existing=skip_existing,
            )
        finally:
            chm_ds.close()
            den_ds.close()
            if chm_raw is not chm_ds:
                chm_raw.close()
            if den_raw is not den_ds:
                den_raw.close()

    if not written:
        raise RuntimeError("No valid tile outputs generated from the provided inputs.")

    tile_dir = out / tile_name
    if crowns is not None:
        crowns = Path(crowns)
        if not crowns.exists():
            raise FileNotFoundError(f"Missing crowns file: {crowns}")
        shutil.copy2(crowns, tile_dir / "crowns.gpkg")

    print("✓ Single-tile inputs written to", out.resolve())
    return out

build_tiles(*, img, chm, den, rgb_bands=None, nir_band=None, texture_band=None, slic=None, out=Path('tiles'), tile=500.0, overlap=20.0, cost_weights=(0.4, 0.3, 0.3, 0.0), seed_params=None, thin_seeds=True, thin_dist=0.8, seed_d_min=4.5, seed_min_dist_px=4, seed_gauss_sigma=2, seed_min_samples=1, seed_merge_radius=3.0, seed_min_canopy_height=2.0, write_den=False, skip_existing=True)

Align lidar rasters to imagery and prepare overlapping segmentation tiles.

Parameters:

Name Type Description Default
img Path

Three-band RGB or multiband imagery with square pixels.

required
chm Path

Canopy heights in meters; resampled to the imagery grid if needed.

required
den Path

First-return counts or density, using the same units as training.

required
rgb_bands tuple[int, int, int] | None

One-based red, green, blue indices; defaults to (1, 2, 3).

None
nir_band int | None

Optional near-infrared band for the NDVI cost term.

None
texture_band int | None

Optional texture band; otherwise use the mean RGB intensity.

None
out Path

Parent directory for tile_000_000 and subsequent tile folders.

Path('tiles')
tile float

Tile width and height in imagery CRS units, normally meters.

500.0
overlap float

Overlap between neighboring tiles, in the same units as tile.

20.0
cost_weights tuple[float, float, float, float]

Height-edge, NDVI-gap, texture, and experimental SLIC weights.

(0.4, 0.3, 0.3, 0.0)
seed_params SeedParams | None

Optional complete seed configuration; overrides seed controls.

None
thin_seeds bool

Reduce closely spaced seed points after detection.

True
thin_dist float

Minimum seed spacing in projected CRS units.

0.8
seed_d_min float

Minimum peak value in the CHM and density rasters.

4.5
seed_min_dist_px int

Peak-search radius in pixels.

4
seed_gauss_sigma int

Gaussian smoothing scale in pixels.

2
seed_merge_radius float

Candidate grouping distance in projected CRS units.

3.0
seed_min_canopy_height float

Minimum canopy height in meters.

2.0
write_den bool

Also save the aligned density raster in each tile.

False
skip_existing bool

Reuse complete tile folders. Set to False after changing inputs or preparation settings, or use a new output directory.

True

Each nonempty tile contains img.tif, chm.tif, cost.tif, and seeds.gpkg.

Source code in samstars/data/tiling.py
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
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def build_tiles(*,
                img: Path,
                chm: Path,
                den: Path,
                rgb_bands: tuple[int, int, int] | None = None,
                nir_band: int | None = None,
                texture_band: int | None = None,
                slic: Path | None = None,
                out: Path = Path("tiles"),
                tile: float = 500.0,
                overlap: float = 20.0,
                cost_weights: tuple[float, float, float, float] = (0.4, 0.3, 0.3, 0.0),
                seed_params: SeedParams | None = None,
                thin_seeds: bool = True,
                thin_dist: float = 0.8,
                seed_d_min: float = 4.5,
                seed_min_dist_px: int = 4,
                seed_gauss_sigma: int = 2,
                seed_min_samples: int = 1,
                seed_merge_radius: float = 3.0,
                seed_min_canopy_height: float = 2.0,
                write_den: bool = False,
                skip_existing: bool = True) -> None:

    """Align lidar rasters to imagery and prepare overlapping segmentation tiles.

    Args:
        img: Three-band RGB or multiband imagery with square pixels.
        chm: Canopy heights in meters; resampled to the imagery grid if needed.
        den: First-return counts or density, using the same units as training.
        rgb_bands: One-based red, green, blue indices; defaults to `(1, 2, 3)`.
        nir_band: Optional near-infrared band for the NDVI cost term.
        texture_band: Optional texture band; otherwise use the mean RGB intensity.
        out: Parent directory for `tile_000_000` and subsequent tile folders.
        tile: Tile width and height in imagery CRS units, normally meters.
        overlap: Overlap between neighboring tiles, in the same units as `tile`.
        cost_weights: Height-edge, NDVI-gap, texture, and experimental SLIC weights.
        seed_params: Optional complete seed configuration; overrides seed controls.
        thin_seeds: Reduce closely spaced seed points after detection.
        thin_dist: Minimum seed spacing in projected CRS units.
        seed_d_min: Minimum peak value in the CHM and density rasters.
        seed_min_dist_px: Peak-search radius in pixels.
        seed_gauss_sigma: Gaussian smoothing scale in pixels.
        seed_merge_radius: Candidate grouping distance in projected CRS units.
        seed_min_canopy_height: Minimum canopy height in meters.
        write_den: Also save the aligned density raster in each tile.
        skip_existing: Reuse complete tile folders. Set to False after changing inputs
            or preparation settings, or use a new output directory.

    Each nonempty tile contains `img.tif`, `chm.tif`, `cost.tif`, and `seeds.gpkg`.
    """
    out = Path(out)
    out.mkdir(parents=True, exist_ok=True)
    with rasterio.open(img) as img_ds:
        res = abs(img_ds.transform.a)
        assert abs(res - abs(img_ds.transform.e)) < 1e-6, "non‑square pixels"

        img_h, img_w = img_ds.height, img_ds.width
        img_tfm, img_crs = img_ds.transform, img_ds.crs
        rgb_bands = _resolve_image_bands(img_ds.count, rgb_bands, nir_band, texture_band)

        base_meta = img_ds.profile | {"driver": "GTiff", "count": 3,
                                      "compress": "deflate", "predictor": 2,
                                      "zlevel": 6}

        chm_ds, chm_raw = _align_to_img(chm, img_ds)
        den_ds, den_raw = _align_to_img(den, img_ds)

        tile_px   = int(round(tile / res))
        stride_px = int(round((tile - overlap) / res))
        tiles = [(ty, tx, r0, c0,
                  min(tile_px, img_h - r0),
                  min(tile_px, img_w - c0))
                 for ty, r0 in enumerate(range(0, img_h, stride_px))
                 for tx, c0 in enumerate(range(0, img_w, stride_px))
                 if r0 < img_h and c0 < img_w]

        pbar = tqdm(total=len(tiles), desc="Tiling", unit="tile")
        for ty, tx, r0, c0, h, w in tiles:
            tile_dir = out / f"tile_{ty:03d}_{tx:03d}"
            win = Window(c0, r0, w, h)
            _prepare_tile(
                tile_dir=tile_dir,
                img_ds=img_ds,
                chm_ds=chm_ds,
                den_ds=den_ds,
                img_tfm=img_tfm,
                img_crs=img_crs,
                rgb_bands=rgb_bands,
                nir_band=nir_band,
                texture_band=texture_band,
                base_meta=base_meta,
                win=win,
                h=h,
                w=w,
                res=res,
                slic=slic,
                cost_weights=cost_weights,
                seed_params=seed_params,
                seed_d_min=seed_d_min,
                seed_min_dist_px=seed_min_dist_px,
                seed_gauss_sigma=seed_gauss_sigma,
                seed_min_samples=seed_min_samples,
                seed_merge_radius=seed_merge_radius,
                seed_min_canopy_height=seed_min_canopy_height,
                thin_seeds=thin_seeds,
                thin_dist=thin_dist,
                write_den=write_den,
                skip_existing=skip_existing,
            )
            pbar.update(1)

        pbar.close()
        chm_ds.close(); den_ds.close()
        if chm_raw is not chm_ds: chm_raw.close()
        if den_raw is not den_ds: den_raw.close()
    print("✓ Tiles written to", out.resolve())