CODEX README — HAPI Obsidian Foundation

Purpose

This file is the recommended entry point for Codex or another coding agent working on the HAPI Project.

The goal is to provide enough project context to understand the HAPI business logic without repeatedly attaching the PDF user manual.

What HAPI Is

HAPI stands for HyD Automated Plotting Interface. It is a Civil 3D workflow originally implemented as Dynamo scripts for:

survey data exchange
point data import and export
migration from legacy DGN/DWG sources
survey plan drafting
plan production
Existing Conditions Modelling (ECM)

The long-term project direction is to migrate the Dynamo workflow into a structured, testable, and maintainable PythonNet3 / C# framework for Autodesk Civil 3D.

Read These Files First

Read the notes in this order:

00_Index.md
01_System_Overview/HAPI_System_Overview.md
03_Core_Concepts/Point_Code.md
03_Core_Concepts/Feature_Code.md
03_Core_Concepts/Feature_Type.md
03_Core_Concepts/Point_Code_Grouping_Rules.md
03_Core_Concepts/Rectangle_Fitting_Rules.md
03_Core_Concepts/Style_Code.md
06_Code_Reference/Feature_Catalogue.md
06_Code_Reference/Global_Configuration.md

Source Priority

Use this priority order when sources conflict:

Priority	Source	Treatment
1	User-confirmed corrections	Highest priority where explicit.
2	HAPI User Manual.pdf	Official workflow and terminology.
3	HAPI Quick Start Guide.pdf	Visual and explanatory supplement.
4	FeatureCatalogue.json / GlobalConfiguration.json	Current executable configuration.
5	Old Markdown specifications	Implementation notes, not automatically canonical.

Confirmed Corrections

Topic	Correct Rule
Shrink to Fit rectangle scoring	Use Minimum Perimeter. Do not use minimum area, even though the manual says smallest area.

Core Concepts

Point Code

A Point Code defines the surveyed feature and controls geometric processing.

Point Code = Feature Code + optional Segment Type Indicator + optional Numeric Suffix + optional Supplementary Suffix

Important examples:

Code	Meaning
`KX01`	Kerb Bottom, straight segment, cluster `01`.
`KC01`	Kerb Bottom, curve segment, cluster `01`.
`CP3`	Catch Pit using three points for enclosing rectangle construction.
`FB02`	Flower Bed cluster `02`, forming an irregular polygon.
`KX01G`	Kerb Bottom cluster `01` with compound Grating suffix.

Feature Type

Supported routing types:

Feature Type	Meaning
`1POINT`	Single-coordinate placement.
`2POINT`	Two points define length and orientation.
`LINEAR`	Open continuous line string.
`POLYGON`	Enclosed or rectangle-derived shape.

Numeric Suffix

Digit Count	Type	Meaning
1	Sizing Number	Defines the exact number of points for rectangle construction.
2	Clustering Number	Links non-sequential related records.

Rectangle Fitting

Use two modes:

Mode	Rule
Best-fit	Select the truest 90-degree surveyed corner and align the rectangle to it.
Shrink to Fit	Test candidate orientations and select the lowest `Width + Height` score.

Always apply left-first orientation stabilisation after rectangle generation.

Style Code

Style Code is used for ECM appearance and object style resolution. Point Code defines geometry and processing; Style Code defines physical appearance and ECM style selection.

Implementation Constraints

Naming

Use PascalCase for planned functions and methods.

Examples:

ParseSurveyData
ParsePointCode
ResolveFeatureCode
ResolveFeatureType
CalculateBestFitRectangle
CalculateShrinkToFitRectangle
CreateCogoPoints
BuildLayerMapping

Environment

Target environment:

Autodesk Civil 3D 2026+
Civil 3D 2027 compatibility where relevant
Dynamo for Civil 3D during migration
PythonNet3
CPython 3.11
AutoCAD .NET API
Civil 3D .NET API
Future native C# Civil 3D plugin path

Architecture

Obsidian is the knowledge-management layer, not the automation engine.

PythonNet3/C# code should keep pure business logic testable outside Civil 3D where possible. Civil 3D API-dependent code should be isolated behind clear integration layers.

Do Not Do

Do not invent unsupported HAPI rules.
Do not treat old Markdown files as higher authority than the manual unless there is a user-confirmed correction.
Do not use minimum area for Shrink to Fit.
Do not hard-code Feature Catalogue values where they can be loaded from configuration.
Do not mix raw source extraction with final structured notes.

Current Knowledge Base Status

This first batch defines the foundation layer:

HAPI system overview
Point Code anatomy
Feature Code and Feature Type
Numeric suffix rules
grouping logic
rectangle fitting rules
Style Code basics
Feature Catalogue reference
Global Configuration reference

Next recommended batches:

file format notes for CSV, PT2, DTA, and XYZ
SurveyRecord data model
A-series script documentation
PythonNet3 code generation rules
pure Python test harness notes
C# migration architecture notes

Open Questions

Should curve Feature Codes such as KC be stored as raw FeatureCode = KC, or resolved to base FeatureCode = KX plus IsCurveSegment = True?
Should the misspelt configuration key FriendlyNeighborhoodThreshould be preserved or migrated with alias support?
Should Supplementary Suffix rules live in FeatureCatalogue.json or a separate compound feature catalogue?