Converting CAD Elevations to Indoor Z-Levels: A Production Pipeline for Wayfinding Automation

Architectural and structural CAD deliverables rarely publish Z-coordinates in a format directly consumable by indoor wayfinding engines. Surveyors and BIM modelers typically anchor elevations to absolute geodetic datums (e.g., NAVD88, EGM96) or arbitrary site-relative benchmarks (e.g., Z=0.00 at finished floor grade, Z=100.00 at slab top). Indoor navigation systems, however, require discrete, topology-aware Z-levels that align with routing graphs and POI classification schemas. Without a deterministic conversion pipeline, vertical datum mismatches propagate through the entire mapping stack, causing routing discontinuities, POI misplacement, and failed vertical transitions.

This guide details a production-grade methodology for extracting, normalizing, and clustering CAD elevation data into standardized indoor Z-levels. It targets facilities technicians, GIS developers, indoor navigation teams, and Python automation engineers building scalable wayfinding infrastructure.

Phase I: Entity Extraction & Coordinate System Audit

When parsing DWG/DXF exports, elevation data is fragmented across multiple entity types. Primary Z-bearing primitives include 3DFACE, POLYLINE (3D variants), INSERT (block references with elevation attributes), and occasionally MTEXT containing surveyor annotations. CAD layers frequently mix 2D drafting geometry (implicitly Z=0) with true 3D structural elements. Direct iteration without entity filtering introduces massive noise into the Z-distribution.

Before extraction, facilities teams must audit the drawing’s coordinate system metadata. Verify whether the file operates in a local projected coordinate system (e.g., State Plane, UTM) or a global CRS. Misaligned horizontal datums rarely affect Z-extraction directly, but they complicate spatial joins later in the pipeline. More critically, confirm the vertical reference frame. If the CAD file uses a project benchmark (e.g., BM-1 = 100.00 ft), all extracted Z-values must be shifted relative to that baseline before indoor normalization begins.

Phase II: Z-Datum Normalization & Offset Resolution

Raw CAD elevations must be stripped of geodetic or site-specific offsets to establish a consistent indoor reference frame. The normalization process involves three deterministic steps:

Baseline Identification: Locate the primary finished floor level (FFL) or structural slab datum. This is typically the most densely populated Z-cluster in the lower quartile of the dataset.
Vertical Shift Application: Subtract the baseline Z-value from all extracted elevations to anchor the indoor coordinate system to Z=0 at the primary ground floor.
Unit Harmonization: CAD files may use imperial (feet/inches) or metric (meters) units. Convert all values to meters to align with Indoor Coordinate Reference Systems specifications used by modern routing engines.

This baseline normalization directly informs the Level Mapping & Z-Axis Logic framework used by routing engines to distinguish between mezzanines, split-levels, and continuous ramps. Without precise offset resolution, vertical adjacency graphs will incorrectly link stairwells to elevator shafts or misclassify double-height atriums as separate floors.

Phase III: Topological Clustering & Slab Intersection Resolution

CAD models rarely maintain mathematically perfect horizontal planes. Slab warping, stair stringer offsets, MEP penetrations, and surveyor rounding introduce Z-variances of ±0.05m to ±0.30m across a single floor. Direct equality checks (Z == 3.00) will fail, producing fragmented Z-levels that break wayfinding continuity.

The industry-standard solution applies density-based clustering to group proximate Z-values into discrete floor planes. DBSCAN is preferred over K-means because it does not require pre-specifying the number of floors and naturally handles outliers (e.g., rooftop equipment, basement sumps). Facilities tech and GIS developers should enforce a vertical tolerance band (typically ±0.15m for commercial structures) to merge adjacent Z-values into a single logical floor.

Overlapping slabs—common in atrium voids, double-height retail spaces, and mechanical penthouses—require explicit intersection testing. After clustering, validate each Z-plane against architectural boundary footprints using 2D polygon intersection. If a Z-cluster spans multiple non-contiguous footprints without vertical connectivity (stairs/elevators), it should be flagged for manual review or assigned a sub-level designation (e.g., L1-A, L1-B).

Phase IV: Routing Graph Integration & POI Alignment

Normalized Z-levels must be mapped to discrete routing identifiers before ingestion into wayfinding engines. Each clustered Z-plane receives a canonical level ID (e.g., B2, G, L1, L2, P1). These IDs feed directly into the Indoor Mapping Architecture & Standards documentation outlining required tolerance matrices and vertical transition rules.

POI classification schemas rely on accurate Z-level assignment. A retail kiosk at Z=3.05m must resolve to L1, not L2, even if the ceiling height suggests a split level. Fallback routing architectures handle edge cases where Z-clustering yields ambiguous results by prioritizing connectivity to known vertical circulation nodes (stairs, escalators, elevators). When automated clustering fails, routing graphs should degrade gracefully to 2D planar navigation with explicit vertical transition warnings.

Production-Ready Python Implementation

The following pipeline demonstrates a robust, production-grade approach using ezdxf, numpy, and scikit-learn. It handles DXF parsing, Z-extraction, tolerance-aware clustering, and outputs a structured mapping table ready for routing engine ingestion.

import logging
import numpy as np
import pandas as pd
import ezdxf
from sklearn.cluster import DBSCAN
from pathlib import Path

logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")

