sageroad 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. sageroad-1.0.0/LICENSE +21 -0
  2. sageroad-1.0.0/PKG-INFO +466 -0
  3. sageroad-1.0.0/PYPI.md +441 -0
  4. sageroad-1.0.0/README.md +76 -0
  5. sageroad-1.0.0/pyproject.toml +44 -0
  6. sageroad-1.0.0/setup.cfg +4 -0
  7. sageroad-1.0.0/src/sageroad/__init__.py +0 -0
  8. sageroad-1.0.0/src/sageroad/__main__.py +9 -0
  9. sageroad-1.0.0/src/sageroad/app.py +94 -0
  10. sageroad-1.0.0/src/sageroad/main.py +69 -0
  11. sageroad-1.0.0/src/sageroad/static/app.css +545 -0
  12. sageroad-1.0.0/src/sageroad/static/index.html +53 -0
  13. sageroad-1.0.0/src/sageroad/static/lib/app.js +576 -0
  14. sageroad-1.0.0/src/sageroad/static/lib/args.js +180 -0
  15. sageroad-1.0.0/src/sageroad/static/lib/canvas.js +262 -0
  16. sageroad-1.0.0/src/sageroad/static/lib/doc.js +15 -0
  17. sageroad-1.0.0/src/sageroad/static/lib/draw.js +298 -0
  18. sageroad-1.0.0/src/sageroad/static/lib/explore.js +288 -0
  19. sageroad-1.0.0/src/sageroad/static/lib/form.js +185 -0
  20. sageroad-1.0.0/src/sageroad/static/lib/format.js +147 -0
  21. sageroad-1.0.0/src/sageroad/static/lib/geo.js +129 -0
  22. sageroad-1.0.0/src/sageroad/static/lib/homePage.js +616 -0
  23. sageroad-1.0.0/src/sageroad/static/lib/mapPage.js +663 -0
  24. sageroad-1.0.0/src/sageroad/static/lib/markdown.js +275 -0
  25. sageroad-1.0.0/src/sageroad/static/lib/model.js +1488 -0
  26. sageroad-1.0.0/src/sageroad/static/lib/models.js +304 -0
  27. sageroad-1.0.0/src/sageroad/static/lib/modelsPage.js +266 -0
  28. sageroad-1.0.0/src/sageroad/static/lib/planData.js +89 -0
  29. sageroad-1.0.0/src/sageroad/static/lib/planView.js +401 -0
  30. sageroad-1.0.0/src/sageroad/static/lib/report.js +257 -0
  31. sageroad-1.0.0/src/sageroad/static/lib/schemaDoc.js +171 -0
  32. sageroad-1.0.0/src/sageroad/static/lib/smoothing.js +71 -0
  33. sageroad-1.0.0/src/sageroad/static/lib/tables.js +78 -0
  34. sageroad-1.0.0/src/sageroad/static/lib/view3d.js +1246 -0
  35. sageroad-1.0.0/src/sageroad/static/lib/viewPages.js +471 -0
  36. sageroad-1.0.0/src/sageroad/static/plan/lib/auto.js +775 -0
  37. sageroad-1.0.0/src/sageroad/static/plan/lib/browser/buffer.js +21 -0
  38. sageroad-1.0.0/src/sageroad/static/plan/lib/browser/io.js +177 -0
  39. sageroad-1.0.0/src/sageroad/static/plan/lib/browser/zlib.js +61 -0
  40. sageroad-1.0.0/src/sageroad/static/plan/lib/design.js +140 -0
  41. sageroad-1.0.0/src/sageroad/static/plan/lib/draft.js +285 -0
  42. sageroad-1.0.0/src/sageroad/static/plan/lib/draws.js +263 -0
  43. sageroad-1.0.0/src/sageroad/static/plan/lib/elevationImage.js +364 -0
  44. sageroad-1.0.0/src/sageroad/static/plan/lib/engineer.js +764 -0
  45. sageroad-1.0.0/src/sageroad/static/plan/lib/features.js +309 -0
  46. sageroad-1.0.0/src/sageroad/static/plan/lib/numeric.js +192 -0
  47. sageroad-1.0.0/src/sageroad/static/plan/lib/ollama.js +68 -0
  48. sageroad-1.0.0/src/sageroad/static/plan/lib/planFile.js +27 -0
  49. sageroad-1.0.0/src/sageroad/static/plan/lib/plot.js +342 -0
  50. sageroad-1.0.0/src/sageroad/static/plan/lib/png.js +43 -0
  51. sageroad-1.0.0/src/sageroad/static/plan/lib/profile.js +339 -0
  52. sageroad-1.0.0/src/sageroad/static/plan/lib/roads.js +90 -0
  53. sageroad-1.0.0/src/sageroad/static/plan/lib/route.js +716 -0
  54. sageroad-1.0.0/src/sageroad/static/plan/lib/siteCommand.js +361 -0
  55. sageroad-1.0.0/src/sageroad/static/plan/lib/structures.js +181 -0
  56. sageroad-1.0.0/src/sageroad/static/plan/lib/terrain.js +502 -0
  57. sageroad-1.0.0/src/sageroad/static/plan/lib/usgs.js +188 -0
  58. sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/parser.js +611 -0
  59. sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/schema.js +659 -0
  60. sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/schemaUtil.js +349 -0
  61. sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/typeModel.js +245 -0
  62. sageroad-1.0.0/src/sageroad.egg-info/PKG-INFO +466 -0
  63. sageroad-1.0.0/src/sageroad.egg-info/SOURCES.txt +65 -0
  64. sageroad-1.0.0/src/sageroad.egg-info/dependency_links.txt +1 -0
  65. sageroad-1.0.0/src/sageroad.egg-info/entry_points.txt +2 -0
  66. sageroad-1.0.0/src/sageroad.egg-info/requires.txt +2 -0
  67. sageroad-1.0.0/src/sageroad.egg-info/top_level.txt +1 -0
