structura-geo 0.1.0__tar.gz

structura_geo-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: structura-geo
+Version: 0.1.0
+Summary: Terrain reconstruction and terraforming around a captured Minecraft structure: envelope, per-column ground height, and the additive pod that completes a cut-out landscape
+Project-URL: Repository, https://github.com/kirimba1024/structura-geo
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: structura-core<0.3,>=0.2.0
+Requires-Dist: structura-render<0.3,>=0.2.0
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<2,>=1.13
+Requires-Dist: matplotlib<4,>=3.9
+
+# structura-geo
+
+Terrain reconstruction and terraforming around a captured Minecraft structure.
+
+A structure exported from a world is a rectangular *cut* out of a landscape:
+the building comes with whatever ground the selection box happened to slice
+through, and the cut faces are vertical walls. This package rebuilds the
+landscape that was lost, additively — it never removes or replaces a single
+authored block — so the result can be dropped into any terrain at any height
+and still read as a place rather than as a box.
+
+## What is in here
+
+| Module | What it does |
+| --- | --- |
+| `envelope` | The structure's own envelope, interior air, worldgen clearance buffers, `base_y` detection, and `terrain_height_field` — the per-column reconstruction of the natural grade from the ground materials the builder walked on |
+| `terrain_pod` | The pod: the organic body of terrain that completes the cut-out landscape, shaped against that per-column grade |
+| `dome_doors` | Connects authored doors to a glass dome and clips the pod to it |
+| `strip_snow_layer` | Removes the weather layer, which is not part of the build |
+| `terrain_morphology` | Text/ASCII report of a structure's own terrain shape |
+| `terrain_height_render` | The same signal as PNGs: a hillshaded height map, and its contours over a top-down render of the build |
+| `region_report`, `slice_view`, `structure_search` | Inspection of structures without opening the game |
+| `debug_interior_air` | Writes the interior-air mask out as a structure for eyeballing |
+
+## The rules this package holds to
+
+1. **Additive only.** No authored block is ever removed or replaced.
+2. **Never above the build.** For every XZ column, added material may sit
+   beside or below the authored structure — never above it, and never on
+   top of ground the builder themselves declared.
+3. **No face steeper than the angle of repose**, where that is achievable
+   additively — loose material does not stand vertically anywhere in nature,
+   and a vertical cut is what makes a placed structure read as a glitch.
+
+## Install
+
+```
+pip install structura-geo
+```
+
+Depends on `structura-core` (structure NBT) and `structura-render` (block
+colours for the height-field overlay).

structura_geo-0.1.0/README.md

@@ -0,0 +1,42 @@
+# structura-geo
+
+Terrain reconstruction and terraforming around a captured Minecraft structure.
+
+A structure exported from a world is a rectangular *cut* out of a landscape:
+the building comes with whatever ground the selection box happened to slice
+through, and the cut faces are vertical walls. This package rebuilds the
+landscape that was lost, additively — it never removes or replaces a single
+authored block — so the result can be dropped into any terrain at any height
+and still read as a place rather than as a box.
+
+## What is in here
+
+| Module | What it does |
+| --- | --- |
+| `envelope` | The structure's own envelope, interior air, worldgen clearance buffers, `base_y` detection, and `terrain_height_field` — the per-column reconstruction of the natural grade from the ground materials the builder walked on |
+| `terrain_pod` | The pod: the organic body of terrain that completes the cut-out landscape, shaped against that per-column grade |
+| `dome_doors` | Connects authored doors to a glass dome and clips the pod to it |
+| `strip_snow_layer` | Removes the weather layer, which is not part of the build |
+| `terrain_morphology` | Text/ASCII report of a structure's own terrain shape |
+| `terrain_height_render` | The same signal as PNGs: a hillshaded height map, and its contours over a top-down render of the build |
+| `region_report`, `slice_view`, `structure_search` | Inspection of structures without opening the game |
+| `debug_interior_air` | Writes the interior-air mask out as a structure for eyeballing |
+
+## The rules this package holds to
+
+1. **Additive only.** No authored block is ever removed or replaced.
+2. **Never above the build.** For every XZ column, added material may sit
+   beside or below the authored structure — never above it, and never on
+   top of ground the builder themselves declared.
+3. **No face steeper than the angle of repose**, where that is achievable
+   additively — loose material does not stand vertically anywhere in nature,
+   and a vertical cut is what makes a placed structure read as a glitch.
+
+## Install
+
+```
+pip install structura-geo
+```
+
+Depends on `structura-core` (structure NBT) and `structura-render` (block
+colours for the height-field overlay).