class CADZLevelExtractor:
    def __init__(self, dxf_path: str, vertical_tolerance: float = 0.15):
        self.dxf_path = Path(dxf_path)
        self.tolerance = vertical_tolerance
        self.raw_z = []
        self.entity_ids = []
        self.layer_map = {}

    def extract_z_entities(self):
        """Parse DXF and extract Z-values from 3D-bearing entities."""
        if not self.dxf_path.exists():
            raise FileNotFoundError(f"DXF not found: {self.dxf_path}")
            
        doc = ezdxf.readfile(str(self.dxf_path))
        msp = doc.modelspace()
        
        target_types = {'3DFACE', 'POLYLINE', 'INSERT', 'SOLID'}
        
        for entity in msp:
            if entity.dxftype() in target_types:
                try:
                    # Extract all vertices/points with Z
                    if hasattr(entity, 'vertices'):
                        for v in entity.vertices:
                            z = float(v.z)
                            self.raw_z.append(z)
                            self.entity_ids.append(entity.dxf.handle)
                    elif hasattr(entity, 'dxf') and hasattr(entity.dxf, 'elevation'):
                        z = float(entity.dxf.elevation)
                        self.raw_z.append(z)
                        self.entity_ids.append(entity.dxf.handle)
                except Exception as e:
                    logging.warning(f"Failed to parse Z from {entity.dxftype()}: {e}")
                    
        logging.info(f"Extracted {len(self.raw_z)} Z-values from DXF.")
        return np.array(self.raw_z)

    def normalize_and_cluster(self, z_array: np.ndarray):
        """Apply vertical shift, cluster Z-values, and assign level IDs."""
        if len(z_array) == 0:
            raise ValueError("No Z-values extracted. Check DXF entity types.")
            
        # Step 1: Normalize to lowest dense cluster (assumed ground floor)
        baseline = np.percentile(z_array, 10)
        z_normalized = z_array - baseline
        
        # Step 2: DBSCAN clustering on 1D Z-axis
        # eps = tolerance, min_samples = 50 (adjust based on drawing complexity)
        clustering = DBSCAN(eps=self.tolerance, min_samples=50).fit(z_normalized.reshape(-1, 1))
        
        labels = clustering.labels_
        # Filter out noise (-1)
        valid_mask = labels != -1
        z_clean = z_normalized[valid_mask]
        labels_clean = labels[valid_mask]
        ids_clean = [self.entity_ids[i] for i, m in enumerate(valid_mask) if m]
        
        # Step 3: Order clusters by elevation (cluster centroids on the Z axis)
        # and assign canonical level strings (B-n / G / L-n).
        unique_clusters = np.unique(labels_clean)
        cluster_centroids = {
            cid: float(np.median(z_clean[labels_clean == cid])) for cid in unique_clusters
        }
        ordered = sorted(unique_clusters, key=lambda c: cluster_centroids[c])
        
        # Ground floor = the cluster whose centroid is closest to Z=0.
        ground_cluster = min(ordered, key=lambda c: abs(cluster_centroids[c]))
        ground_idx = ordered.index(ground_cluster)
        
        level_map = {}
        for idx, cid in enumerate(ordered):
            if idx == ground_idx:
                level_map[cid] = "G"
            elif idx < ground_idx:
                level_map[cid] = f"B{ground_idx - idx}"     # below ground
            else:
                level_map[cid] = f"L{idx - ground_idx}"     # above ground
        
        df = pd.DataFrame({
            "entity_id": ids_clean,
            "z_raw": z_array[valid_mask],
            "z_normalized": z_clean,
            "cluster_id": labels_clean,
            "level_id": [level_map[c] for c in labels_clean]
        })
        
        logging.info(f"Clustering complete. {len(unique_clusters)} discrete levels identified.")
        return df

    def run(self, output_path: str = "z_level_mapping.csv"):
        z_data = self.extract_z_entities()
        mapping_df = self.normalize_and_cluster(z_data)
        mapping_df.to_csv(output_path, index=False)
        logging.info(f"Mapping exported to {output_path}")
        return mapping_df

# Usage Example:
# extractor = CADZLevelExtractor("site_floorplan.dxf", vertical_tolerance=0.15)
# df = extractor.run()

Diagnostics & Validation Protocol

Before deploying normalized Z-levels to production routing engines, execute the following validation checks:

Vertical Gap Analysis: Verify that the delta between consecutive level centroids exceeds 2.0m (standard floor-to-floor height). Gaps <1.5m indicate unresolved split-levels or clustering over-merging.
POI Z-Alignment Audit: Sample 10% of POI coordinates against the normalized Z-level table. Ensure classification matches physical placement (e.g., restrooms on L1 should not resolve to L2).
Vertical Circulation Connectivity: Confirm that stairwell and elevator shaft entities intersect exactly two adjacent Z-levels. Single-level intersections indicate missing floor slabs; triple intersections indicate atrium misclassification.
Tolerance Sensitivity Testing: Re-run clustering with ±0.10m and ±0.20m tolerances. If level counts fluctuate by >15%, the CAD model contains excessive Z-drift and requires pre-processing (e.g., planarization or slab flattening).

For comprehensive tolerance matrices and vertical routing fallback architectures, consult the Indoor Mapping Architecture & Standards documentation. Properly normalized Z-levels eliminate vertical routing failures, ensure POI taxonomy alignment, and provide a deterministic foundation for automated wayfinding graph generation.

Converting CAD Elevations to Indoor Z-Levels: A Production Pipeline for Wayfinding Automation

Phase I: Entity Extraction & Coordinate System Audit #

Phase II: Z-Datum Normalization & Offset Resolution #

Phase III: Topological Clustering & Slab Intersection Resolution #

Phase IV: Routing Graph Integration & POI Alignment #

Production-Ready Python Implementation #

Diagnostics & Validation Protocol #