moontin

    LandXML TIN terrain validation

    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    9 hours ago
    Downloads
    5

    #MoonTIN

    MoonTIN 检查 LandXML 1.2 地形曲面的测点引用、投影退化和三角面拓扑。

    moon run cmd/main -- check examples/terrain.xml moon run cmd/main -- check examples/missing-point.xml --format json moon test --target native pwsh -NoProfile -File scripts/test-cli.ps1

    正常样本返回 0。悬空引用样本返回 1,并报告 Existing Ground 曲面的第 1 个面引用了不存在的 99 号点。输入、参数或文件读取错误返回 2。

    当前原型支持内联 TIN 点和三角面。CLI 会记录无效点和三角面,并继续验收其余记录。JSON 含曲面边界边数、连通片数及坐标范围。文件验收诊断带打开标签的行号和列号,文本模式输出为 文件:行:列,JSON 使用 location 对象。行列从 1 开始。使用 --area-tolerance N 设置投影面积阈值,单位为文件坐标单位的平方。完整支持矩阵和后续工作见 DESIGN.md 与 TODO.md。

    #验收选项

    • --strict 把验收警告视为失败。当前警告包括缺少线性单位和文件中跳过的非 TIN 曲面。
    • --max-diagnostics N 同时限制记录问题和几何拓扑诊断的输出条数,默认 1000。设为 0 时只保留统计。JSON 中的 error_count 和 warning_count 是完整计数,truncated 表示有详情未输出。
    • --max-input-bytes N 限制文件大小,默认 16 MiB。CLI 在读取文件内容前检查实际字节数,并以严格 UTF-8 解码。
    • --max-records N 限制 LandXML 1.2 命名空间中的点与面元素总数,默认 500,000。字节或记录超限时退出 2,详情写入 stderr。

    #本地性能基线

    Windows 原生 Release 构建处理 160 × 160 合成网格。输入大小为 1,895,456 字节,含 25,600 个点、50,562 个面。一次本地运行含进程启动约 614 ms,运行期间采样到的峰值工作集约 63 MiB。结果为 636 条边界边、1 个连通片。

    在单曲面样本中加入 90,000 个无关 CgPoint 元素后,文件大小约 3.77 MB。Windows Release 交替运行五次,优化前后 JSON 报告逐字节一致。中位耗时由 509 ms 降至 465 ms,采样峰值工作集由 78.1 MiB 降至 33.9 MiB。上述数据适用于该合成输入和本地环境。

    同一 160 × 160 合成网格用于对比连通片统计。Windows Release 交替运行五次,改用并查集后 JSON 报告逐字节一致,中位耗时由 575 ms 降至 542 ms,五次采样中的最大峰值工作集由 72.2 MiB 降至 65.1 MiB。

    #比较两版地形

    moon run cmd/main -- diff examples/terrain.xml examples/terrain-revised.xml --format json

    diff 按曲面名和测点 ID 比较两版 TIN 文件,报告新增、删除和移动的测点,以及三角面的增删、方向和可见性变化。两份文件的线性单位声明必须相同。测点 ID 重新编号会表现为删除和新增。

    --coordinate-tolerance N 为每个坐标轴设置比较容差,默认 0。--max-details N 限制每个曲面的明细条数,默认 1,000。退出码 0 表示无变化,1 表示有变化,2 表示读取、解析或比较失败。

    #抽查坐标高程

    moon run cmd/main -- sample examples/terrain.xml 100.25 200.25 --format json

    按 Northing、Easting 输入坐标,返回所有覆盖该点的可见三角面与线性插值高程。坐标和结果沿用文件单位。共享边或重叠曲面可返回多条结果,使用 --surface NAME 限定曲面。退出码 0 表示有命中,1 表示坐标没有可见面覆盖,2 表示输入错误。

    #提取直线高程剖面

    moon run cmd/main -- profile examples/terrain.xml 100.25 199.75 100.25 201.25 --format json

    命令接收起终点的 Northing、Easting 坐标,按沿线距离输出每个可见三角面内的线性高程区间,以及未覆盖区间。重叠或共享边上的多个三角面分别保留。--surface NAME 限定曲面。退出码 0 表示存在覆盖区段,1 表示整条线无覆盖,2 表示输入错误。

    曲面 JSON 摘要中的 geometry 汇总通过几何检查的唯一可见面,包含投影面积、三维面积和最小、最大坡度百分比。面积沿用文件线性单位的平方,重叠三角面各自计入。若计算超出浮点范围,受影响的面积汇总为 null,overflow_faces 记录局部溢出的面数。

    #导出 TIN 网格

    moon run cmd/main -- export examples/terrain.xml --format ply --local-origin > terrain.ply

    支持 OBJ 和 ASCII PLY,坐标轴依次为 Easting、Northing、Elevation。导出保留可见面的顶点顺序,以曲面为单位重用同一测点。OBJ 分组和 PLY 面属性记录曲面序号,PLY 还保留面序号。--local-origin 减去首个可见面首点的坐标,并在文件注释记录原点。

    #批量验收测点高程

    moon run cmd/main -- survey examples/terrain.xml examples/survey-points.json 0.1 --format json

    测点文件是 JSON 数组,每项包含字符串 id 和数值 northing、easting、elevation。容差沿用地形线性单位。若多个可见面覆盖同一测点,所有插值高程都须落在容差内。报告按输入顺序记录每个点的覆盖数、插值范围和偏差最大的面。退出码 0 表示全部通过,1 表示存在超差或无覆盖测点,2 表示输入错误。

    #提取等高线

    moon run cmd/main -- contour examples/terrain.xml 10.5 --level 11.5 --format json

    每条线沿相邻可见三角面的共享边拼接。分叉点处会拆成独立路径。整面高程与等高线重合时计入 skipped_flat_faces,单点接触不会形成路径。退出码 1 表示没有线段,2 表示输入或计算错误。

    #计算相对基准面的挖填方量

    moon run cmd/main -- volume examples/terrain.xml 11 --format json

    默认使用指定高程的水平面。--anchor NORTH EAST 设置锚点,--grade NORTH EAST 设置两个方向的单位坡降系数,即每单位水平距离对应的高程变化。工具切分跨过基准面的可见三角面,对上下两侧分别积分,报告挖方、填方、净挖方和投影面积。方量为文件线性单位的立方。重叠曲面分别计量。

    #回写 LandXML TIN

    moon run cmd/main -- rewrite examples/terrain.xml --timestamp 2026-11-21 09:00:00 --project Road > normalized.xml

    回写结果包含 MoonTIN 支持的 TIN 曲面、点、面和线性单位。默认保留测点 ID、三角面方向及可见性。--visible-only 移除隐藏面及其独用测点,--renumber-points 将每个曲面的测点重新编号为连续整数。--timestamp DATE TIME 和 --project NAME 可为交付文件补充元数据。回写的范围限于 TIN 数据,原文件的坐标参考系统、断裂线、路线及其他扩展元数据不会进入输出。往返测试验证 MoonTIN 可重读输出。

    ComparisonError

    pub suberror ComparisonError {
    InvalidComparison(String)
    }

    LandXmlError

    pub suberror LandXmlError {
    InvalidLandXml(String)
    }

    SamplingError

    pub suberror SamplingError {
    InvalidSample(String)
    }

    TerrainWriteError

    pub suberror TerrainWriteError {
    InvalidTerrainOutput(String)
    }

    Bounds

    pub struct Bounds {
    min_northing : Double
    max_northing : Double
    min_easting : Double
    max_easting : Double
    min_elevation : Double
    max_elevation : Double
    }

    Bounds::to_json

    CheckReport

    pub struct CheckReport {
    surfaces : Array[SurfaceSummary]
    linear_unit : String?
    area_tolerance : Double
    strict : Bool
    error_count : Int
    warning_count : Int
    truncated : Bool
    record_issues : Array[RecordIssue]
    diagnostics : Array[Diagnostic]
    }

    CheckReport::passed

    fn CheckReport::passed(self : CheckReport) -> Bool

    CheckReport::to_json

    ContourPath

    pub struct ContourPath {
    surface_number : Int
    surface_name : String
    elevation : Double
    closed : Bool
    points : Array[ContourPoint]
    }

    ContourPath::to_json

    ContourPoint

    pub struct ContourPoint {
    northing : Double
    easting : Double
    }

    ContourPoint::to_json

    ContourReport

    pub struct ContourReport {
    linear_unit : String?
    levels : Array[Double]
    paths : Array[ContourPath]
    skipped_flat_faces : Int
    }

    ContourReport::to_json

    Diagnostic

    pub(all) struct Diagnostic {
    rule : Rule
    surface_number : Int
    surface_name : String
    face_number : Int?
    point_ids : Array[String]
    location : SourceLocation?
    related_faces : Array[FaceReference]
    }

    Diagnostic::to_json

    ElevationHit

    pub struct ElevationHit {
    surface_number : Int
    surface_name : String
    face_number : Int
    elevation : Double
    point_ids : Array[String]
    }

    ElevationHit::to_json

    ElevationProfile

    pub struct ElevationProfile {
    length : Double
    linear_unit : String?
    segments : Array[ProfileSegment]
    gaps : Array[ProfileRange]
    }

    ElevationProfile::to_json

    ElevationSample

    pub struct ElevationSample {
    northing : Double
    easting : Double
    linear_unit : String?
    hits : Array[ElevationHit]
    }

    ElevationSample::to_json

    Face

    pub(all) struct Face {
    vertices : (String, String, String)
    visible : Bool
    }

    FaceChange

    pub struct FaceChange {
    vertices : Array[String]
    before_number : Int
    after_number : Int
    winding_changed : Bool
    visibility_changed : Bool
    }

    FaceChange::to_json

    FaceGeometry

    pub struct FaceGeometry {
    projected_area : Double?
    surface_area : Double?
    min_grade_percent : Double?
    max_grade_percent : Double?
    measured_faces : Int
    overflow_faces : Int
    }

    FaceGeometry::to_json

    FaceReference

    pub struct FaceReference {
    number : Int
    location : SourceLocation?
    }

    FaceReference::to_json

    LandXmlMetadata

    pub(all) struct LandXmlMetadata {
    date : String?
    time : String?
    project : String?
    description : String?
    }

    Metadata supplied by the caller for a normalized TIN document. Dates use YYYY-MM-DD and times use HH:MM:SS.

    MeshFace

    pub struct MeshFace {
    surface_number : Int
    face_number : Int
    vertices : (Int, Int, Int)
    }

    MeshFormat

    pub(all) enum MeshFormat {
    Obj
    Ply
    }

    MeshVertex

    pub struct MeshVertex {
    easting : Double
    northing : Double
    elevation : Double
    }

    ParsedTerrain

    pub struct ParsedTerrain {
    terrain : Terrain
    issues : Array[RecordIssue]
    face_numbers : Array[Array[Int]]
    }

    Point

    pub(all) struct Point {
    id : String
    northing : Double
    easting : Double
    elevation : Double
    }

    PointChange

    pub struct PointChange {
    id : String
    before : Point
    after : Point
    }

    PointChange::to_json

    ProfileRange

    pub struct ProfileRange {
    start_distance : Double
    end_distance : Double
    }

    ProfileRange::to_json

    ProfileSegment

    pub struct ProfileSegment {
    surface_number : Int
    surface_name : String
    face_number : Int
    start_distance : Double
    end_distance : Double
    start_elevation : Double
    end_elevation : Double
    }

    ProfileSegment::to_json

    RecordIssue

    pub(all) struct RecordIssue {
    surface_number : Int
    surface_name : String
    code : String
    record_kind : String
    record_number : Int
    message : String
    severity : Severity
    location : SourceLocation
    }

    RecordIssue::to_json

    ReferencePlane

    pub(all) struct ReferencePlane {
    northing : Double
    easting : Double
    elevation : Double
    north_grade : Double
    east_grade : Double
    }

    ReferencePlane::to_json

    Rule

    pub(all) enum Rule {
    DuplicatePoint
    MissingPoint
    AmbiguousPoint
    NonFinitePoint
    RepeatedVertex
    DegenerateFace
    NonFiniteArea
    DuplicateFace
    NonManifoldEdge
    SharedEdgeDirection
    BranchingBoundary
    }

    Rule::code

    fn Rule::code(self : Rule) -> String

    Severity

    pub(all) enum Severity {
    Error
    Warning
    }

    Severity::label

    fn Severity::label(self : Severity) -> String

    SourceLocation

    pub struct SourceLocation {
    line : Int
    column : Int
    }

    SourceLocation::to_json

    Surface

    pub(all) struct Surface {
    name : String
    points : Array[Point]
    faces : Array[Face]
    }

    SurfaceComparison

    pub struct SurfaceComparison {
    name : String
    status : String
    added_point_count : Int
    removed_point_count : Int
    moved_point_count : Int
    added_face_count : Int
    removed_face_count : Int
    changed_face_count : Int
    added_points : Array[String]
    removed_points : Array[String]
    moved_points : Array[PointChange]
    added_faces : Array[Array[String]]
    removed_faces : Array[Array[String]]
    changed_faces : Array[FaceChange]
    truncated : Bool
    }

    SurfaceComparison::to_json

    SurfaceSummary

    pub struct SurfaceSummary {
    surface_number : Int
    name : String
    decoded_points : Int
    decoded_faces : Int
    invisible_faces : Int
    indexed_faces : Int
    skipped_visible_faces : Int
    usable_points : Int
    boundary_edges : Int
    boundary_loops : Int
    branched_boundaries : Int
    connected_components : Int
    bounds : Bounds?
    geometry : FaceGeometry
    }

    SurfaceSummary::to_json

    SurveyPoint

    pub(all) struct SurveyPoint {
    id : String
    northing : Double
    easting : Double
    elevation : Double
    }

    SurveyReport

    pub struct SurveyReport {
    linear_unit : String?
    tolerance : Double
    passed_count : Int
    outside_tolerance_count : Int
    uncovered_count : Int
    results : Array[SurveyResult]
    }

    SurveyReport::passed

    fn SurveyReport::passed(self : SurveyReport) -> Bool

    SurveyReport::to_json

    SurveyResult

    pub struct SurveyResult {
    point : SurveyPoint
    status : SurveyStatus
    hit_count : Int
    min_elevation : Double?
    max_elevation : Double?
    worst_hit : ElevationHit?
    max_absolute_error : Double?
    }

    SurveyResult::to_json

    SurveyStatus

    pub(all) enum SurveyStatus {
    Passed
    OutsideTolerance
    Uncovered
    }

    SurveyStatus::label

    fn SurveyStatus::label(self : SurveyStatus) -> String

    Terrain

    pub(all) struct Terrain {
    linear_unit : String?
    surfaces : Array[Surface]
    }

    TerrainComparison

    pub struct TerrainComparison {
    linear_unit : String?
    coordinate_tolerance : Double
    surfaces : Array[SurfaceComparison]
    }

    TerrainComparison::changed

    fn TerrainComparison::changed(self : TerrainComparison) -> Bool

    TerrainComparison::to_json

    TerrainMesh

    pub struct TerrainMesh {
    vertices : Array[MeshVertex]
    faces : Array[MeshFace]
    linear_unit : String?
    origin : MeshVertex
    }

    TerrainMesh::encode

    fn TerrainMesh::encode(self : TerrainMesh, format : MeshFormat) -> String

    VolumeReport

    pub struct VolumeReport {
    reference : ReferencePlane
    linear_unit : String?
    surfaces : Array[VolumeSurface]
    cut : Double
    fill : Double
    }

    VolumeReport::to_json

    VolumeSurface

    pub struct VolumeSurface {
    number : Int
    name : String
    faces : Int
    above_faces : Int
    below_faces : Int
    crossing_faces : Int
    coincident_faces : Int
    projected_area : Double
    above_area : Double
    below_area : Double
    cut : Double
    fill : Double
    }

    VolumeSurface::to_json

    build_mesh

    fn build_mesh(terrain : Terrain, surface_name? : String, local_origin? : Bool) -> TerrainMesh raise SamplingError

    Builds a visible mesh in X=easting, Y=northing, Z=elevation order. Local origin uses the first vertex of the first visible face.

    check

    fn check(source : String, area_tolerance? : Double, strict? : Bool, max_diagnostics? : Int, max_records? : Int) -> CheckReport raise

    check_survey_points

    fn check_survey_points(terrain : Terrain, points : ArrayView[SurveyPoint], tolerance : Double, surface_name? : String) -> SurveyReport raise SamplingError

    Checks measured elevations against every covering visible triangle. A point passes if all hits are within the absolute elevation tolerance.

    compare_terrain

    fn compare_terrain(before : Terrain, after : Terrain, coordinate_tolerance? : Double, max_details? : Int) -> TerrainComparison raise ComparisonError

    Compares named TIN surfaces using their authored point IDs. Coordinate tolerance applies independently on each axis in the file unit. The detail limit applies per surface and full counts remain available.

    elevation_profile

    fn elevation_profile(terrain : Terrain, start : (Double, Double), end : (Double, Double), surface_name? : String) -> ElevationProfile raise SamplingError

    Extracts piecewise linear elevation along a straight survey line. Endpoints are (northing, easting). Shared edges and overlaps retain each hit.

    estimate_volume

    fn estimate_volume(terrain : Terrain, reference : ReferencePlane, surface_name? : String) -> VolumeReport raise SamplingError

    Integrates vertical cut and fill with respect to a planar reference. Grades are rises per unit horizontal distance, not percentages.

    extract_contours

    fn extract_contours(terrain : Terrain, requested_levels : ArrayView[Double], surface_name? : String, max_segments? : Int) -> ContourReport raise SamplingError

    Traces contour segments through matching TIN edges. Flat faces coincident with a level are counted separately because they cover an area.

    parse

    fn parse(source : String) -> Terrain raise

    parse_records

    fn parse_records(source : String) -> ParsedTerrain raise

    sample_elevation

    fn sample_elevation(terrain : Terrain, northing : Double, easting : Double, surface_name? : String) -> ElevationSample raise SamplingError

    Returns every visible face containing the query position in file order. Multiple hits let callers inspect shared edges and overlapping surfaces.

    validate

    fn validate(terrain : Terrain, area_tolerance? : Double) -> Array[Diagnostic]

    write_landxml

    fn write_landxml(terrain : Terrain, surface_name? : String, visible_only? : Bool, renumber_points? : Bool, metadata? : LandXmlMetadata) -> String raise

    Writes the supported TIN subset of LandXML. Visible-only output removes hidden faces and points no remaining face references.