Purpose: Demonstrate computational geometry workflows through triangulation and bounding-box clipping exposed as clean versioned APIs.
Business problem: Shows how map-drawn coordinates can be transformed into derived geometry that is ready for GIS visualization and downstream analysis.
Scope: The current MVP intentionally implements simple fan triangulation and vertex clipping. It establishes the API/native boundary for future robust algorithms such as Delaunay triangulation, Voronoi generation, and topology validation.
Frontend Architecture
Page:Pages/Projects/Geometry/Index.cshtml provides JSON coordinate input, bounding-box controls, operation buttons, KPI cards, and an SVG viewport.
Script:wwwroot/js/Geometry/app.js uses the existing IIFE pattern and shared apiPost helper.
Rendering: Triangle and clipped polygon results are rendered as SVG polygons, which maps cleanly to future ArcGIS graphics or feature layers.
State: The browser stores only the active point set and result payload; geometry rules remain server-side.
Route config: API paths are centralized under PortfolioApi.routes.spatialCompute.geometry.
API Layer
Controller:SpatialGeometryController is versioned at /api/v1/geometry and allows anonymous portfolio access.
Endpoints:POST /api/v1/geometry/triangulate accepts GeometryPointSetDto; POST /api/v1/geometry/clip accepts PolygonClipRequestDto.
Responses:TriangulationResultDto returns triangles; PolygonOperationResultDto returns clipped vertices. Both expose a native acceleration flag.
Validation: The service rejects insufficient points, invalid bounding boxes, and non-finite coordinates.
Error translation:ArgumentException maps to 400 with the standard { error } response shape.
Services and Business Logic
Service:SpatialGeometryService validates requests, branches through SpatialGeometryNativeBridge.IsAvailable, and returns DTOs only.
Managed fallback: Produces a fan triangulation from the first point and clamps polygon vertices into a bounding box. This keeps behavior deterministic and easy to test.
Native bridge:SpatialGeometryNativeBridge maps CoordinateDto to CoordinateNative, passes preallocated output buffers, and translates native status codes into managed exceptions.
C++ library:native/spatial_geometry_kernel exposes Geometry_TriangulateFan and Geometry_ClipToBoundingBox through a stable C ABI.
Why C++ here: Production geometry engines depend on robust predicates, exactness tradeoffs, specialized memory layouts, and native libraries such as GEOS, CGAL, Clipper2, or Boost.Geometry.
Data Access Layer
Current MVP: Geometry operations are stateless and do not use EF Core or PostgreSQL.
Reasoning: The current feature focuses on request/response geometry processing rather than persisted datasets.
Future persistence: Saved geometries, uploaded datasets, or benchmark cases could be represented by models in Portfolio.Common and repositories in Portfolio.Repositories.
Spatial database path: PostgreSQL/PostGIS would be a natural future complement if persisted geometry queries become part of the feature.
Infrastructure and Deployment
Native build:native/spatial_geometry_kernel/CMakeLists.txt builds the shared library and copies it to the .NET output path when compiled locally.
Runtime fallback: The app remains functional without the native library, which keeps Render deployment simple.
Dependency strategy: The MVP avoids heavy native dependencies. A full version could add GEOS, CGAL, or Clipper2, but deployment impact would need explicit documentation.
Container path: Native-enabled Docker builds would install the required C++ dependencies and copy the shared object before application publish.
Engineering Decisions and Tradeoffs
MVP algorithm choice: Fan triangulation is not a replacement for Delaunay triangulation, but it validates the API shape, native bridge, output-buffer contract, and frontend rendering pipeline.
Correctness over SIMD: Geometry is often branch-heavy and numerically sensitive. The C++ value is robust algorithms and data structures more than blanket AVX2 acceleration.