structura_geo-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "structura-geo"
+version = "0.1.0"
+description = "Terrain reconstruction and terraforming around a captured Minecraft structure: envelope, per-column ground height, and the additive pod that completes a cut-out landscape"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+  "structura-core>=0.2.0,<0.3",
+  "structura-render>=0.2.0,<0.3",
+  "numpy>=1.26,<3",
+  "scipy>=1.13,<2",
+  "matplotlib>=3.9,<4",
+]
+
+[project.urls]
+Repository = "https://github.com/kirimba1024/structura-geo"
+
+[project.scripts]
+structura-envelope = "structura_geo.envelope:main"
+structura-terrain-pod = "structura_geo.terrain_pod:main"
+structura-dome-doors = "structura_geo.dome_doors:main"
+structura-strip-snow-layer = "structura_geo.strip_snow_layer:main"
+structura-terrain-morphology = "structura_geo.terrain_morphology:main"
+structura-terrain-height-render = "structura_geo.terrain_height_render:main"
+structura-region-report = "structura_geo.region_report:main"
+structura-slice-view = "structura_geo.slice_view:main"
+structura-structure-search = "structura_geo.structure_search:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

structura_geo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

structura_geo-0.1.0/src/structura_geo/debug_interior_air.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Render the interior_air cavern alone as solid lapis blocks, for visual debugging."""
+import argparse
+import math
+
+import numpy as np
+
+from .envelope import adaptive_cavern_radius, compute_masks
+from structura_core import AIR_NAMES, Structure, save_structure
+
+
+class BlankSource:
+    def __init__(self, src):
+        self.data_version = src.data_version
+        self.palette_raw = []
+        self.palette = []
+        self.present = {}
+        self.block_nbt = {}
+        self.entities = []
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("src")
+    parser.add_argument("dst")
+    parser.add_argument("--envelope-radius", type=float, default=1.5)
+    parser.add_argument("--block", default="minecraft:lapis_block")
+    parser.add_argument(
+        "--target", choices=("interior_air", "envelope"), default="interior_air",
+    )
+    args = parser.parse_args()
+
+    src = Structure(args.src)
+    solid = np.zeros(src.size, dtype=bool)
+    for pos, idx in src.present.items():
+        if src.palette[idx] not in AIR_NAMES:
+            solid[pos] = True
+
+    cavern_radius = adaptive_cavern_radius(solid)
+    margin = math.ceil(args.envelope_radius + cavern_radius) + 1
+    solid = np.pad(solid, margin)
+    base_y = int(np.flatnonzero(solid.any(axis=(0, 2)))[0])
+
+    envelope, _, interior_air, _, _ = compute_masks(
+        solid, args.envelope_radius, 0.0, 0.0, base_y,
+    )
+    target = envelope if args.target == "envelope" else interior_air
+
+    shift = (margin, 0, margin)
+    block_count = save_structure(
+        BlankSource(src), args.dst, target.shape, shift,
+        ((pos, args.block) for pos in np.argwhere(target)),
+    )
+    print(f"size={target.shape} lapis_blocks={block_count}")
+
+
+if __name__ == "__main__":
+    main()

structura_geo-0.1.0/src/structura_geo/dome_doors.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""Cut sealed door sockets into a glass dome's own contour. Closed doors
+block water on their own, so the structure is a self-sufficient, sealed
+underwater room with no dependency on anything else ever being built."""
+import argparse
+
+import sys
+
+import numpy as np
+
+from structura_core import AIR_NAMES, Structure, save_structure
+
+AXIS = {"west": (0, -1), "east": (0, 1), "north": (2, -1), "south": (2, 1)}
+HINGE = {"west": "left", "east": "left", "north": "left", "south": "left"}
+FRAME_SEARCH_RADIUS = 8
+
+
+def find_wall(src, center, axis, sign, size, start=None):
+    pos = center[axis] if start is None else start
+    while 0 <= pos < size[axis]:
+        cell = list(center)
+        cell[axis] = pos
+        if tuple(cell) not in src.present:
+            return pos
+        pos += sign
+    return pos
+
+
+def find_dome_exit(in_shell, center, axis, sign, size):
+    """Where a ray from center first leaves the glass shell -- not where it
+    leaves *any* solid block, which is find_wall()'s job and would walk
+    straight through the pod's own seabed sand beyond the dome without
+    stopping. entered guards against a ray that starts outside the shell
+    (center misestimated, or a very thin/holed dome) returning its very
+    first step."""
+    pos = center[axis]
+    entered = False
+    while 0 <= pos < size[axis]:
+        cell = list(center)
+        cell[axis] = pos
+        if in_shell(tuple(cell)):
+            entered = True
+        elif entered:
+            return pos
+        pos += sign
+    return pos
+
+
+def shifted_lookup(mask, shift):
+    def lookup(pos):
+        idx = tuple(p - s for p, s in zip(pos, shift))
+        return all(0 <= v < limit for v, limit in zip(idx, mask.shape)) and bool(mask[idx])
+    return lookup
+
+
+def is_solid(src, pos):
+    index = src.present.get(tuple(pos))
+    return index is not None and src.palette[index] not in AIR_NAMES
+
+
+def frame_positions(door_pos, perp):
+    up = tuple(v + (1 if i == 1 else 0) for i, v in enumerate(door_pos))
+    sill = tuple(v - (1 if i == 1 else 0) for i, v in enumerate(door_pos))
+    sides = []
+    for level in (door_pos, up):
+        for d in (-1, 1):
+            side = list(level)
+            side[perp] += d
+            sides.append(tuple(side))
+    return up, sill, sides
+
+
+def find_wall_at_base(src, anchor, axis, sign, size, perp, start=None):
+    for radius in range(FRAME_SEARCH_RADIUS + 1):
+        for dp in ({0} if radius == 0 else {-radius, radius}):
+            candidate = list(anchor)
+            candidate[perp] += dp
+            if not 0 <= candidate[perp] < size[perp]:
+                continue
+            wall = find_wall(src, candidate, axis, sign, size, start)
+            door_pos = list(candidate)
+            door_pos[axis] = wall - sign
+            return tuple(door_pos)
+    return tuple(anchor)
+
+
+def tunnel_levels(anchor, dome_exit, door_axis_pos, axis, sign):
+    """Every axis position between the dome's own glass shell and the door,
+    inclusive, regardless of which is further out -- a door can legitimately
+    land at or behind the dome exit (no pod material past the glass in that
+    direction at all, so find_wall_at_base's wall-minus-sign lands right at
+    the shell), not always past it. A fixed dome_exit -> door_axis_pos walk
+    stepping by `sign` never terminates when the door isn't actually further
+    out in that direction."""
+    lo, hi = sorted((dome_exit, door_axis_pos))
+    for pos in range(lo, hi + 1):
+        level = list(anchor)
+        level[axis] = pos
+        yield tuple(level)
+
+
+def door_state(facing):
+    lower = f"minecraft:oak_door[half=lower,facing={facing},hinge={HINGE[facing]},open=false,powered=false]"
+    upper = f"minecraft:oak_door[half=upper,facing={facing},hinge={HINGE[facing]},open=false,powered=false]"
+    return lower, upper
+
+
+def auto_center(pod_masks):
+    """Any point at floor height, roughly inside the footprint, works --
+    doors are cut by shooting rays out to the shell, not by a meaningful
+    building center. base_y/raw_footprint are already computed by
+    terrain_pod for this exact structure, so no per-asset input is needed."""
+    masks = np.load(pod_masks)
+    base_y = int(masks["base_y"])
+    footprint = masks["raw_footprint"]
+    xs, zs = np.nonzero(footprint)
+    return int(round(xs.mean())), base_y, int(round(zs.mean()))
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("src")
+    parser.add_argument("dst")
+    parser.add_argument("--center-x", type=int)
+    parser.add_argument("--center-y", type=int)
+    parser.add_argument("--center-z", type=int)
+    parser.add_argument(
+        "--pod-masks",
+        help="terrain_pod's --masks npz; derives the center automatically "
+             "(base_y + footprint centroid) when --center-x/y/z are omitted",
+    )
+    parser.add_argument(
+        "--envelope-masks",
+        help="envelope.py's --masks npz for this same structure; its "
+             "glass_dome tells a door where the dome's own glass shell "
+             "actually is, so the door -- and a connecting glass tunnel -- "
+             "land there instead of wherever terrain_pod's seabed pod "
+             "happens to end, possibly many blocks further out. Without "
+             "it, doors are cut at the first solid-to-air boundary same as "
+             "before, which is only correct when there's no pod material "
+             "past the dome to begin with",
+    )
+    parser.add_argument(
+        "--directions", default="north,south,east,west",
+        help="comma-separated subset of north,south,east,west",
+    )
+    args = parser.parse_args()
+
+    directions = [d.strip() for d in args.directions.split(",") if d.strip()]
+    for d in directions:
+        if d not in AXIS:
+            parser.error(f"unknown direction {d!r}; choose from {sorted(AXIS)}")
+
+    manual = (args.center_x, args.center_y, args.center_z)
+    if all(v is not None for v in manual):
+        center = manual
+    elif any(v is not None for v in manual):
+        parser.error("--center-x/y/z must be given together, or not at all")
+    elif args.pod_masks:
+        center = auto_center(args.pod_masks)
+    else:
+        parser.error("need --center-x/y/z or --pod-masks")
+
+    src = Structure(args.src)
+    size = src.size
+
+    in_shell = None
+    if args.envelope_masks:
+        env = np.load(args.envelope_masks)
+        if "glass_dome" in env and env["glass_dome"].any():
+            shift = (0, 0, 0)
+            if args.pod_masks:
+                shift = tuple(int(v) for v in np.load(args.pod_masks)["shift"])
+            in_shell = shifted_lookup(env["glass_dome"], shift)
+
+    def in_bounds(pos):
+        return all(0 <= v < limit for v, limit in zip(pos, size))
+
+    replacements = []
+    doors = []
+    for facing in directions:
+        axis, sign = AXIS[facing]
+        perp = 2 - axis
+
+        if in_shell is None:
+            door_pos = find_wall_at_base(src, center, axis, sign, size, perp)
+            upper_pos, sill, sides = frame_positions(door_pos, perp)
+            patched = 0
+            for pos in (sill, *sides):
+                if in_bounds(pos) and not is_solid(src, pos):
+                    replacements.append((pos, "minecraft:glass"))
+                    patched += 1
+            if patched:
+                print(f"forced glass frame around {facing} door: {patched} block(s)", file=sys.stderr)
+        else:
+            dome_exit = find_dome_exit(in_shell, center, axis, sign, size)
+            exit_anchor = list(center)
+            exit_anchor[axis] = dome_exit
+            door_pos = find_wall_at_base(
+                src, tuple(exit_anchor), axis, sign, size, perp, start=dome_exit,
+            )
+            upper_pos, sill, sides = frame_positions(door_pos, perp)
+            cleared = glazed = 0
+            for level in tunnel_levels(door_pos, dome_exit, door_pos[axis], axis, sign):
+                level_up, level_sill, level_sides = frame_positions(level, perp)
+                frame = (level_sill, *level_sides) if level == door_pos else level_sides
+                if level != door_pos:
+                    for pos in (level, level_up):
+                        if in_bounds(pos) and is_solid(src, pos):
+                            replacements.append((pos, "minecraft:air"))
+                            cleared += 1
+                for pos in frame:
+                    if in_bounds(pos):
+                        replacements.append((pos, "minecraft:glass"))
+                        glazed += 1
+            if cleared or glazed:
+                print(
+                    f"{facing} passage: cleared {cleared}, glazed {glazed} "
+                    f"block(s) from the dome shell out to the door",
+                    file=sys.stderr,
+                )
+
+        lower, upper = door_state(facing)
+        replacements.append((door_pos, lower))
+        replacements.append((upper_pos, upper))
+        doors.append((door_pos, facing))
+
+    save_structure(src, args.dst, size, replacements=replacements)
+    for pos, facing in doors:
+        print(f"door {facing}: {pos}")
+
+
+if __name__ == "__main__":
+    main()

