pyramids-citymodels 0.2.0__py3-none-any.whl

pyramids_citymodels/__init__.py

@@ -0,0 +1,54 @@
+"""3D city-model file-format drivers for the pyramids stack.
+
+`pyramids-citymodels` reads and writes the file formats of semantic 3D city models —
+CityGML, CityJSON and the related interchange formats — as `pyramids` objects.
+`pyramids-core` owns the GIS data model (the raster `Dataset`, the vector
+`FeatureCollection`, the datacube), its GDAL/OGR-backed I/O, and every operation that
+follows once features are in hand — reprojection, overlays, spatial joins, conversion
+and spatial indexing. What it does not do is open the city-model exchange formats;
+that is this package's job, and its only job.
+
+Drivers are discovered by `pyramids-core` through the `pyramids.vector_drivers`
+entry-point group (the group `FeatureCollection.read_file` consults — city models are
+vector features), so a read of a city-model file resolves to a driver here once this
+package is installed. A dependency-backed driver names its optional dependency via a
+`VectorDriver.extra` attribute and is skipped silently at discovery when that package
+is not importable. See ADR-0003 for the scope decision.
+
+The package root deliberately re-exports nothing: it carries `__version__` and the
+import contract that activates the vendored osgeo bindings, and that is all. Installing
+the package is the whole integration, so nothing here needs importing. A driver class is
+still reachable by its module path for the rare case of wanting one directly.
+
+Examples:
+    - The root carries the installed version and nothing else. `__all__` is empty
+      because there is deliberately nothing to re-export:
+
+        >>> import pyramids_citymodels
+        >>> pyramids_citymodels.__version__.split(".")[0].isdigit()
+        True
+        >>> pyramids_citymodels.__all__
+        []
+"""
+
+# Import pyramids FIRST — before anything else, and keep it first. pyramids-core
+# bundles GDAL's osgeo SWIG bindings and native libs inside its platform wheel
+# and activates them on import (puts `_vendor/osgeo` on sys.path, sets
+# GDAL_DATA / PROJ_DATA, registers the Windows DLL directory). Any module here
+# that does `from osgeo import gdal` at load time needs this line to have run
+# first, or that import fails wherever no separate GDAL is installed.
+import pyramids  # noqa: F401  # isort:skip  (keep first — see above; ruff must not reorder it)
+
+from importlib.metadata import PackageNotFoundError, version
+
+# The distribution name, not `__name__`: the import name is `pyramids_citymodels`
+# and the distribution is `pyramids-citymodels`. importlib.metadata normalizes `_`
+# to `-` so either spelling resolves today, but the metadata lookup is a
+# distribution lookup — spell it the way the metadata does.
+try:
+    __version__ = version("pyramids-citymodels")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+
+
+__all__: list[str] = []

pyramids_citymodels/drivers/__init__.py

@@ -0,0 +1,13 @@
+"""Format drivers, one module per city-model format family.
+
+Grouped by format family rather than by file suffix, because related encodings of one
+standard share a parser (CityGML and its CityJSON sibling, for instance).
+
+Each driver is a ``VectorDriver`` class registered into the ``pyramids.vector_drivers``
+entry-point group. Keep this subpackage -- and each driver module -- light at import:
+pyramids reads a driver's claims as class attributes without constructing it, so a driver's
+heavy backend belongs inside its ``read`` method, not at module top, and the optional
+dependency is named by the driver's ``extra`` attribute (the registry skips the driver
+silently at discovery when that package is absent). An eager backend import here would
+break the whole package import instead.
+"""

pyramids_citymodels/drivers/citygml.py

@@ -0,0 +1,84 @@
+"""The CityGML vector driver (issue #11).
+
+Registered into the ``pyramids.vector_drivers`` entry-point group, this driver is what
+``FeatureCollection.read_file`` dispatches a CityGML read into. Like the CityJSON driver it
+follows the class-attribute contract — claims are class attributes, :meth:`can_open` is a
+classmethod — so discovery reads the class without importing the parser or shapely/geopandas;
+those load only inside :meth:`read`.
+
+``.gml`` / ``.xml`` are shared with plenty of non-CityGML data, so :meth:`can_open` sniffs for a
+CityGML namespace or a ``CityModel`` element rather than trusting the suffix.
+"""
+
+import pyramids  # noqa: F401  # isort:skip  (keep first — activates vendored osgeo; see __init__)
+
+from typing import Any
+
+
+class CityGmlDriver:
+    """Read CityGML LOD2 (``.gml`` / ``.xml`` / ``.citygml``) as a ``FeatureCollection``."""
+
+    name = "citygml"
+    long_name = "CityGML (3D city model, LOD2 semantic surfaces)"
+    api_version = 1
+    suffixes = (".gml", ".citygml", ".xml")
+    schemes: tuple[str, ...] = ()
+    capabilities = frozenset({"read"})
+    #: Parsing uses only the standard-library ``xml.etree.ElementTree``, so there is no backend.
+    extra: str | None = None
+
+    @classmethod
+    def can_open(cls, source: Any) -> bool:
+        """Return ``True`` only when ``source`` looks like CityGML (namespace / ``CityModel``).
+
+        Examples:
+            - A CityGML-namespaced document is claimed; plain XML is declined:
+                ```python
+                >>> CityGmlDriver.can_open('<core:CityModel xmlns:core="http://www.opengis.net/citygml/2.0"/>')
+                True
+                >>> CityGmlDriver.can_open("<root/>")
+                False
+
+                ```
+        """
+        from pyramids_citymodels.readers.citygml import looks_like_citygml
+
+        return looks_like_citygml(source)
+
+    def read(self, source: Any, **kwargs: Any) -> Any:
+        """Parse ``source``'s LOD2 buildings into a :class:`pyramids.feature.FeatureCollection`.
+
+        Keyword Args:
+            strategy: ``"footprint"`` or ``"semantic_surfaces"`` (default).
+            lod: Level of detail to select; ``None`` takes the highest present.
+            geometry_dimension: ``"xyz"`` (default) keeps Z, ``"xy"`` drops it.
+            child_inherits_parent_attributes: Whether child rows carry parent attributes.
+
+        Examples:
+            - Read an in-memory CityGML building into a FeatureCollection:
+                ```python
+                >>> xml = '''<core:CityModel
+                ...   xmlns:core="http://www.opengis.net/citygml/2.0"
+                ...   xmlns:bldg="http://www.opengis.net/citygml/building/2.0"
+                ...   xmlns:gml="http://www.opengis.net/gml">
+                ...   <core:cityObjectMember><bldg:Building gml:id="B">
+                ...     <bldg:boundedBy><bldg:RoofSurface>
+                ...       <bldg:lod2MultiSurface><gml:MultiSurface><gml:surfaceMember>
+                ...         <gml:Polygon><gml:exterior><gml:LinearRing>
+                ...           <gml:posList srsDimension="3">0 0 1 1 0 1 1 1 1</gml:posList>
+                ...         </gml:LinearRing></gml:exterior></gml:Polygon>
+                ...       </gml:surfaceMember></gml:MultiSurface></bldg:lod2MultiSurface>
+                ...     </bldg:RoofSurface></bldg:boundedBy>
+                ...   </bldg:Building></core:cityObjectMember>
+                ... </core:CityModel>'''
+                >>> frame = CityGmlDriver().read(xml)
+                >>> frame["surface_type"].iloc[0]
+                'RoofSurface'
+
+                ```
+        """
+        from pyramids_citymodels.flatten import to_feature_collection
+        from pyramids_citymodels.readers.citygml import parse_citygml
+
+        model = parse_citygml(source)
+        return to_feature_collection(model, **kwargs)

pyramids_citymodels/drivers/cityjson.py

@@ -0,0 +1,80 @@
+"""The CityJSON vector driver (issue #11).
+
+Registered into the ``pyramids.vector_drivers`` entry-point group, this driver is what
+``FeatureCollection.read_file`` dispatches a CityJSON read into. It follows the class-attribute
+contract pyramids' driver registry reads without constructing the driver: the claims
+(``name``/``long_name``/``suffixes``/…) are class attributes and :meth:`can_open` is a
+classmethod, so discovery never imports the parser or shapely/geopandas — those load only inside
+:meth:`read`, when a read is actually dispatched here.
+
+The ``.json`` suffix is shared with GeoJSON, so a suffix alone cannot be trusted: :meth:`can_open`
+**content-sniffs** ``"type": "CityJSON"`` to claim a file, which cleanly separates CityJSON from a
+GeoJSON ``FeatureCollection`` (decision #3 in the ecosystem report).
+"""
+
+import pyramids  # noqa: F401  # isort:skip  (keep first — activates vendored osgeo; see __init__)
+
+from typing import Any
+
+
+class CityJsonDriver:
+    """Read CityJSON (``.city.json`` / ``.json`` / ``.cityjson``) as a ``FeatureCollection``."""
+
+    name = "cityjson"
+    long_name = "CityJSON (3D city model)"
+    api_version = 1
+    suffixes = (".city.json", ".cityjson", ".json")
+    schemes: tuple[str, ...] = ()
+    capabilities = frozenset({"read"})
+    #: Parsing uses only the standard-library ``json`` module, so there is no optional backend.
+    extra: str | None = None
+
+    @classmethod
+    def can_open(cls, source: Any) -> bool:
+        """Return ``True`` only when ``source`` is a CityJSON document.
+
+        Content-sniffs ``"type": "CityJSON"`` rather than trusting the ``.json`` suffix, so a
+        GeoJSON file sharing that suffix is declined. Never raises.
+
+        Examples:
+            - CityJSON is claimed; GeoJSON sharing the ``.json`` suffix is declined:
+                ```python
+                >>> CityJsonDriver.can_open('{"type": "CityJSON", "CityObjects": {}, "vertices": []}')
+                True
+                >>> CityJsonDriver.can_open('{"type": "FeatureCollection", "features": []}')
+                False
+
+                ```
+        """
+        from pyramids_citymodels.readers.cityjson import looks_like_cityjson
+
+        return looks_like_cityjson(source)
+
+    def read(self, source: Any, **kwargs: Any) -> Any:
+        """Parse ``source`` and flatten it into a :class:`pyramids.feature.FeatureCollection`.
+
+        Keyword Args:
+            strategy: ``"footprint"`` or ``"semantic_surfaces"`` (default).
+            lod: Level of detail to select; ``None`` takes the highest present.
+            geometry_dimension: ``"xyz"`` (default) keeps Z, ``"xy"`` drops it.
+            child_inherits_parent_attributes: Whether child rows carry parent attributes.
+
+        Examples:
+            - Read an in-memory CityJSON document into a FeatureCollection:
+                ```python
+                >>> doc = {
+                ...     "type": "CityJSON", "version": "2.0",
+                ...     "CityObjects": {"b": {"type": "Building", "geometry": [
+                ...         {"type": "MultiSurface", "lod": "2", "boundaries": [[[0, 1, 2]]]}]}},
+                ...     "vertices": [[0, 0, 0], [1, 0, 0], [1, 1, 0]]}
+                >>> frame = CityJsonDriver().read(doc)
+                >>> len(frame)
+                1
+
+                ```
+        """
+        from pyramids_citymodels.flatten import to_feature_collection
+        from pyramids_citymodels.readers.cityjson import parse_cityjson
+
+        model = parse_cityjson(source)
+        return to_feature_collection(model, **kwargs)

pyramids_citymodels/flatten.py

@@ -0,0 +1,290 @@
+"""Flatten the IR into a ``FeatureCollection`` row model (issue #8).
+
+The 3D, hierarchical city model becomes a flat feature table using the pattern 3DCityDB and the
+QGIS Loader both converge on: **one flat table, a ``surface_type`` discriminator column and a
+``parent_id`` foreign key**, with object attributes passed through. That single shape serves both
+load strategies (:class:`~pyramids_citymodels.options.LoadStrategy`):
+
+- ``semantic_surfaces`` — one row per boundary surface, carrying ``surface_type`` (RoofSurface,
+  WallSurface, …), the owning object's id/type, its ``parent_id`` and its attributes.
+- ``footprint`` — one row per city object, geometry = the 2D union of its ground surfaces (or,
+  when a model tags no ground, the 2D union of all its surfaces).
+
+Z is kept or dropped per :class:`~pyramids_citymodels.options.GeometryDimension` (a footprint is
+always 2D). Identical polygons within one object are de-duplicated, which collapses the common
+XLink case where one polygon is referenced by both a semantic surface and a solid shell.
+
+**Surface geometries are planar polygons in 3D (2.5D).** A building's *vertical* surface — a wall —
+is a real polygon in 3D space whose projection onto the XY plane is a straight line. Shapely
+measures validity and area on that XY footprint only, so a wall row is deliberately **non-areal**:
+``is_valid`` is ``False`` and ``area`` is ``0`` for it, while roofs and ground (near-horizontal) are
+valid with positive area. This is the documented ``semantic_surfaces`` contract, not a defect —
+operate on the surfaces in 3D (the Z is preserved in ``xyz`` mode), and treat 2D-areal operations
+(overlay, area, ``to_file`` of a 2D driver) as meaningful only for the horizontal surfaces or for a
+``footprint`` load. The footprint load, being a plan projection, excludes these non-areal surfaces.
+
+The result is a :class:`pyramids.feature.FeatureCollection` — a GeoDataFrame subclass — so it
+flows straight into the rest of the pyramids stack; this module builds no GIS of its own.
+"""
+
+import pyramids  # noqa: F401  # isort:skip  (keep first — activates vendored osgeo; see __init__)
+
+from typing import Any
+
+import geopandas as gpd
+from pyramids.feature import FeatureCollection
+from shapely.geometry import MultiPolygon, Polygon
+from shapely.ops import unary_union
+
+from pyramids_citymodels.ir import (
+    CityModel,
+    CityObject,
+    Geometry,
+    iter_surfaces,
+    normalize_lod,
+)
+from pyramids_citymodels.options import GeometryDimension, LoadStrategy, ReadOptions
+
+__all__ = ["to_feature_collection"]
+
+
+def _ring_coordinates(ring: list[Any], keep_z: bool) -> list[tuple[float, ...]]:
+    """Coerce a ring's coordinates to 2D or 3D tuples."""
+    if keep_z:
+        return [
+            (coord[0], coord[1], coord[2])
+            if len(coord) >= 3
+            else (coord[0], coord[1], 0.0)
+            for coord in ring
+        ]
+    return [(coord[0], coord[1]) for coord in ring]
+
+
+def _polygon(surface: list[Any], keep_z: bool) -> Polygon | None:
+    """Build a shapely :class:`Polygon` from a surface (exterior ring first, then holes)."""
+    rings = [ring for ring in surface if ring]
+    if not rings:
+        return None
+    exterior = _ring_coordinates(rings[0], keep_z)
+    if len(exterior) < 3:
+        return None
+    holes = [_ring_coordinates(ring, keep_z) for ring in rings[1:] if len(ring) >= 3]
+    return Polygon(exterior, holes)
+
+
+def _select_geometries(geometries: list[Geometry], lod: str | None) -> list[Geometry]:
+    """Pick the geometries to flatten: those matching ``lod``, else the highest LOD present."""
+    if not geometries:
+        return []
+    if lod is not None:
+        wanted = normalize_lod(lod)
+        selected = [g for g in geometries if normalize_lod(g.lod) == wanted]
+        if selected:
+            return selected
+        return []
+
+    def lod_value(geometry: Geometry) -> float:
+        normalized = normalize_lod(geometry.lod)
+        try:
+            return float(normalized) if normalized is not None else -1.0
+        except ValueError:
+            return -1.0
+
+    highest = max((lod_value(g) for g in geometries), default=-1.0)
+    return [g for g in geometries if lod_value(g) == highest]
+
+
+def _ring_key(coords: Any) -> tuple:
+    """A hashable, rounded key for a single ring's coordinates (closing point dropped)."""
+    return tuple(round(component, 6) for point in coords[:-1] for component in point)
+
+
+def _polygon_key(polygon: Polygon) -> tuple:
+    """A hashable key for de-duplicating identical polygons.
+
+    Covers the exterior ring **and every interior ring (hole)**, so two surfaces that share an
+    exterior boundary but differ in their holes do not collide and get one wrongly dropped (SF4).
+    """
+    return (
+        _ring_key(polygon.exterior.coords),
+        tuple(_ring_key(interior.coords) for interior in polygon.interiors),
+    )
+
+
+def _attributes_for(
+    city_object: CityObject, model: CityModel, options: ReadOptions
+) -> dict[str, Any]:
+    """The attribute dict for an object's rows, optionally inheriting its parent's attributes."""
+    attributes: dict[str, Any] = {}
+    if options.child_inherits_parent_attributes:
+        parent_id = city_object.parent
+        parent = model.objects.get(parent_id) if parent_id else None
+        if parent is not None:
+            attributes.update(parent.attributes)
+    attributes.update(city_object.attributes)
+    return attributes
+
+
+def _semantic_surface_rows(
+    city_object: CityObject,
+    geometries: list[Geometry],
+    model: CityModel,
+    options: ReadOptions,
+) -> list[dict[str, Any]]:
+    """One row per boundary surface, with its ``surface_type`` and owner metadata."""
+    keep_z = options.geometry_dimension is GeometryDimension.XYZ
+    base_attributes = _attributes_for(city_object, model, options)
+    rows: list[dict[str, Any]] = []
+    seen: set[tuple] = set()
+    for geometry in geometries:
+        surface_index = 0
+        for surface, semantic_value in iter_surfaces(
+            geometry.boundaries, geometry.semantic_values
+        ):
+            polygon = _polygon(surface, keep_z)
+            if polygon is None:
+                continue
+            key = _polygon_key(polygon)
+            if key in seen:
+                continue
+            seen.add(key)
+            semantic = geometry.semantic_for(semantic_value)
+            rows.append(
+                {
+                    **base_attributes,
+                    "city_object_id": city_object.id,
+                    "city_object_type": city_object.type,
+                    "parent_id": city_object.parent,
+                    "lod": geometry.lod,
+                    "surface_type": semantic.type if semantic is not None else None,
+                    "surface_index": surface_index,
+                    "geometry": polygon,
+                }
+            )
+            surface_index += 1
+    return rows
+
+
+def _footprint_row(
+    city_object: CityObject,
+    geometries: list[Geometry],
+    model: CityModel,
+    options: ReadOptions,
+) -> dict[str, Any] | None:
+    """One 2D row per object: the union of its ground surfaces, else of all its surfaces."""
+    ground: list[Polygon] = []
+    everything: list[Polygon] = []
+    for geometry in geometries:
+        for surface, semantic_value in iter_surfaces(
+            geometry.boundaries, geometry.semantic_values
+        ):
+            polygon = _polygon(surface, keep_z=False)
+            if polygon is None or polygon.area == 0.0:
+                # A footprint is a plan projection; a non-areal surface (a vertical wall
+                # projects to a line, area 0) is not part of it and would only pollute the
+                # union with degenerate, invalid geometry (SF1).
+                continue
+            everything.append(polygon)
+            semantic = geometry.semantic_for(semantic_value)
+            if semantic is not None and semantic.type == "GroundSurface":
+                ground.append(polygon)
+    polygons = ground or everything
+    if not polygons:
+        return None
+    merged = unary_union(polygons)
+    if merged.is_empty:
+        return None
+    if merged.geom_type == "Polygon":
+        geometry_value: Any = merged
+    elif merged.geom_type == "MultiPolygon":
+        geometry_value = merged
+    else:
+        # A union that collapses to lines/points is not a usable footprint; wrap what polygons
+        # we have instead of returning a degenerate geometry.
+        geometry_value = MultiPolygon([p for p in polygons if p.geom_type == "Polygon"])
+    lods = sorted({g.lod for g in geometries if g.lod is not None})
+    return {
+        **_attributes_for(city_object, model, options),
+        "city_object_id": city_object.id,
+        "city_object_type": city_object.type,
+        "parent_id": city_object.parent,
+        "lod": lods[-1] if lods else None,
+        "geometry": geometry_value,
+    }
+
+
+def to_feature_collection(
+    model: CityModel,
+    *,
+    strategy: "str | LoadStrategy" = LoadStrategy.SEMANTIC_SURFACES,
+    lod: Any = None,
+    geometry_dimension: "str | GeometryDimension" = GeometryDimension.XYZ,
+    child_inherits_parent_attributes: bool = False,
+) -> FeatureCollection:
+    """Flatten a :class:`~pyramids_citymodels.ir.CityModel` into a ``FeatureCollection``.
+
+    Args:
+        model: The parsed city model.
+        strategy: ``"footprint"`` (one row per object) or ``"semantic_surfaces"`` (one row per
+            boundary surface). Accepts a :class:`~pyramids_citymodels.options.LoadStrategy`.
+        lod: Level of detail to select; ``None`` takes the highest each object offers. An explicit
+            ``lod`` that no object carries selects nothing and yields an **empty** FeatureCollection
+            (no error) — pass ``None`` to always get the best available.
+        geometry_dimension: ``"xyz"`` keeps Z, ``"xy"`` drops it. Ignored for ``footprint``.
+        child_inherits_parent_attributes: When ``True``, child rows also carry parent attributes.
+
+    Note:
+        The structural columns ``city_object_id``, ``city_object_type``, ``parent_id``, ``lod``,
+        ``surface_type`` and ``surface_index`` take precedence: a city-object attribute that happens
+        to share one of these names is overwritten by the structural value in the output table.
+
+        A ``footprint`` load omits an object whose surfaces are **all non-areal** (e.g. a wall-only
+        object): it has no plan-view area, so it contributes no row. This is omission by design, not
+        data loss — use ``semantic_surfaces`` to keep every surface.
+
+    Returns:
+        A :class:`pyramids.feature.FeatureCollection` in the model's CRS, with a stable column
+        order; empty (but still a valid FeatureCollection) when the model has no usable geometry.
+
+    Examples:
+        - Flatten a one-building model into one row per semantic surface and read it back:
+            ```python
+            >>> from pyramids_citymodels.readers.cityjson import parse_cityjson
+            >>> doc = {
+            ...     "type": "CityJSON", "version": "2.0",
+            ...     "CityObjects": {"b": {"type": "Building", "geometry": [
+            ...         {"type": "MultiSurface", "lod": "2", "boundaries": [[[0, 1, 2]]],
+            ...          "semantics": {"surfaces": [{"type": "RoofSurface"}], "values": [0]}}]}},
+            ...     "vertices": [[0, 0, 0], [1, 0, 0], [1, 1, 0]]}
+            >>> frame = to_feature_collection(parse_cityjson(doc), strategy="semantic_surfaces")
+            >>> len(frame)
+            1
+            >>> frame["surface_type"].iloc[0]
+            'RoofSurface'
+
+            ```
+    """
+    options = ReadOptions.coerce(
+        strategy=strategy,
+        lod=lod,
+        geometry_dimension=geometry_dimension,
+        child_inherits_parent_attributes=child_inherits_parent_attributes,
+    )
+
+    rows: list[dict[str, Any]] = []
+    for city_object in model.objects.values():
+        geometries = _select_geometries(city_object.geometries, options.lod)
+        if not geometries:
+            continue
+        if options.strategy is LoadStrategy.SEMANTIC_SURFACES:
+            rows.extend(_semantic_surface_rows(city_object, geometries, model, options))
+        else:
+            row = _footprint_row(city_object, geometries, model, options)
+            if row is not None:
+                rows.append(row)
+
+    if rows:
+        frame = gpd.GeoDataFrame(rows, geometry="geometry", crs=model.crs)
+    else:
+        frame = gpd.GeoDataFrame({"geometry": []}, geometry="geometry", crs=model.crs)
+    return FeatureCollection(frame)