Add lidar/point cloud integration guide and modernize integration docs - #534
Open
kevankramb wants to merge 12 commits into
Open
Add lidar/point cloud integration guide and modernize integration docs#534kevankramb wants to merge 12 commits into
kevankramb wants to merge 12 commits into
Conversation
Adds doc/lidar_integration.md outlining the highest-priority schema fields for integrators converting lidar, point cloud, or other classified survey datasets into SPIDA project JSON, with field-by-field geometry mapping, tension options, units/conventions, and validation checklist. Links the guide from README, calc.md, and data_requirements.md. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Fix broken schema links in rpc.md, clientAPI.md, stationLinkerAPI.md, projectSearches.md, and resources/schema/README.md - Fix malformed cee-cli link in input_assemblies.md and point rpc.md's removed asset.json interface reference to the asset API doc - Update README released/master version lines (12.0.3 / 13.0.0) and typo - Link previously undiscoverable integration docs (data_requirements, clientReferences, results, cee) from README, calc.md, and doc/README.md - Add SPIDAcalc doc index to doc/README.md landing page Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Validates against spidacalc/calc/project.schema (draft-04, strict). Demonstrates a Measured design populated from point cloud extraction: measured pole agl/glc, lean, measuredSag and midspanHeight wires, span points, relative WEP elevations, and pc-* externalIds. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
calc.md: - Correct Supported Structure Fields list to match structure.schema (adds wireMountedEquipments, trusses, componentBraces; removes duplicate Equipment entry and deprecated Sidewalk Guys) - Fix stale schema paths (v1/calc -> resources/schema/spidacalc/calc) and calc_project.schema -> project.schema - Condense long-resolved 4.4.2/5.3-era known issues and strikethrough history into current behavior statements - Fix broken/bare dev-tool links; point schema validation at the repo's validateJson gradle task - Fix demo script path and typos (Unknwn, CROSS_CONNEC T, 'another programming', coffescript) - Replace absolute GitHub links with relative doc links All docs: normalize SPIDACalc -> SPIDAcalc casing. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replaces the inaccurate 'Component ids may be any string' claim with
an Identifiers and Validation section covering what SPIDAcalc actually
enforces on import:
- Import-time schema validation always runs; failures reject the file
(strict mode only changes additionalProperties handling)
- Component ids: letters/numbers/underscores/spaces/#, min 2 chars,
no leading/trailing space; uniqueness required but only enforced in
the UI - duplicates on import resolve to the first match
- connectionId: lowercase 24-char hex ([a-f0-9]{24}, schema-enforced);
pairing rules and silent-disconnect behavior documented
- clientItemVersion / load case version / analysisCaseVersion:
lowercase 32-char hex hash ([a-f0-9]{32}, schema-enforced) with
clientItem/clientItemAlias fallback
- externalId free-form; project/location/design ids calc-managed;
label character and length limits
Also links the lidar guide's ID note to the new section.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Three-pole example project demonstrating cross-design connectivity (connectionIds on wire end points and wires), connectedWire pairs through the middle pole, and measuredSag on all spans. Validated against project.schema (strict draft-04). Linked from the lidar integration guide and calc.md connectivity section, and refreshed the stale projects example README index. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Capstone example project integrating all lidar-extraction features in a semi-realistic feeder: five connected locations (connectionIds), connected wires through the middle poles (connectedWire), field-measured sags for tension data on every span, and terrainPoints under every span including a creek crossing, plus deadend guys/anchors and a transformer. Terrain profiles are reciprocal across connected WEPs and validated against project.schema (strict draft-04). Linked from the lidar guide, calc.md connectivity section, and the projects README. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Five-pole connected example that delivers ground as a project-level terrain layer (terrainLayers points with lat/lon/absolute elevations, assigned to the Measured Design layer via appliedTerrainLayers) instead of per-span wireEndPoints[].terrainPoints. Terrain elevations at the pole locations are consistent with the WEP relative elevations, and connectivity/measured sags follow the other lidar examples. Documented appliedTerrainLayers in the calc.md Terrain Layers section and updated the guide's terrain row and example indexes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Investigated why the terrain layer example was not applied to spans in SPIDAcalc. Root cause: Design.hasTerrain() requires the design mapLocation to include an absolute altitude; on JSON import calc wires the layer but never back-fills pole elevations (that only happens via the UI settings dialog), so 2D coordinates cause a silent fallback to per-span terrainPoints. Point proximity was not an issue - points need only be within profileViewWidth of the span centerline, which held. - Add third GeoJSON coordinate (pole base elevation, meters ASL) to every location geographicCoordinate and design mapLocation in lidar_terrain_layer_project.json, exactly matching the terrain layer elevation at each pole and the wire end point relativeElevation chain - Document both requirements in the calc.md Terrain Layers section and the lidar integration guide terrain row Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The terrain layer elevations were unit-tagged FOOT values around 780 while the GeoJSON mapLocation altitudes are bare meters around 238 - functionally identical to calc (which normalizes both to meters), but the raw file read as a ~550 ft separation between ground and poles and invited real datum mistakes. Convert all 13 terrain layer point elevations to METRE with values identical to the pole z coordinates, and note the GeoJSON meters convention pitfall in the calc.md Terrain Layers section. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
SPIDAcalc keeps a terrain layer point on a span only if its along-track projection (computed on a spherical earth from the GPS coordinates) is within the wire end point's horizontal distance. The example's span distances were derived with flat-earth approximations and came up 0.1-0.4 ft short of the geodesic pole separations, so the point at the far pole of every span was silently culled - visible at distance 0 from its own pole but missing when the same span was viewed from the other end. Bump each span's distance (both paired wire end points) to cover the geodesic separation, and document the pitfall in calc.md and the lidar integration guide. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Integrators converting lidar, point cloud, or other classified survey data into our schema JSON regularly ask "what are the main fields to fill in from the acquisition?" We had no doc answering that, and while auditing for one we found broader gaps: broken links, stale version references, 7.x-era content, and inaccurate claims about ID validation. This PR adds the guide and fixes the surrounding docs.
New documentation
doc/lidar_integration.md- a priority-ordered guide mapping point-cloud extractions to schema fields, informed by how the calc engine actually consumes the JSON: what drives analysis (attachment heights, spans, sags, lean), what calc defaults when absent, tension options when field tension is unknown, units/bearing conventions, a validation checklist, and a suggested development path. Linked from the README,doc/calc.md, anddoc/data_requirements.md.resources/examples/spidacalc/projects/lidar_measured_project.json- a complete "Measured" design built the way the guide describes (measured AGL/GLC, lean,measuredSagandmidspanHeightwires, span points, relative WEP elevations,externalIds throughout). Validates clean againstproject.schemain strict draft-04 mode.doc/calc.md"Identifiers and Validation" - documents what SPIDAcalc actually enforces on imported JSON, verified against the calc engine source: import-time schema validation always runs and rejects failures; component id format rules and first-match behavior for duplicate ids;connectionIdmust be lowercase 24-char hex ([a-f0-9]{24});clientItemVersion/load case version hashes must be lowercase 32-char hex ([a-f0-9]{32}) with clientItem/alias fallback; label restrictions. Replaces the previous inaccurate "ids may be any string" claim.Docs cleanup
doc/andresources/schema/README.md(a link checker now reports zero broken links)data_requirements.md,clientReferences.md,results.md,cee.md) are discoverablecalc.md: structure fields list now matchesstructure.schemaexactly (addswireMountedEquipments,trusses,componentBraces; removes a duplicate entry and deprecated sidewalk guys), fixed stale schema paths (v1/calc,calc_project.schema), condensed decade-old 4.4.2/5.3-era known-issue notes into current behavior, and replaced dead JSV tooling references with the repo'svalidateJsontaskSPIDACalc->SPIDAcalcacross markdown docsNotes for reviewers
Validatorclass uses, in strict mode, alongside a known-good control example.