Feature Request: Support non-vertical downholes in AGS and GEF converters

[antbrown]

Summary

Add support for non-vertical downholes in AGS and GEF data converters by calculating dip and azimuth from directional survey data when available.

Background

Currently, the AGS and GEF converters assume all downholes are vertical (azimuth = 0°, dip = 90°). However, both data formats can contain directional survey information that describes non-vertical downholes:

• GEF files: Columns 8-10 and 21-22 may contain inclination data (resultant, N-S, E-W, X, and Y components)
• AGS files: The HORN table may contain HORN_ORNT (orientation from north) and HORN_INCL (inclination from horizontal) values

When this directional data is present, it should be used to accurately construct the DownholeCollection -> Location -> Path component with proper dip and azimuth values, enabling correct spatial representation of inclined boreholes.

User Story

As a geotechnical engineer importing field data
I want to have non-vertical downholes correctly represented with their actual dip and azimuth values
So that the spatial location of measurements along inclined boreholes is accurately modelled in the Evo data structure

Acceptance Criteria

• GEF converter detects and uses available inclination columns (8, 9, 10, 21, 22) to calculate dip and azimuth
• AGS converter detects the HORN table and uses HORN_ORNT and HORN_INCL values to calculate dip and azimuth
• When directional data is not available, the system defaults to vertical (azimuth = 0°, dip = 90°) with a logging message indicating this assumption
• Calculated dip and azimuth values are correctly assigned to the DownholeCollection_V1_3_1_Location.path component
• The mathematical conversion from source format directional data to Evo's dip/azimuth representation is documented
• Logging messages clearly indicate when:
  • Directional data is found and used
  • Vertical downhole is assumed due to missing data
• Synthetic test data covering both vertical and non-vertical cases is created and included

Out of Scope

• Support for curved downhole paths (only straight inclined sections will be supported)
• Interpolation between survey points

References

• GEF specification columns 8-10, 21-22 (inclination data) https://bedrock.engineer/reference/formats/gef/gef-cpt/#column-quantities
• AGS4 HORN table specification (HORN_ORNT, HORN_INCL fields) https://www.ags.org.uk/content/uploads/2022/02/AGS4-v-4.1.1-2022.pdf (search "Group Name: HORN")

Implementation Notes

• The exact mathematical conversion from GEF inclination components to dip/azimuth needs to be researched and documented
• No conversion from AGS HORN_ORNT (degrees from north) and HORN_INCL (down from horizontal) to Evo's dip/azimuth convention is required.
• Consider whether partial directional data (e.g., only some GEF columns present) should trigger a warning or default to vertical
• The HORN table in AGS defines sections with HORN_TOP and HORN_BASE depths (intervals) and the DownholeDirectionVector_V1_0_0 component uses distance values, we use a lookup to find if each depth falls within a given interval and if so uses the associated dip/azimuth values

Definition of Done

• All acceptance criteria met
• Code reviewed and approved by maintainers
• Documentation complete and reviewed (including mathematical conversions)
• Tests passing in CI/CD pipeline (including synthetic non-vertical test cases)

[antbrown]

This is implemented in the following PR's

• Support non-vertical downholes in AGS antbrown/evo-data-converters#63
• Support non-vertical downholes in GEF antbrown/evo-data-converters#61