dapper.topounit.topomake

Topographic unit generation utilities.

Functions

add_topounit_image_samples(topounits_gdf, ...)	Attach additional sampled properties from arbitrary GEE images to each topounit.
build_bins_for_source(source_id, image, ...)	Produces a list of bin definitions for a source.
build_source(source_id, feature, ...[, ...])	Returns (single-band ee.Image renamed to 'v', native_scale_m, meta dict).
choose_hand_image([desired_scale, ...])	Auto-select among available HAND products based on a desired scale (m) and/or fixed edges. If edges extend >100 m, prefer *_1000 variants. Returns (hand_image_single_band, native_scale_m).
make_topounits(aoi[, sources, binning, ...])	SINGLE-AOI topounit builder.
make_topounits_for_domain(domain, *, ...[, ...])	Compute topounits per-domain-geometry and attach them to the Domain.

dapper.topounit.topomake.add_topounit_image_samples(topounits_gdf, sampling_specs, default_scale=None, ensure_pixel_centers=True, verbose=False)

Attach additional sampled properties from arbitrary GEE images to each topounit.

Parameters:

• topounits_gdf (GeoDataFrame) – Output from make_topounits(return_as=’gdf’). Must contain ‘band_name’.

• sampling_specs (list[dict]) –

  Each dict describes one sampled variable with keys:

  • ’image’ : ee.Image or image ID string

  • ’band’ : optional band name (if omitted, image must be single-band)

  • ’reducer’ : str {‘mean’,’min’,’max’,’std’} or ee.Reducer

  • ’out_name’: name of the column to add

  • ’scale’ : optional scale [m]; overrides default_scale

• default_scale (float, optional) – Default scale [m] for specs that do not define ‘scale’. If None, uses topounits_gdf[‘analysis_scale_m’].iloc[0] if present; otherwise the nominal scale of each image.

• ensure_pixel_centers (bool, default True) – If True, guard against polygons with no pixel centers.

• verbose (bool, default False) – Print which variables were attached.

Returns:

Copy of topounits_gdf with new columns added.

Return type:

GeoDataFrame

dapper.topounit.topomake.build_bins_for_source(source_id, image, region, binning_spec, analysis_scale, aspect_ranges_default=None)

Produces a list of bin definitions for a source. Numeric sources (elev, hand): [{‘id’, ‘low’, ‘high’, ‘label’, ‘method’, ‘units’}] Aspect (circular): [{‘id’,’start’,’end’,’wrap’,’label’,’method’,’units’}]

dapper.topounit.topomake.build_source(source_id, feature, desired_scale_hint, binning_spec, dem_source='arcticdem', verbose=False)

Returns (single-band ee.Image renamed to ‘v’, native_scale_m, meta dict).

Built-in source_ids:

• ‘elev’ : ArcticDEM elevation (meters)

• ‘hand’ : multi-scale HAND auto-selection (meters)

• ‘aspect’ : Aspect (degrees) derived from DEM

• ‘cti’ : Compound Topographic Index (dimensionless), mosaicked & scaled

Custom image:

If binning[source_id] contains key ‘image’, that value MUST be a single-band ee.Image (already mosaicked/selected/masked as needed). We validate single-band and use it. If the image advertises a degree-based/undefined native scale (~111,319 m), we coerce the native scale to desired_scale_hint (if provided) or 90 m to avoid over-clamping.

dapper.topounit.topomake.choose_hand_image(desired_scale=None, hand_edges=None, verbose=False)

Auto-select among available HAND products based on a desired scale (m) and/or fixed edges. If edges extend >100 m, prefer *_1000 variants. Returns (hand_image_single_band, native_scale_m).

dapper.topounit.topomake.make_topounits(aoi, sources=None, binning=None, combine='cartesian', combine_order=None, max_topounits=256, dem_source='arcticdem', return_as='gdf', export_scale='native', asset_name='topounits', asset_ftype='GeoJSON', min_patch_pixels=None, target_pixels_per_topounit=500, target_scale=None, verbose=False)

SINGLE-AOI topounit builder.

aoi can be:

• Domain (must have exactly 1 geometry in domain.support / domain.gdf)

• shapely geometry

• ee.Geometry / ee.Feature / ee.FeatureCollection

• str (GEE FeatureCollection asset id)

If sources is None, sources = list(binning.keys()) (dict insertion order).

dapper.topounit.topomake.make_topounits_for_domain(domain, *, sources, binning, combine='cartesian', combine_order=None, max_topounits=256, dem_source='arcticdem', export_scale='native', min_patch_pixels=None, target_pixels_per_topounit=500, target_scale=None, verbose=False, allow_slow_ncells=25)

Compute topounits per-domain-geometry and attach them to the Domain.

• For domain.mode == ‘sites’: this computes per-run (each run is 1 geom) and returns a Domain with a concatenated topounits table; iter_runs() can later subset by gid.

• For domain.mode == ‘cellset’: loops over each cell geometry and computes topounits for each gid separately (can be slow for large N).

Returns:

domain with domain.topounits populated (expects Domain.with_topounits exists).

Return type:

Domain

Parameters:

• domain (Domain)

• allow_slow_ncells (int)