sageroad-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2026 Craig A. Hobbs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,466 @@
1
+ Metadata-Version: 2.4
2
+ Name: sageroad
3
+ Version: 1.0.0
4
+ Summary: SageRoad engineers low-volume roads on USGS lidar terrain and views the resulting road plans
5
+ Author: Craig A. Hobbs
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/craigahobbs/sageroad
8
+ Keywords: road,grading,lidar,civil engineering
9
+ Classifier: Development Status :: 5 - Production/Stable
10
+ Classifier: Intended Audience :: End Users/Desktop
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Programming Language :: Python :: 3.15
18
+ Classifier: Topic :: Scientific/Engineering
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: chisel<2.6.0,>=2.5.0
23
+ Requires-Dist: waitress>=3.0.0
24
+ Dynamic: license-file
25
+
26
+ # SageRoad
27
+
28
+ [![PyPI - Status](https://img.shields.io/pypi/status/sageroad)](https://pypi.org/project/sageroad/)
29
+ [![PyPI](https://img.shields.io/pypi/v/sageroad)](https://pypi.org/project/sageroad/)
30
+ [![GitHub](https://img.shields.io/github/license/craigahobbs/sageroad)](https://github.com/craigahobbs/sageroad/blob/main/LICENSE)
31
+ [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sageroad)](https://pypi.org/project/sageroad/)
32
+
33
+ SageRoad engineers low-volume roads (driveways, rural access roads, and forest roads) on USGS lidar
34
+ terrain, and views the resulting road grading plans in 3D.
35
+
36
+ The SageRoad application runs in your web browser. Make a plan - the road's start and end points (their
37
+ latitudes and longitudes) and its planning notes - and run it: SageRoad builds the site from the USGS 3D
38
+ Elevation Program's 1 meter lidar terrain, engineers the road's options from the start point to the
39
+ end point, and costs them, and an [Ollama](https://ollama.com) model reads what the notes ask for.
40
+ Then view the options' report and 3D views, edit the plan and run it again, and save it to a file.
41
+
42
+ **[View the example road plan](https://craigahobbs.github.io/sageroad/viewer/#url=../example/example.json)** - an access road up a hill, with its road options' report,
43
+ 3D views, and 3D explorer - in the SageRoad viewer, on this project's web site. There's nothing to
44
+ install. See The example, below.
45
+
46
+ [![The example road plan's 3D views](https://craigahobbs.github.io/sageroad/example/screenshot.png)](https://craigahobbs.github.io/sageroad/viewer/#url=../example/example.json)
47
+
48
+ The application needs only Python 3.11 or later. A site must be in the United States, where the USGS
49
+ has 1 meter lidar terrain.
50
+
51
+
52
+ ## Installing
53
+
54
+ The application is a Python package - it needs [Python](https://www.python.org/downloads/) 3.11 or
55
+ later. Install it from [PyPI](https://pypi.org/project/sageroad/), in a virtual environment:
56
+
57
+ ```
58
+ python3 -m venv sageroad-venv
59
+ sageroad-venv/bin/pip install sageroad
60
+ sageroad-venv/bin/sageroad
61
+ ```
62
+
63
+ On Windows, the virtual environment's commands are `sageroad-venv\Scripts\pip` and
64
+ `sageroad-venv\Scripts\sageroad` (and `py -m venv sageroad-venv` makes it). `sageroad` opens the application
65
+ in your web browser (Ctrl-C stops it - `sageroad -h` lists its options). To update it, run the same
66
+ `pip install` with `--upgrade`.
67
+
68
+ To have a model read your plans' notes, install [Ollama](https://ollama.com), and download a model
69
+ that reads images on the application's **Ollama Models** page (a plan's **Run Plan** section links to
70
+ it). Without a model, a plan's notes aren't read.
71
+
72
+ The application runs offline - its page and its planning tools are the package's - except for the
73
+ USGS's site data, which a plan's first run (or a run after its site's points, units, margin, or
74
+ spacing change) fetches, the list of Ollama's models to download, and Ollama, on this computer (a
75
+ model's download, and an Ollama cloud model, use the internet).
76
+
77
+
78
+ ## Your first road
79
+
80
+ 1. Run the application (`sageroad-venv/bin/sageroad`), and choose **New Plan**.
81
+ 2. Give the plan a title, and its start and end points - copy each point's latitude and longitude from
82
+ a map (Google Maps, say), and paste them into its latitude. Write the road's notes: what it's for,
83
+ and what it must avoid or pass through (see The plan's notes, below). **Done** makes the plan.
84
+ 3. **Run Plan**, with an Ollama model to read the notes (**Ollama Models**, beside it, downloads
85
+ one). The first run fetches the site's data from the USGS - it takes a minute or two, and longer
86
+ for a large site.
87
+ 4. **View Plan** for its road options' report, and **Save** the plan to a file.
88
+
89
+
90
+ ## The SageRoad application
91
+
92
+ `sageroad` runs the application (or `make run`, in a clone of the repository), and opens it in your web
93
+ browser (`Ctrl-C` stops it). Its home page:
94
+
95
+ - **Open Plan** - choose or drop a plan's JSON file (and its source map image, to show it in the
96
+ report). The files stay on your computer - they're kept in the browser's storage, and the home
97
+ page lists the recent files (remove one with its ✕).
98
+ - **New Plan** - a form for the plan's config: its title, units, start and end points, notes, design
99
+ criteria, cost rates, and its site's margin and grid spacing. An empty member is its default - its
100
+ box shows it.
101
+
102
+ A plan is its config and, once it's run, its **road options**. The opened or new plan is the
103
+ **loaded plan** - the home page shows its config (its points, the distance between them, its notes,
104
+ criteria, and marks), and what can be done with it:
105
+
106
+ - **View Plan** - its road options' report (each option's length, maximum grade, earthwork, walls,
107
+ warnings, and cost score, its plan and profile, and its 3D views), and the 3D explorer.
108
+ - **Edit Plan** - its config: the notes, say. If the plan has road options, they're from the config
109
+ before - run the plan to engineer them again.
110
+ - **Edit Map** - draw its config's marks on its site's map (once it's run): the areas the road must
111
+ avoid (a property line's setback, an easement), the existing roads that the USGS doesn't map (a
112
+ track - the shaded relief shows one's worn trough), and the places the road must pass through.
113
+ The map's backdrop is the site's contours, its topographic map, or its shaded relief, with its
114
+ streams, roads, and road options. Scroll to zoom, and drag to move. Draw an area's corners or a
115
+ road's points with clicks (double-click or Enter finishes, Backspace removes the last point), or
116
+ click a place. Select a mark to rename or delete it, or drag its points. A mark that a run found
117
+ for the notes is dashed - edit it to correct it (it's yours then). **Done** makes the marks the
118
+ plan's. Run the plan again to engineer its road options with the marks - its site's data is kept,
119
+ so the USGS isn't asked for it again.
120
+ - **Run Plan** - choose an Ollama model to read its notes (or none - the last model chosen is the
121
+ default). If the notes can't be read - Ollama isn't running, or it has no models - or won't be
122
+ (no model is chosen), or the model doesn't read images (it can't find the notes' places on the
123
+ map), it says so. The run's steps are shown as it goes, with its time, and its result and report when it's
124
+ done. **Stop** stops it, when its current step's work is done - and its work is thrown away. The
125
+ road options it engineers are the plan's, and so are the places it found for the notes (see
126
+ Planning a road, below). A plan that's run again keeps its site's data (its terrain,
127
+ streams, roads, and map), so the USGS isn't asked for it again - unless its points, units, margin,
128
+ or spacing changed, or "Fetch the site's data from the USGS again" is checked. **Clear Road
129
+ Options** clears them - the plan keeps its site's data.
130
+ - **Save** the plan to its file - the file it was opened from, or saved to - or **Save As** another,
131
+ to duplicate it (and run it with another config, say). In a browser that can't write to a file
132
+ (Firefox and Safari), a save downloads the plan's file. A plan with road options keeps its config
133
+ and its map image, so it's one file - and a plan without road options is its config's file.
134
+ - **Close** it - if it has changes that aren't saved, you're asked first.
135
+ - **Ollama Models** - Ollama's models on this computer: whether each reads images, its parameters,
136
+ size, and modified date. **Delete** a model, or **Update** it (download it again), and see a
137
+ download's progress (**Stop** stops it). **Download Models** lists the models of Ollama's library -
138
+ filter them by how recent they are, whether your computer runs them (**Compatible** - a local
139
+ model needs about a byte of memory for each of its parameters), and their type (local, cloud, or
140
+ MLX - a Mac with Apple silicon's), sort them, and download one of a model's sizes. It starts with
141
+ the compatible local models of the last 6 months, the most recently modified first. A download
142
+ stops if the page is closed or reloaded - you're asked first.
143
+
144
+ Ollama answers the application's page when it runs on this computer (`http://127.0.0.1:11434`) - the
145
+ page asks Ollama itself, for its models, their downloads, and a run's questions.
146
+
147
+
148
+ ## Planning a road
149
+
150
+ A plan's config - its **road site model** - is a JSON file:
151
+
152
+ ```json
153
+ {
154
+ "title": "Hillside Driveway",
155
+ "units": "feet",
156
+ "start": {
157
+ "latitude": 44.0000, "longitude": -115.0000,
158
+ "label": "County Rd",
159
+ "description": "At the gate on the county road"
160
+ },
161
+ "end": {
162
+ "latitude": 44.0030, "longitude": -114.9960,
163
+ "label": "House site",
164
+ "description": "The bench above the creek"
165
+ },
166
+ "notes": [
167
+ "A single-lane gravel driveway with fire apparatus access.",
168
+ "Stay off the creek's east bank."
169
+ ]
170
+ }
171
+ ```
172
+
173
+ The points' latitudes and longitudes are decimal degrees, as a phone or a map application gives them
174
+ (the United States' longitudes are negative). A config may also have design criteria (`criteria`),
175
+ cost rates (`costRates`), the distance its site extends beyond the start and end points (`margin`),
176
+ its terrain grid's spacing (`spacing`), and its **marks** - the areas the road must avoid
177
+ (`exclusions`, polygons of latitudes and longitudes), the existing roads the USGS doesn't map (`roads`
178
+ - a track, a driveway - that a road may follow), and the places a road must pass through
179
+ (`passThrough`) - draw them with **Edit Map**. The model documentation (linked from the viewer's
180
+ report) describes every member.
181
+
182
+ A run of the plan:
183
+
184
+ 1. **Builds the site.** Its terrain is the USGS 3D Elevation Program's 1 meter elevation models -
185
+ lidar ground elevations - gridded in the plan's coordinates, a map projection centered on the
186
+ site. Its streams are the USGS National Hydrography Dataset's (moved to the bottoms of their
187
+ valleys), its roads and trails and its topographic map image are the USGS National Map's, and its
188
+ marks are the config's.
189
+ 2. **Reads the notes**, with a model - see The plan's notes, below.
190
+ 3. **Engineers the road options:**
191
+ - **Existing Roads** - the least-cost road, following the site's existing roads where upgrading
192
+ them costs less than a new road (if it follows any)
193
+ - **New Road** - the least-cost all-new road
194
+ - **Another corridor** - the least-cost road around the middle of those two, through the middle of
195
+ that way (named for its side - "West Corridor"), if it's a real choice: within the grade limit,
196
+ apart from them, and at most three times the least-cost option's cost score. Otherwise the
197
+ plan's description says why there isn't one.
198
+ - **Via PLACE** - a road through each place the road must pass through. A place that's a dead
199
+ end off the road's way - the road would go out to it and return the way it came - is passed
200
+ by: the plan's description says how near the road passes it.
201
+
202
+ A road is found by a least-cost lattice search (with radius-constrained turns, and grade, side
203
+ slope, stream crossing, rock, and exclusion costs) - a road doesn't cross itself, run back along
204
+ itself, or run in a stream's channel - its vertical profile is designed by dynamic
205
+ programming (the least earthwork within the grade limits, flatter on switchbacks), and its
206
+ culverts, retaining walls, bridges, and turnouts are placed. Each road is searched with three
207
+ weights of the penalty for ground steeper than the design grade, and it's the one with the lowest
208
+ cost score (the other corridor's road is searched with one). A road's cut or fill is 60 feet (18
209
+ meters) deep at most, at its center line (but for a bridge's span) - where the grade limits need
210
+ more, the road is searched again with stricter grades, and if it still does, it isn't a road. The
211
+ terrain's unmapped draws that a road crosses are added as streams, with culverts, and the roads
212
+ are engineered again. If the Existing Roads or New Road option runs to the site's edge, or
213
+ there's no road within the grade limit, the site's margin is enlarged by half, and the plan is
214
+ made again - at most twice. On ground too steep for a road at the maximum grade - a canyon's
215
+ walls, say - a run ends with no road, and says where the road it found is too deep.
216
+ 4. **Keeps the best options** - at most four, in cost score order (another corridor is the first
217
+ that isn't kept) - and writes their descriptions: the plan's facts, what the notes asked for, and
218
+ what the run did with them.
219
+
220
+
221
+ ### The plan's notes
222
+
223
+ The notes are the road's purpose, constraints, and preferences, in your words. A model (an Ollama
224
+ model) is asked what they ask for:
225
+
226
+ - the road's **width** and **surface**, a **maximum grade** and **minimum radius**, and the depth of
227
+ a stream crossing's fill that a **bridge** replaces (the config's own criteria win)
228
+ - the **existing roads to rule out** - a private or closed road, say - which the options don't follow
229
+ - the **places to avoid**, and the **places to pass through**
230
+
231
+ A place's coordinates may be in the notes ("the easement's corners are 44.0011, -114.9981; ..."):
232
+ three or more corners are an area to avoid, and one point is a place to pass through. Otherwise the
233
+ model finds the place on the site's topographic map. Each place it finds is one of the config's marks,
234
+ with how it was found - so a plan that's run again doesn't look for it again. Correct a found mark by
235
+ editing it on the map (it's yours then), and a mark that was found for a place the notes don't name
236
+ any more is removed. A place the model can't find - an easement, a property line - draw on the map. A model's reading of a map is the weakest part of a plan - the plan's description says what
237
+ the model found, to be verified. A note the run can't act on is reported, and it's in the plan's
238
+ limitations.
239
+
240
+ The model's questions are small - a paragraph, and a map image - with a JSON answer that's checked:
241
+ the model doesn't run the plan. Without a model, the notes aren't read, and the plan is the tools'
242
+ alone.
243
+
244
+ Typical criteria for the notes (from the USFS *Low-Volume Roads Engineering Best Management Practices
245
+ Field Guide*, AASHTO low-volume road guidance, and fire codes):
246
+
247
+ | | Driveway / fire access | Rural access road | Forest / ranch road |
248
+ | --- | --- | --- | --- |
249
+ | Width | 12-14 ft / 3.7-4.3 m | 14-20 ft / 4.3-6 m | 12-14 ft / 3.7-4.3 m |
250
+ | Surface | gravel (asphalt above about 12-15% grade) | gravel or asphalt | gravel or native |
251
+ | Maximum grade | 12% (10% where the fire code requires) | 12% | 15% (12% preferred) |
252
+ | Minimum radius | 50 ft / 15 m | 50 ft / 15 m | 50 ft / 15 m (70 ft for trucks with trailers) |
253
+
254
+ The defaults are a 14 foot (4.3 meter) gravel road, a 12% maximum grade (designed 1% under it, and 8%
255
+ on switchbacks), a 50 foot (15 meter) minimum radius, and a 20 foot (6 meter) maximum wall height. A
256
+ dead-end road also needs a turnaround at its end - it isn't modeled.
257
+
258
+
259
+ ## The viewer
260
+
261
+ The viewer's report - meant to be read and printed - computes each option's earthwork, structures,
262
+ and cost score, then shows:
263
+
264
+ - **Plan options** - a comparison of every option's length, maximum grade, cut, fill, net import or
265
+ export, retaining walls, design warnings, and cost score (select an option to view it)
266
+ - **Plan view** - a contour map with the road footprint (cut and fill slopes), structures, station
267
+ ticks, the other options' centerlines, and the outlines of the 3D views. Click it to explore the 3D
268
+ landscape from that point.
269
+ - **Profile** - the ground and road grade along the road, with cut and fill areas, structures, and
270
+ grades over the maximum highlighted
271
+ - **3D views** - the terrain (with contours) graded to the road's finished surface: the road, cut and
272
+ fill slopes, retaining walls, bridges, culverts, streams, station labels, and other features. The
273
+ first view is always the whole site. When the road is too narrow to see in it, views of equal road
274
+ segments follow, from the start to the end. Every view keeps the overview's general orientation, so
275
+ the reader stays oriented across the views. Each looks across its road segment - preferably upslope,
276
+ where the road's cuts into the hillsides and its fill slopes face the viewer - at the lowest tilt
277
+ that shows all of its road (from straight above, if the terrain hides parts of it at every tilt).
278
+ - **Cost** - the cost breakdown by item
279
+ - **Design warnings** - grades over the maximum, curves under the minimum radius, slopes that don't
280
+ daylight (retaining walls needed), walls over the maximum height, unprotected stream crossings,
281
+ exclusion areas, and ends that miss the start/end points or don't tie in to the ground
282
+ - **Structures** and the **source map** image
283
+
284
+ The 3D views are drawn from the plan's full elevation grid, as detailed as the computer can draw
285
+ quickly. Where a view is zoomed in far enough for the grid's cells to show, the terrain is smoothed -
286
+ each grid cell is divided into smaller cells interpolated between the grid points, clamped to each
287
+ grid cell's corner elevations. Smooth terrain looks smoother up close but is no more accurate.
288
+
289
+ On large sites, where the road is too narrow to see at a view's scale, the selected option's road is
290
+ also drawn as a highlighted centerline.
291
+
292
+ The report's "Explore" links open the full-window **3D explorer**, controlled with the mouse:
293
+
294
+ | Control | Action |
295
+ | --- | --- |
296
+ | Drag | Move - the ground follows the mouse |
297
+ | Right-drag or Shift+drag | Rotate (drag left and right) and tilt (drag up and down) |
298
+ | Wheel or pinch | Zoom in and out, around the mouse |
299
+ | Double-click | Center the view there and zoom in (Shift+double-click zooms out) |
300
+ | Arrows, + / - | Move, and zoom in and out |
301
+ | The + / - buttons, North, Top, and Reset | Zoom, face north, view from above, and view the whole site |
302
+ | The Exaggeration slider | The vertical exaggeration |
303
+ | The ? button | Show or hide the controls' help |
304
+ | Esc | Back to the report |
305
+
306
+ The explorer's URL keeps its view, so it can be reloaded or shared.
307
+
308
+
309
+ ### Viewing a road plan
310
+
311
+ The application views a road plan that's opened, or made by a run. The viewer is also a web site,
312
+ [craigahobbs.github.io/sageroad/viewer/](https://craigahobbs.github.io/sageroad/viewer/) (see
313
+ Publishing, below), that views plans without installing anything:
314
+
315
+ - **Open a local plan** - on the viewer's home page, select or drop the plan's JSON file (and its
316
+ source map image, to show it in the report). Local files stay on your computer - they're kept in
317
+ the browser's storage, so the plan's URL works after a reload, and the home page lists the recent
318
+ plans.
319
+ - **View a plan URL** - `viewer/#url=<plan.json URL>` (the URL is relative to the viewer). The plan's
320
+ map image is relative to the plan's URL. Plans hosted on another site must allow cross-origin
321
+ requests (CORS).
322
+ - **View the example** - the web site's viewer has a link to the example on its home
323
+ page.
324
+
325
+ The viewer validates every plan it loads against the road plan model (see The road plan model, below), and
326
+ reports the first problem it finds.
327
+
328
+
329
+ ## The cost score
330
+
331
+ The cost score is the estimated construction cost in thousands of nominal US dollars - for comparing
332
+ plan options, not as a bid estimate. SageRoad computes it from typical 2023-2025 unit rates (state DOT
333
+ average bid prices and low-volume road references):
334
+
335
+ - **Earthwork** by the average end area method. Cross sections every third of a grid cell model the
336
+ road template, cut slopes (1:1 soil, 0.5:1 rock), and fill slopes (1.5:1) against the ground's
337
+ cross slope. Rock excavation applies within rock outcrop areas.
338
+ - **Mass balance** - shrinkage and swell, borrow (import), waste (export), and overhaul from the mass
339
+ haul diagram beyond the free haul distance
340
+ - **Clearing, surfacing, ditches and cross drains, erosion control**, by area or length
341
+ - **Culverts, retaining walls (by face area), bridges (by deck area), and turnouts**
342
+ - **Existing road upgrades** (by area) - where an option follows an existing road, reshaping, a
343
+ gravel lift, ditch cleaning, and minor widening replace the new road's earthwork, clearing,
344
+ surfacing, and ditches
345
+ - **Mobilization** (10%)
346
+
347
+ A plan's config can override any unit rate (`costRates`, in dollars per metric unit) for local prices.
348
+ The default rates:
349
+
350
+ | Item | Default rate |
351
+ | --- | --- |
352
+ | Clearing and grubbing | $8,000 / acre of disturbed area |
353
+ | Common excavation | $15 / CY |
354
+ | Rock excavation | $75 / CY |
355
+ | Embankment placement and compaction | $5 / CY |
356
+ | Borrow (import) | $20 / CY |
357
+ | Waste (export) | $8 / CY |
358
+ | Overhaul (beyond 500 ft free haul) | about $3 / CY-mile |
359
+ | Native surface finish grading | about $1.25 / SY |
360
+ | Aggregate surfacing | about $16 / SY |
361
+ | Asphalt paving (with base) | about $33 / SY |
362
+ | Concrete paving | about $75 / SY |
363
+ | Ditches and cross drains | about $14 / LF of road |
364
+ | Culverts | about $120 / LF (18 in) to $250 / LF (36 in), plus $3,000 per end |
365
+ | Retaining walls | about $60 / SF of face |
366
+ | Bridges | about $250 / SF of deck |
367
+ | Existing road upgrade (reshaping, gravel lift, ditch cleaning, minor widening) | about $11 / SY of road |
368
+ | Erosion control and revegetation | $3,000 / acre of disturbed area |
369
+ | Mobilization | 10% |
370
+
371
+ Shrinkage: 1 CY of common excavation makes 0.87 CY of compacted fill; rock swells to 1.1 CY.
372
+
373
+
374
+ ## The road plan model
375
+
376
+ A road plan model is a JSON file containing the site topography (an elevation grid with streams,
377
+ roads, trails, rock outcrops, and exclusion areas, and its elevation data's sources), the plan's
378
+ georeference (its place on the Earth), the start and end points, design criteria, cost rate
379
+ overrides, one or more road plan options, and the plan's config (its road site model). Each option
380
+ has a road cross section, a centerline alignment (x, y, and grade elevation), and structures
381
+ (retaining walls, bridges, culverts, turnouts, and the existing roads it follows).
382
+
383
+ The model is defined with [Schema Markdown](https://craigahobbs.github.io/schema-markdown-js/language/)
384
+ (in `viewer/lib/model.js`), and the viewer validates every plan against it. The viewer's report links
385
+ to the model documentation.
386
+
387
+
388
+ ## The example
389
+
390
+ The [example](https://craigahobbs.github.io/sageroad/example/example.json) is an access road up a hill at the south edge of Kennewick,
391
+ Washington - not quite half a mile of road, to climb 200 feet. It was made by the application, from
392
+ its config, [site.json](https://craigahobbs.github.io/sageroad/example/site.json): the road's start and end points, as latitudes and
393
+ longitudes, its planning notes, and its marks - the house lots at the foot of the hill, which the road
394
+ must avoid, and an unmapped dirt track to the hilltop, which a road may follow.
395
+
396
+ The site's terrain is the USGS's 1 meter lidar elevations, and its features are the USGS's roads and
397
+ stream, the config's marks, and a draw of the hill that an option crosses, which the run added. The run
398
+ read the notes with a local model (the road is gravel, and its grade is 12% at most), and engineered
399
+ three options: the least-cost road, which follows the track to the hilltop, an all-new road, and a
400
+ road in another corridor, around the hill's west side. The plan keeps its image - the USGS topographic
401
+ map of the site, for the report's source map - so the example is one file. Open the config in the
402
+ application and run it to make the plan again.
403
+
404
+ Run the application, and open the example's file to view it - `example/example.json` in the
405
+ repository, or [download it](https://craigahobbs.github.io/sageroad/example/example.json). On the project's web site,
406
+ [view the example](https://craigahobbs.github.io/sageroad/viewer/#url=../example/example.json) - the site's viewer links to it from its home
407
+ page, too.
408
+
409
+
410
+ ## Development
411
+
412
+ SageRoad's development runs from a clone of its repository, on macOS, Linux, and Windows. It needs
413
+ `make`, `git`, and `curl` (or `wget`), [Node.js](https://nodejs.org/en/download) 22 or later, and
414
+ [Python](https://www.python.org/downloads/) 3.11 or later:
415
+
416
+ - **macOS** - the Xcode Command Line Tools have `make` and `git` (`xcode-select --install`), and
417
+ Node.js has an installer (or `brew install node`, with [Homebrew](https://brew.sh)).
418
+ - **Linux** - your distribution's package manager (`sudo apt install make git curl`, say), and
419
+ Node.js 22 or later - a distribution's own Node.js package may be older.
420
+ - **Windows** - the `make` commands need a Unix shell: [MSYS2](https://www.msys2.org/) (run
421
+ `pacman -S --needed make git` in its "MSYS2 UCRT64" terminal), and Node.js's Windows installer. To
422
+ let the MSYS2 terminal find `node`, set the Windows environment variable `MSYS2_PATH_TYPE` to
423
+ `inherit` (`setx MSYS2_PATH_TYPE inherit`, in PowerShell).
424
+
425
+ ```
426
+ make run # run the application from the repository, in the browser
427
+ make commit # the pre-commit gate: the viewer's, the planning tools', and the application's tests and lint
428
+ make test # run the unit tests (TEST=name runs the viewer's and the planning tools' tests of a name)
429
+ make lint # run ESLint on the viewer and the planning tools, and pylint on the application
430
+ make site # stage the project's web site (build/gh-pages/)
431
+ make changelog # update the changelog (CHANGELOG.md) with the commits since its last
432
+ make publish # publish the application's package to PyPI
433
+ make clean # remove the build directories
434
+ ```
435
+
436
+ The first `make` command downloads the build's files and npm packages, so it takes a minute. The
437
+ top-level makefile delegates to the project's subprojects - run `make` in one for its own targets:
438
+
439
+ | Directory | Contents |
440
+ | --- | --- |
441
+ | [viewer/](https://github.com/craigahobbs/sageroad/tree/main/viewer) | The SageRoad viewer - the web application, the road plan model (its schema, validation, earthwork, and cost analysis), and a command line (`bin/sageroad.js`) that prints a plan's analysis and the model documentation. JavaScript, built with [javascript-build](https://github.com/craigahobbs/javascript-build#readme) - see its [README](https://github.com/craigahobbs/sageroad/blob/main/viewer/README.md). |
442
+ | `plan/` | The planning tools - the site's USGS lidar terrain and features, road engineering, and a plan's run (`auto`) - which the application runs in the browser, and a command line for their development (`bin/plan.js`). JavaScript, built with [javascript-build](https://github.com/craigahobbs/javascript-build#readme). |
443
+ | `app/` | The SageRoad application - a Python package (`sageroad`), built with [python-build](https://github.com/craigahobbs/python-build#readme). Its command line, `sageroad`, serves the front end (the viewer's application and the planning tools, staged in the package) with a [chisel](https://github.com/craigahobbs/chisel#readme) back end - to this computer only. |
444
+ | `example/` | The example - its road site model, and its plan |
445
+
446
+ The planning tools' command line - `node plan/bin/plan.js site`, `options`, `route`, and `auto` -
447
+ checks the tools against the USGS's services, and compares their plans when they change. It doesn't
448
+ ask a model. `CLAUDE.md` is the repository guide for Claude Code.
449
+
450
+
451
+ ### Publishing
452
+
453
+ `make site` stages the project's web site in `build/gh-pages/`: this README at its root (rendered by
454
+ `index.html`, a [MarkdownUp](https://github.com/craigahobbs/markdown-up#readme) page), the example
455
+ plan, and the viewer in `viewer/`. `make gh-pages` runs the pre-commit gate, stages the site, and
456
+ updates a checkout of the repository's `gh-pages` branch in `../sageroad.gh-pages` - commit and push it
457
+ there to publish (GitHub Pages serves the branch).
458
+
459
+ `make publish` runs the pre-commit gate, builds the package, and uploads it to PyPI (with
460
+ [twine](https://twine.readthedocs.io/) - it asks for a PyPI API token, or reads one from `~/.pypirc`).
461
+ It publishes only from a working tree without changes. The package's version is
462
+ `app/pyproject.toml`'s, and `make changelog` updates `CHANGELOG.md`.
463
+
464
+ The published viewer is the viewer's complete source - including the earthwork and cost model - and
465
+ the site is public. Road plans and map images are user data: don't add them to the site unless
466
+ they're meant to be public.