KML Road Length Calculator

🛣️ Civil Engineering User Manual: KML Linear Take-off Engine

System Purpose: Automated spatial analysis tool for calculating chainages, polyline lengths, and linear quantities (Bill of Quantities / BOQ estimation) from spatial Keyhole Markup Language (KML) road alignment data.

1. Executive Summary

This script serves as a web-based geographic information system (GIS) engine for highway design, survey review, and quantity estimation. It ingests alignment vector data (KML files), projects geographic coordinates onto an ellipsoidal geodesic model, computes horizontal segment lengths (chainages), and aggregates totals dynamically based on user-defined scope selection.

2. Core Functional Modules

Module A: GIS Engine & Coordinate Reference System Initialization

The application initializes a web map client utilizing the Leaflet.js framework using the standard Web Mercator coordinate system (EPSG:3857). Initial view coordinates are defaulted to [0, 0] at global scale prior to vector file loading.

var map = L.map('map').setView([0, 0], 2);
var kmlLayers = L.featureGroup().addTo(map);

Module B: Asynchronous Vector File Ingestion & Parsing

When KML alignment drawings (exported from AutoCAD Civil 3D, Google Earth, or MicroStation) are uploaded, the application instantiates a FileReader API loop. It parses spatial vectors using the Leaflet-Omnivore plugin without sending sensitive project data to external servers.

Input Property Engineering Treatment
LineString / MultiLineString Parsed into continuous polyline vertices $(x_i, y_i, z_i)$ for distance computation.
Feature Attributes (properties.name) Extracted to label alignment segments (e.g., "Chainage 0+000 to 2+500", "Mainline Alignment"). Defaults to "Unnamed Road" if unlabelled.
Geographic Bounds Triggers automatic spatial zooming (map.fitBounds()) to frame the imported road alignment network.

Module C: Geodesic Length Computation (The Geodetic Engine)

Planar Euclidean calculations ($\sqrt{\Delta x^2 + \Delta y^2}$) introduce severe distortion over long linear infrastructure projects due to Earth's curvature. This script computes actual ground-projected distance between consecutive horizontal alignment points using WGS-84 ellipsoidal geometry (Haversine/Vincenty formula approximations via Leaflet's native distanceTo() method).

$$\text{Segment Length } (L) = \sum_{i=1}^{n-1} \text{distanceTo}(\text{Point}_i, \text{Point}_{i+1})$$
Where distanceTo calculates the great-circle arc length over the WGS-84 reference ellipsoid in meters.
function getLengthFromPoints(points) {
  var lineLength = 0;
  for (var i = 0; i < points.length - 1; i++) {
    lineLength += points[i].distanceTo(points[i + 1]); // Returns horizontal surface distance in meters
  }
  return lineLength;
}

Module D: Dynamic Quantity Take-off & Selection Filtering

Each parsed road alignment segment is appended to a structural Bill of Quantities (BOQ) table with a control checkbox. The exact computed length is stored as raw unrounded metadata inside the DOM element: data-length="lengthInMeters".

When alignment segments are checked or unchecked by the project engineer, an event listener triggers recalculateTotal(), performing a real-time vector summation over active elements only.

function recalculateTotal() {
  var newTotal = 0;
  var checkedBoxes = document.querySelectorAll('.road-checkbox:checked');
  checkedBoxes.forEach(function(box) {
    newTotal += parseFloat(box.dataset.length);
  });
  totalLength = newTotal;
  updateDisplay();
}

3. User Workflow for Site Engineers & Estimators

  1. Import Alignments: Click Add KML to load centerlines exported from survey or design software.
  2. Review Network: The map automatically pans and zooms to the site location. Alignment layers render graphically on the map canvas.
  3. Scope Quantities: Inspect the schedule of quantities in the generated data table. Uncheck temporary bypass roads, service lines, or secondary alternatives to isolate mainline pavement requirements.
  4. Output Acquisition: View the aggregated linear quantity displayed simultaneously in meters (exact precision) and kilometers (standard chainage notation).
⚠️ Engineering Note on Elevation (3D Cut/Fill): The current spatial parsing engine measures 2D horizontal surface distance ($L_h$). For steep terrain alignments (slopes exceeding 10%), true slope length ($L_s = \sqrt{L_h^2 + \Delta Z^2}$) must account for vertical profile gradients using supplemental elevation profile analysis.

📌 Functional Capabilities

  • Extracts LineString and MultiLineString geometries from KML files.
  • Calculates distances accurately using geodesic spatial formulas via Turf.js.
  • Interactively syncs map polyline visibility with table checkbox selections.