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.
- sageroad-1.0.0/LICENSE +21 -0
- sageroad-1.0.0/PKG-INFO +466 -0
- sageroad-1.0.0/PYPI.md +441 -0
- sageroad-1.0.0/README.md +76 -0
- sageroad-1.0.0/pyproject.toml +44 -0
- sageroad-1.0.0/setup.cfg +4 -0
- sageroad-1.0.0/src/sageroad/__init__.py +0 -0
- sageroad-1.0.0/src/sageroad/__main__.py +9 -0
- sageroad-1.0.0/src/sageroad/app.py +94 -0
- sageroad-1.0.0/src/sageroad/main.py +69 -0
- sageroad-1.0.0/src/sageroad/static/app.css +545 -0
- sageroad-1.0.0/src/sageroad/static/index.html +53 -0
- sageroad-1.0.0/src/sageroad/static/lib/app.js +576 -0
- sageroad-1.0.0/src/sageroad/static/lib/args.js +180 -0
- sageroad-1.0.0/src/sageroad/static/lib/canvas.js +262 -0
- sageroad-1.0.0/src/sageroad/static/lib/doc.js +15 -0
- sageroad-1.0.0/src/sageroad/static/lib/draw.js +298 -0
- sageroad-1.0.0/src/sageroad/static/lib/explore.js +288 -0
- sageroad-1.0.0/src/sageroad/static/lib/form.js +185 -0
- sageroad-1.0.0/src/sageroad/static/lib/format.js +147 -0
- sageroad-1.0.0/src/sageroad/static/lib/geo.js +129 -0
- sageroad-1.0.0/src/sageroad/static/lib/homePage.js +616 -0
- sageroad-1.0.0/src/sageroad/static/lib/mapPage.js +663 -0
- sageroad-1.0.0/src/sageroad/static/lib/markdown.js +275 -0
- sageroad-1.0.0/src/sageroad/static/lib/model.js +1488 -0
- sageroad-1.0.0/src/sageroad/static/lib/models.js +304 -0
- sageroad-1.0.0/src/sageroad/static/lib/modelsPage.js +266 -0
- sageroad-1.0.0/src/sageroad/static/lib/planData.js +89 -0
- sageroad-1.0.0/src/sageroad/static/lib/planView.js +401 -0
- sageroad-1.0.0/src/sageroad/static/lib/report.js +257 -0
- sageroad-1.0.0/src/sageroad/static/lib/schemaDoc.js +171 -0
- sageroad-1.0.0/src/sageroad/static/lib/smoothing.js +71 -0
- sageroad-1.0.0/src/sageroad/static/lib/tables.js +78 -0
- sageroad-1.0.0/src/sageroad/static/lib/view3d.js +1246 -0
- sageroad-1.0.0/src/sageroad/static/lib/viewPages.js +471 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/auto.js +775 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/browser/buffer.js +21 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/browser/io.js +177 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/browser/zlib.js +61 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/design.js +140 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/draft.js +285 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/draws.js +263 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/elevationImage.js +364 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/engineer.js +764 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/features.js +309 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/numeric.js +192 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/ollama.js +68 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/planFile.js +27 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/plot.js +342 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/png.js +43 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/profile.js +339 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/roads.js +90 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/route.js +716 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/siteCommand.js +361 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/structures.js +181 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/terrain.js +502 -0
- sageroad-1.0.0/src/sageroad/static/plan/lib/usgs.js +188 -0
- sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/parser.js +611 -0
- sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/schema.js +659 -0
- sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/schemaUtil.js +349 -0
- sageroad-1.0.0/src/sageroad/static/schema-markdown/lib/typeModel.js +245 -0
- sageroad-1.0.0/src/sageroad.egg-info/PKG-INFO +466 -0
- sageroad-1.0.0/src/sageroad.egg-info/SOURCES.txt +65 -0
- sageroad-1.0.0/src/sageroad.egg-info/dependency_links.txt +1 -0
- sageroad-1.0.0/src/sageroad.egg-info/entry_points.txt +2 -0
- sageroad-1.0.0/src/sageroad.egg-info/requires.txt +2 -0
- 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.
|
sageroad-1.0.0/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/sageroad/)
|
|
29
|
+
[](https://pypi.org/project/sageroad/)
|
|
30
|
+
[](https://github.com/craigahobbs/sageroad/blob/main/LICENSE)
|
|
31
|
+
[](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
|
+
[](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.
|