structura_geo-0.1.0/src/structura_geo/droplet.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+import numpy as np
+from scipy import ndimage
+
+from .fields import NO_CEILING as NO_LID, patch_noise
+
+
+SAG = 4.0
+SIGMA = 3.0
+THRESHOLD = 0.25
+WOBBLE = 0.30
+CELL = 9
+SALT = 7
+HANG = 0.35
+SPREAD = 1.3
+LEAN = 0.6
+
+
+def lateral_reach(thickness, spread=SPREAD, sigma=SIGMA):
+    return int(np.ceil(thickness * spread + 3.0 * sigma))
+
+
+def vertical_reach(inradius, hang=HANG, sigma=SIGMA):
+    return int(np.ceil(hang * inradius + 6.0 * sigma)) + 8
+
+
+def sag_kernel(length):
+    reach = max(1, int(4 * length))
+    weights = np.exp(-np.arange(reach) / max(length, 1e-6))
+    return np.concatenate([weights[::-1], np.zeros(reach - 1)]) / weights.max()
+
+
+def ground_lid(solid, interior_air):
+    height = solid.shape[1]
+    roofed = np.where(
+        interior_air.any(axis=1), np.argmax(interior_air, axis=1), NO_LID,
+    )
+    rows = np.arange(height)[None, :, None]
+    ground = solid & ((roofed[:, None, :] == NO_LID) | (rows < roofed[:, None, :]))
+    top = np.where(
+        ground.any(axis=1), height - 1 - np.argmax(ground[:, ::-1, :], axis=1), -1,
+    )
+    known = top >= 0
+    if not known.any():
+        return np.full(top.shape, NO_LID)
+    _, nearest = ndimage.distance_transform_edt(~known, return_indices=True)
+    return np.where(known, top, top[nearest[0], nearest[1]])
+
+
+def downhill(solid):
+    footprint = solid.any(axis=1)
+    if footprint.sum() < 16:
+        return None
+    top = np.where(
+        footprint, solid.shape[1] - 1 - np.argmax(solid[:, ::-1, :], axis=1), np.nan,
+    ).astype(np.float64)
+    filled = np.nan_to_num(top, nan=float(np.nanmean(top)))
+    smoothed = ndimage.gaussian_filter(filled, 6.0)
+    gradient_x, gradient_z = np.gradient(smoothed)
+    vector = np.array([gradient_x[footprint].mean(), gradient_z[footprint].mean()])
+    length = float(np.hypot(*vector))
+    if length < 1e-3:
+        return None
+    return -vector / length
+
+
+def flow_target(solid, hang, spread, lean=0.0):
+    footprint = solid.any(axis=1)
+    if not footprint.any() or (hang <= 0 and spread <= 0):
+        return np.zeros_like(solid)
+    height = solid.shape[1]
+    rows = np.arange(height)[None, :, None]
+    floor = np.where(footprint, np.argmax(solid, axis=1), 0)
+    reach = ndimage.distance_transform_edt(footprint)
+    if lean > 0:
+        direction = downhill(solid)
+        if direction is not None:
+            rows_xz, cols_xz = np.indices(footprint.shape)
+            centred_x = rows_xz - rows_xz[footprint].mean()
+            centred_z = cols_xz - cols_xz[footprint].mean()
+            along = centred_x * direction[0] + centred_z * direction[1]
+            extent = max(float(np.abs(along[footprint]).max()), 1.0)
+            reach = reach * (1.0 + lean * along / extent)
+            reach = np.maximum(reach, 0.0)
+    sunk = np.maximum(floor - hang * reach, 0.0)
+    target = (rows >= sunk[:, None, :]) & (rows < floor[:, None, :]) & footprint[:, None, :]
+    if spread > 0:
+        thickness = solid.sum(axis=1).astype(np.float64)
+        top = np.where(footprint, height - 1 - np.argmax(solid[:, ::-1, :], axis=1), 0)
+        outward, source = ndimage.distance_transform_edt(
+            ~footprint, return_indices=True,
+        )
+        near = (source[0], source[1])
+        run = np.maximum(thickness[near] * spread, 1e-6)
+        taper = np.clip(1.0 - outward / run, 0.0, 1.0)
+        crest = top[near].astype(np.float64)
+        base = sunk[near]
+        lip = crest - (crest - base) * 0.5
+        apron = (
+            ~footprint[:, None, :]
+            & (taper[:, None, :] > 0)
+            & (rows <= (lip * taper + base * (1 - taper))[:, None, :])
+            & (rows >= (base - hang * 0.0)[:, None, :])
+        )
+        target |= apron
+    return target
+
+
+def droplet(solid, interior_air, reserved, sag=SAG, sigma=SIGMA,
+            threshold=THRESHOLD, wobble=WOBBLE, cell=CELL, salt=SALT,
+            hang=HANG, spread=SPREAD, lean=LEAN):
+    shape = solid | flow_target(solid, hang, spread, lean)
+    field = ndimage.convolve1d(
+        shape.astype(np.float32), sag_kernel(sag), axis=1, mode="constant",
+    )
+    field = ndimage.gaussian_filter(field, sigma)
+    field /= float(sag_kernel(sag).sum())
+    if wobble > 0:
+        corner = np.argwhere(solid.any(axis=1))
+        anchor = -corner.min(axis=0) if len(corner) else (0, 0)
+        noise = patch_noise(
+            (solid.shape[0], solid.shape[2]), cell, salt, origin=anchor,
+        ) - 0.5
+        field *= (1.0 + wobble * noise).astype(np.float32)[:, None, :]
+    blob = field >= threshold
+    rows = np.arange(solid.shape[1])[None, :, None]
+    lid = ground_lid(solid, interior_air)
+    blob &= rows <= lid[:, None, :]
+    added = blob & ~solid & ~reserved
+    sealed = ndimage.binary_fill_holes(solid | added) & ~solid & ~reserved
+    sealed &= rows <= lid[:, None, :]
+    added = added | sealed
+    body = solid | added
+    labels, count = ndimage.label(body)
+    if count > 1:
+        keep = 1 + int(np.argmax(ndimage.sum(body, labels, range(1, count + 1))))
+        added &= labels == keep
+    return added
+
+
+def droplet_for_budget(solid, interior_air, reserved, budget=0.4, steps=9,
+                       low=0.02, high=0.95, **kwargs):
+    if "threshold" in kwargs:
+        raise TypeError(
+            "droplet_for_budget solves for the threshold; passing one asks it "
+            "to hit a budget and use a fixed isolevel at the same time. Call "
+            "droplet() directly if the isolevel is what you want to set.",
+        )
+    mass = max(int(solid.sum()), 1)
+    best = None
+    for _ in range(steps):
+        middle = (low + high) / 2.0
+        candidate = droplet(solid, interior_air, reserved, threshold=middle, **kwargs)
+        if candidate.sum() / mass > budget:
+            low = middle
+        else:
+            high = middle
+            if best is None or candidate.sum() > best.sum():
+                best = candidate
+    if best is None:
+        best = np.zeros_like(solid)
+    return best