`nemora.synthesis`

The synthesis package bundles helper modules for:

tessellation: configuration objects describing the rlandscape-style point processes, seed counts, and editing knobs that inform Voronoi tiling.
stands: routines that translate vegetation/age-class distributions into reusable templates (inspired by the FLG Weibull-based workflow).
exporters: JSON/GeoJSON convenience functions for persisting synthesis metadata and placeholder geometries while the full CLI matures.

Seed-point configuration helpers for Voronoi-based landscape tiling.

The CJFR rlandscape paper describes a mixture of four point processes and two editing knobs (hole/merge fractions) that collectively control the number of management units, polygon area variation, and vertex-degree statistics. This module captures those inputs so downstream synthesis code (Phase 1 of the plan) can generate repeatable seed sets and share the configuration with docs/tests.

class nemora.synthesis.tessellation.ClusterConfig(size=6, spread=0.05)[source]

Parameters controlling the cluster point process.

Parameters:

size (int)
spread (float)

class nemora.synthesis.tessellation.InhibitionConfig(min_distance=None, max_attempts_per_point=500)[source]

Parameters controlling the inhibition (SSI) process.

Parameters:

min_distance (float | None)
max_attempts_per_point (int)

resolved_distance(aspect_ratio, count)[source]

Derive a fallback inhibition distance when none was provided.

Return type:

float

Parameters:

aspect_ratio (float)
count (int)

class nemora.synthesis.tessellation.LatticeConfig(resolution=None, jitter=0.0)[source]

Parameters controlling the lattice/grid process.

Parameters:

resolution (tuple[int, int] | None)
jitter (float)

class nemora.synthesis.tessellation.MaskGeometry(polygons, name=None, mode=MaskMode.CLIP)[source]

Optional clipping geometry for Voronoi polygons.

Parameters:

polygons (list[ndarray])
name (str | None)
mode (MaskMode)

class nemora.synthesis.tessellation.MaskMode(value)[source]: Mask behaviour for polygon overlays.

class nemora.synthesis.tessellation.PointProcessMix(uniform=1.0, cluster=0.0, inhibition=0.0, lattice=0.0)[source]

Proportions for the four rlandscape point processes.

Parameters:

uniform (float)
cluster (float)
inhibition (float)
lattice (float)

as_array()[source]

Return the normalised weights as an array.

Return type:: ndarray

normalized()[source]

Return a version scaled so the proportions sum to 1.

Return type:: PointProcessMix

class nemora.synthesis.tessellation.RasterMask(values, threshold=0.0, mode=RasterMode.KEEP, name=None)[source]

Raster-based modifier that keeps or excludes polygons.

Parameters:

values (ndarray)
threshold (float)
mode (RasterMode)
name (str | None)

class nemora.synthesis.tessellation.RasterMode(value)[source]: Raster modifier behaviour.

class nemora.synthesis.tessellation.SeedLayoutConfig(mode=SeedLayoutMode.RANDOM, points=None, source=None, geojson_polygons=None)[source]

Deterministic layout configuration (hex grid or imported points).

Parameters:

mode (SeedLayoutMode)
points (ndarray | None)
source (str | None)
geojson_polygons (list[ndarray] | None)

class nemora.synthesis.tessellation.SeedLayoutMode(value)[source]: Seed placement strategies available to callers/CLI.

class nemora.synthesis.tessellation.VoronoiEditConfig(hole_fraction=0.0, merge_fraction=0.0)[source]

Placeholder for polygon deletion/merging controls.

Parameters:

hole_fraction (float)
merge_fraction (float)

class nemora.synthesis.tessellation.VoronoiMetrics(polygon_count, area_mean, area_cv, vertex_degree_mean, vertex_degree_std)[source]

Summary statistics matching the CJFR target controls.

Parameters:

polygon_count (int)
area_mean (float)
area_cv (float)
vertex_degree_mean (float)
vertex_degree_std (float)

class nemora.synthesis.tessellation.VoronoiSeedConfig(count, aspect_ratio=1.0, mix=<factory>, cluster=<factory>, inhibition=<factory>, lattice=<factory>, edit=<factory>, mask=None, mask_overlays=<factory>, raster_masks=<factory>, layout=<factory>, rng=None)[source]

Input knobs for the (future) Voronoi generator.

Parameters:

count (int)
aspect_ratio (float)
mix (PointProcessMix)
cluster (ClusterConfig)
inhibition (InhibitionConfig)
lattice (LatticeConfig)
edit (VoronoiEditConfig)
mask (MaskGeometry | None)
mask_overlays (list[MaskGeometry])
raster_masks (list[RasterMask])
layout (SeedLayoutConfig)
rng (Generator | None)

class nemora.synthesis.tessellation.VoronoiSeedResult(points, config, process_counts, hole_points, merge_pairs, polygons, metrics)[source]

Container for the generated seeds plus bookkeeping metadata.

Parameters:

points (ndarray)
config (VoronoiSeedConfig)
process_counts (dict[str, int])
hole_points (ndarray)
merge_pairs (ndarray)
polygons (list[ndarray])
metrics (VoronoiMetrics)

metadata()[source]

Return a JSON-serialisable summary of the seed configuration.

Return type:: dict[str, object]

nemora.synthesis.tessellation.generate_seed_points(config)[source]

Generate provisional seed coordinates for Phase 1 prototypes.

Return type:: VoronoiSeedResult
Parameters:: config (VoronoiSeedConfig)

nemora.synthesis.tessellation.load_mask_from_geojson(path, *, name=None, mode=MaskMode.CLIP)[source]

Load a simple polygon or multipolygon mask from GeoJSON.

Return type:

MaskGeometry

Parameters:

path (Path)
name (str | None)
mode (MaskMode)

nemora.synthesis.tessellation.load_polygons_from_geojson(path)[source]

Return polygon coordinates from a GeoJSON file.

Return type:: list[ndarray]
Parameters:: path (Path)

nemora.synthesis.tessellation.load_raster_mask(path, *, threshold=0.0, mode=RasterMode.KEEP, name=None)[source]

Load a raster (NumPy .npy/.npz or CSV/txt) used to keep/exclude polygons.

Return type:

RasterMask

Parameters:

path (Path)
threshold (float)
mode (RasterMode)
name (str | None)

Stand-attribute templates inspired by the FLG workflow.

class nemora.synthesis.stands.StandAttributeSample(vegetation_type, age_class, area)[source]

Concrete stand attribute sampled from a template.

Parameters:

vegetation_type (str)
age_class (str)
area (float)

class nemora.synthesis.stands.StandAttributeTemplate(vegetation_type, age_class_cdf, patch_weibull)[source]

Reusable patch recipe derived from vegetation/age-class tables.

Parameters:

vegetation_type (str)
age_class_cdf (Sequence[tuple[str, float]])
patch_weibull (tuple[float, float, float])

sample_age_class(rng=None)[source]

Sample an age-class label using the stored cumulative probabilities.

Return type:: str
Parameters:: rng (Generator | None)

sample_patch_size(rng=None, size=1)[source]

Sample patch areas via a shifted/scaled Weibull distribution.

Return type:

ndarray

Parameters:

rng (Generator | None)
size (int)

class nemora.synthesis.stands.StandBootstrapAssignment(stand_id, vegetation_type, age_class, area, bootstrap_id)[source]

Resolved bootstrap reference for a stand attribute sample.

Parameters:

stand_id (str)
vegetation_type (str)
age_class (str)
area (float)
bootstrap_id (str)

class nemora.synthesis.stands.StandBootstrapLibraryEntry(identifier, source, metadata, dbh_vectors)[source]

Loaded bootstrap payload (metadata + DBH vectors).

Parameters:

identifier (str)
source (str)
metadata (dict[str, object])
dbh_vectors (dict[str, list[float]])

class nemora.synthesis.stands.StandBootstrapManifest(attributes_source, plan_source, assignments, bootstraps)[source]

Resolved bootstrap manifest linking stands to payloads.

Parameters:

attributes_source (str | None)
plan_source (str | None)
assignments (Sequence[StandBootstrapAssignment])
bootstraps (Mapping[str, StandBootstrapLibraryEntry])

class nemora.synthesis.stands.StandBootstrapPlan(rules, default_rule=None)[source]

Parsed bootstrap plan describing stand-to-payload rules.

Parameters:

rules (Sequence[StandBootstrapRule])
default_rule (StandBootstrapRule | None)

class nemora.synthesis.stands.StandBootstrapRule(identifier, source, vegetation_type, age_class, bootstrap_path=None, analytic_metadata=None)[source]

Rule describing how to attach a bootstrap payload to a stand sample.

Parameters:

identifier (str)
source (str)
vegetation_type (str | None)
age_class (str | None)
bootstrap_path (Path | None)
analytic_metadata (Mapping[str, object] | None)

nemora.synthesis.stands.build_bootstrap_assignments(samples, plan, *, id_prefix='stand', start_index=1)[source]

Resolve bootstrap payloads for each stand sample.

Return type:

tuple[list[StandBootstrapAssignment], dict[str, StandBootstrapLibraryEntry]]

Parameters:

samples (Sequence[StandAttributeSample])
plan (StandBootstrapPlan)
id_prefix (str)
start_index (int)

nemora.synthesis.stands.build_stand_features(polygons, samples, *, assignments=None, bootstrap_library=None)[source]

Pair Voronoi polygons with sampled attributes and return GeoJSON features.

Return type:

list[dict[str, object]]

Parameters:

polygons (Sequence[ndarray])
samples (Sequence[StandAttributeSample])
assignments (Sequence[StandBootstrapAssignment] | None)
bootstrap_library (Mapping[str, StandBootstrapLibraryEntry] | None)

nemora.synthesis.stands.build_templates(records)[source]

Convert raw vegetation-type tables into reusable templates.

Each record is expected to expose:

vegetation_type: identifier string
age_classes: sequence of (label, cumulative_probability)
patch_weibull: (shape, scale, shift) tuple describing patch areas

Return type:: list[StandAttributeTemplate]
Parameters:: records (Iterable[Mapping[str, object]])

nemora.synthesis.stands.load_bootstrap_manifest(path)[source]

Load a stand→bootstrap manifest produced by the linker CLI.

Return type:: StandBootstrapManifest
Parameters:: path (Path)

nemora.synthesis.stands.load_bootstrap_plan(path)[source]

Load a bootstrap assignment plan describing stand → payload rules.

Return type:: StandBootstrapPlan
Parameters:: path (Path)

nemora.synthesis.stands.load_samples_from_json(path)[source]

Load stand attribute samples (vegetation/age/area) from JSON.

Return type:: list[StandAttributeSample]
Parameters:: path (Path)

nemora.synthesis.stands.load_templates_from_json(path)[source]

Load stand templates from a JSON file (list of record dictionaries).

Return type:: list[StandAttributeTemplate]
Parameters:: path (Path)

nemora.synthesis.stands.sample_stand_attributes(templates, *, total_area, rng=None, weights=None)[source]

Fill total_area with sampled stand attributes.

Return type:

list[StandAttributeSample]

Parameters:

templates (Sequence[StandAttributeTemplate])
total_area (float)
rng (Generator | None)
weights (Sequence[float] | None)

Lightweight exporters for upcoming synthesis artifacts.

nemora.synthesis.exporters.export_geojson(features, path, crs=None)[source]

Emit a FeatureCollection skeleton for downstream GIS tooling.

Return type:

None

Parameters:

features (Iterable[Mapping[str, object]])
path (Path)
crs (str | None)

nemora.synthesis.exporters.export_metadata_json(metadata, path)[source]

Write synthesis metadata (control knobs, metrics, provenance) to disk.

Return type:

None

Parameters:

metadata (Mapping[str, object])
path (Path)

nemora.synthesis.exporters.export_seed_recipe(result, path, *, include_points=True, include_polygons=False)[source]

Persist a seed recipe JSON (config + metadata, optionally raw coordinates).

Return type:

None

Parameters:

result (VoronoiSeedResult)
path (Path)
include_points (bool)
include_polygons (bool)

nemora.synthesis.exporters.export_stand_geojson_from_polygons(polygons, samples, path, *, crs=None, strict=False, expected_count=None, assignments=None, bootstrap_library=None)[source]

Export a GeoJSON pairing polygons and stand samples.

Parameters:

polygons (Sequence[ndarray]) – Iterable of polygon arrays (already filtered to remove empty polygons).
samples (Sequence[StandAttributeSample]) – Stand attribute samples produced by sample_stand_attributes.
path (Path) – Output GeoJSON file path.
crs (str | None) – Optional CRS identifier stored in the GeoJSON metadata.
strict (bool) – When True, require the generated feature count to match expected_count (or the min of polygons/samples when the expectation is omitted). A mismatch raises ValueError.
expected_count (int | None) – Optional explicit expected feature count for strict mode.
assignments (Sequence[StandBootstrapAssignment] | None)
bootstrap_library (Mapping[str, StandBootstrapLibraryEntry] | None)

Return type: