9 min read1,989 words

Ingesting As-Built CAD Deliverables into a Utility Network

An as-built drawing is the most authoritative record of what was actually built and the least structured data a utility network ever ingests. It carries layer names instead of asset types, blocks instead of devices, annotation instead of attributes, and a coordinate frame that is often stated only in the title block. Importing it directly produces geometry that draws correctly and traces not at all. This guide sets out the crosswalk-driven ingestion that turns a deliverable into network features: frame and units first, layers mapped to asset types through versioned configuration, block attributes coerced into domains, and two gates that stop an unmapped layer from arriving as an untraceable asset. It applies the pipeline discipline from data ingestion pipelines for utility assets to the specific case of contractor drawings.

Environment Prerequisites

  • Python 3.11 with geopandas>=1.0, shapely>=2.0 and fiona>=1.9 for DXF reading, plus arcpy where features are created directly in an enterprise geodatabase.
  • A versioned layer crosswalk mapping each expected CAD layer to an asset group and asset type, held in the repository beside the connectivity rules.
  • A block-attribute map translating block attribute tags into feature fields and coded values.
  • The submission standard the contractor is working to, including the required frame, units, layer naming and whether blocks must be exploded.
  • A defined tolerance for geometry cleaning, taken from the precision standards rather than chosen per deliverable.
  • A named version for the created features and a rejection route back to the submitter.

Schema-Aware Validation Protocol — Run Before Reading Geometry

  1. Confirm the units and the frame are declared, not inferred. A drawing authored in survey feet and read as metres produces a uniform scale error that looks like a plausible network.
  2. Diff the layer list against the crosswalk. Any layer present in the drawing and absent from the crosswalk stops the run. Importing it as “unknown” creates assets that no rule governs.
  3. Check whether blocks are exploded. An unexploded block imports as a single feature holding several devices, and the error is invisible until a trace refuses to enter it.
  4. Look for elevation carried as text. Where the vertical model matters, annotation is not a Z value, and the deliverable needs returning rather than interpreting.
  5. Count entities per layer against the drawing’s own schedule. A mismatch means the drawing and its schedule disagree, which is a question for the submitter and not something the importer should resolve.

Minimal Reproducible Implementation

from __future__ import annotations

import logging
from dataclasses import dataclass, field

import geopandas as gpd

logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
LOG = logging.getLogger("cad-ingest")


@dataclass
class IngestReport:
    accepted: int = 0
    rejected: list[str] = field(default_factory=list)
    unmapped_layers: set[str] = field(default_factory=set)
    features: gpd.GeoDataFrame | None = None

    @property
    def ok(self) -> bool:
        return not self.rejected and not self.unmapped_layers


def ingest_deliverable(
    dxf_path: str,
    crosswalk: dict[str, dict],
    block_attrs: dict[str, str],
    target_epsg: int,
    source_units: str,
    tolerance_m: float = 0.02,
) -> IngestReport:
    """Read a CAD deliverable into typed network-ready features.

    ``crosswalk`` maps a layer name to {"asset_group", "asset_type", "geometry"}.
    ``source_units`` must be stated by the submission rather than guessed; the function
    refuses to proceed on an unknown unit because the alternative is a silent scale error.
    """
    report = IngestReport()

    if source_units not in {"m", "us-ft", "ft"}:
        report.rejected.append(f"unsupported or unstated source units: {source_units!r}")
        return report

    gdf = gpd.read_file(dxf_path)
    present = set(gdf["Layer"].unique())
    report.unmapped_layers = present - set(crosswalk)
    if report.unmapped_layers:
        LOG.error("unmapped layer(s): %s", ", ".join(sorted(report.unmapped_layers)))
        return report

    scale = {"m": 1.0, "ft": 0.3048, "us-ft": 1200.0 / 3937.0}[source_units]
    if scale != 1.0:
        gdf["geometry"] = gdf.geometry.scale(xfact=scale, yfact=scale, origin=(0, 0))
    gdf = gdf.set_crs(epsg=target_epsg, allow_override=True)

    rows = []
    for _, ent in gdf.iterrows():
        spec = crosswalk[str(ent["Layer"])]
        geom_kind = ent.geometry.geom_type if ent.geometry is not None else None
        if geom_kind is None or ent.geometry.is_empty:
            report.rejected.append(f"empty geometry on layer {ent['Layer']}")
            continue
        if spec["geometry"] not in geom_kind:
            report.rejected.append(
                f"layer {ent['Layer']} expects {spec['geometry']}, found {geom_kind}")
            continue

        row = {
            "asset_group": spec["asset_group"],
            "asset_type": spec["asset_type"],
            "geometry": ent.geometry.simplify(tolerance_m, preserve_topology=True),
        }
        for tag, field_name in block_attrs.items():
            if tag in ent and ent[tag] is not None:
                row[field_name] = ent[tag]
        rows.append(row)

    report.features = gpd.GeoDataFrame(rows, crs=f"EPSG:{target_epsg}")
    report.accepted = len(rows)
    LOG.info("accepted %d feature(s), rejected %d", report.accepted, len(report.rejected))
    return report
An as-built drawing becoming network features, with the two gates that stop it A CAD deliverable arrives as geometry with layer names and block attributes, none of which the network understands. Units and frame are settled first, then layers are mapped to asset types through a versioned crosswalk, then blocks and their attributes become feature attributes. Geometry is cleaned to tolerance, and only then are features created inside a version. A layer with no mapping and a block with no asset type both stop the run rather than importing as something plausible. FRAME + UNITS declared, not assumed LAYER MAP layer → asset type versioned crosswalk ATTRIBUTES block attributes to domains CLEAN tolerance repair dedupe vertices CREATE features in a named version no crosswalk entry UNMAPPED LAYER stops the run — importing it as "unknown" produces an asset nobody can trace Two gates, both cheap, both placed before any geometry is written.

The unit check refusing to guess is the most important line in the routine. Every other defect in a CAD deliverable produces something visibly wrong; a unit error produces a network that is internally consistent, correctly shaped, and uniformly the wrong size.

The four things a CAD deliverable reliably gets wrong, and what each costs Drawings are produced for construction, not for a network model, and four habits follow from that. Each is harmless on paper and consequential once the geometry becomes topology. Habit Why it happens Cost in the network Units unstated the drawing knows a clean 3.28× scale error Blocks not exploded symbols are blocks devices arrive as one feature Lines split at symbols drafting convention a main becomes fifty edges Elevation as text annotation, not attribute no Z, no vertical model All four are correct practice for a drawing and wrong for a network.

Revisions, and Why They Decide the Design

A drawing is submitted, reviewed, corrected and resubmitted, often several times, and the second submission is where a naive importer breaks. The features created from revision one are already in the network, possibly already connected to existing infrastructure; revision two arrives as a complete drawing rather than as a delta, and importing it again duplicates everything.

Two properties make revisions manageable. The deliverable needs a stable identifier per entity that survives the revision — usually a handle or a tag the drafting standard requires — so the importer can match revision two against what revision one created. And the import has to be idempotent: an entity whose geometry and attributes are unchanged produces no edit, one that changed produces an update, and one that has disappeared produces a review item rather than a deletion, because a missing entity in a drawing is ambiguous in exactly the way a missing record in a data feed is.

Where the drafting standard cannot provide stable identifiers, the fallback is spatial matching inside a tight tolerance, with anything ambiguous routed to review. It works, and it is noticeably worse — which is the argument for putting the identifier requirement into the submission standard rather than solving it in code.

Production Deployment Pattern

  1. Run ingestion as a gate in the submission workflow, so a deliverable is accepted or returned before anyone schedules the work that depends on it.
  2. Return defects with entity identifiers. “Layer WTR_VLV_NEW is not in the crosswalk, 14 entities” is actionable; “import failed” is not.
  3. Never repair locally what the submitter can fix. A local repair has to be repeated for every revision of the same drawing, and revisions are the norm.
  4. Version the crosswalk with the submission standard. When the standard changes, the crosswalk change is the reviewable artefact that records it.
  5. Create features in a named version and validate topology before posting, because as-built geometry frequently connects to existing infrastructure and the connection is the point.
  6. Persist the run. The deliverable hash, the crosswalk version, units, tolerance and counts are what explain, years later, how a feature came to be shaped the way it is.
What to do with a deliverable that fails its checks A deliverable that fails is returned rather than repaired locally, because a repair made in the pipeline has to be made again for every future revision of the same drawing. The exception is a defect the contractor cannot fix — a convention agreed years ago — which belongs in the crosswalk as a documented mapping rather than as a silent fix in code. The deliverable fails a check the contractor can fix it Return with the specific defect how Cite the standard and the failing entity ids why not Repairing locally means repairing every revision it is an agreed convention Add it to the crosswalk good Documented mapping, reviewable, versioned bad Not a special case buried in the importer Every local repair is a repair you will make again next revision.

Conclusion

CAD ingestion works when the translation between drawing conventions and network semantics lives in versioned configuration rather than in the importer’s assumptions. Settling units and frame first removes the one defect that is invisible afterwards; gating on unmapped layers keeps untraceable assets out; returning defects to the submitter with entity identifiers is what gradually improves the deliverables themselves. What arrives after that is ordinary ingestion, and the incremental pipeline handles it from there.

For authoritative reference, consult the Fiona DXF driver notes and the Shapely simplify documentation.

Related pages