From 2037cae81de951b974ab66e23dd3212d06be5b74 Mon Sep 17 00:00:00 2001 From: Dustin Carlino Date: Sun, 21 Jun 2020 16:22:09 -0700 Subject: [PATCH] update some docs --- README.md | 4 ++ docs/CHANGELOG.md | 10 +++ docs/articles/map/article.md | 101 ++++++++++++++-------------- docs/articles/trafficsim/article.md | 6 +- docs/dev.md | 2 +- docs/history/history.md | 6 +- docs/roadmap.md | 53 +++++++-------- 7 files changed, 102 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 7c9277193e..e8f6522a5f 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,10 @@ a city affect the movement of drivers, cyclists, transit users, and pedestrians. or [read all instructions](docs/INSTRUCTIONS.md) (new releases every Sunday) - [build from source](docs/dev.md) (new changes daily) +## Show, don't tell + +[Alpha release trailer](https://www.youtube.com/watch?v=LxPD4n_1-LU) + Find a problem: ![exploring_traffic](docs/videos/exploring_traffic.gif) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 8f68d35d84..213abae54f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -464,3 +464,13 @@ changes here. - layers: use gradient for a few, delay comparison, new UI for picker - overhauled minimap controls, should be intuitive now - edit mode changelist UI started + +0.2.0 (alpha launch) + +- road names now shown by default, in a new style +- all layers now use gradients and show up zoomed in. worst traffic jam layer revamped. +- scatter and line plot improvements +- internal UI fixes: proper word wrap +- bugfixes for following people riding the bus +- rainbow crosswalks in one neighborhood +- final polishing for launch diff --git a/docs/articles/map/article.md b/docs/articles/map/article.md index b66b99fcba..b05997dba5 100644 --- a/docs/articles/map/article.md +++ b/docs/articles/map/article.md @@ -9,23 +9,24 @@ omitted. TODO: Integrate pictures from [these slides](https://docs.google.com/presentation/d/1cF7qFtjAzkXL_r62CjxBvgQnLvuQ9I2WTE2iX_5tMCY/edit?usp=sharing). -Everything here should be up-to-date as of September 2019. +[This recorded presentation](https://youtu.be/chYd5I-5oyc?t=439) covers some of +this. + +Everything here should be up-to-date as of June 2020. + * [A/B Street's map model](#ab-streets-map-model) + * [The final map](#the-final-map) + * [Coordinate system](#coordinate-system) + * [Invariants](#invariants) + * [From OSM to RawMap (convert_osm crate)](#from-osm-to-rawmap-convert_osm-crate) + * [RawMap to InitialMap](#rawmap-to-initialmap) + * [InitialMap to Map](#initialmap-to-map) + * [Live edits](#live-edits) + * [Development tricks](#development-tricks) + * [Appendix: PolyLines](#appendix-polylines) -- [A/B Street's map model](#ab-streets-map-model) - - [The final map](#the-final-map) - - [Coordinate system](#coordinate-system) - - [Invariants](#invariants) - - [From OSM to raw_data (convert_osm crate)](#from-osm-to-raw_data-convert_osm-crate) - - [raw_data to InitialMap](#raw_data-to-initialmap) - - [InitialMap to HalfMap](#initialmap-to-halfmap) - - [HalfMap to Map](#halfmap-to-map) - - [Live edits](#live-edits) - - [Development tricks](#development-tricks) - - [Appendix: PolyLines](#appendix-polylines) - - + @@ -60,6 +61,9 @@ for some portion of Seattle. Each map has these objects: - **Bus route**: A bus route has a name and a list of stops that buses will cycle between. In the future, they'll include information about the frequency/schedule of the route. +- **Parking lot**: A parking lot is connected to a road, has a shape, and has + some internal driving "aisles." The number and position of individual parking + spots is auto-generated. ### Coordinate system @@ -129,41 +133,30 @@ takes a few seconds to load a serialized map. to preserve lots of out-of-bounds geometry. - Area polygons are intersected with the boundary polygon using the `clipping` crate +- `lib.rs`: Remove cul-de-sacs (roads that begin and end at the same + intersection), because they mess up parking hints and pathfinding. - `lib.rs`: Apply parking hints from a King County GIS blockface dataset - Match each blockface to the nearest edge of a road - Interpret the metadata to assign on-street parking there or not - `lib.rs`: Apply offstreet parking hints from a King County GIS dataset - Match each point to the building containing it, plumbing through the number of spots -- `lib.rs`: Apply sidewalk presence hints from a King County GIS dataset +- `lib.rs`: **Disabled**: Apply sidewalk presence hints from a King County GIS + dataset - Match each sidewalk line to the nearest edge of a road - Update the road to have a sidewalk on none, one, or both sides - `lib.rs` using the `gtfs` crate: Load bus route info from GTFS -- `neighborhoods.rs`: Load neighborhood polygons from an extra geojson file - - If the polygon isn't completely in-bounds, just remove it +- `lib.rs` using the `srtm` module: Load (extremely poor quality) elevation data ## RawMap to InitialMap -The remainder of map construction is done in the `map_model` crate, driven by -the `precompute.sh` script. There's one intermediate structure between `RawMap` -and `Map`, called `InitialMap`. +The remainder of map construction is done in the `map_model` crate. There's one +intermediate structure between `RawMap` and `Map`, called `InitialMap`. -- `raw.rs`: Apply manually-defined fixes - - There's a separate crate, `map_editor`, that displays RawMaps and allows me - to manually specify fixes for weird geometry problems. - - The `MapFixes` can delete roads and intersections, then create new ones with - custom tags and geometry. Sometimes OSM's model of a complicated - intersection is so hard to use that it's easier to just start over from - scratch. - - There's also a fix to merge short roads. This arbitrarily deletes one - intersection connected to the short road, then extends the geometry of all - roads connected to the other. - `make/remove_disconnected.rs`: Remove disconnected roads - Just floodfill from some road, assuming all roads are bidirectional, to get different partitions. - Remove roads from all but the largest partition - - Also remove cul-de-sacs (roads that begin and end at the same intersection), - because they mess up parking hints and pathfinding. - `make/initial/mod.rs` and `make/initial/lane_specs.rs`: Interpret OSM tags to figure out what lanes are on each side of each road, also figuring out the total width of the road. @@ -220,6 +213,17 @@ Still in the `map_model` crate. lanes created - Some of these OSM tags are just completely wrong sometimes. If the filter makes an incoming lane lose all of its turns, then ignore that tag. +- `make/parking_blackholes.rs`: Find well-connected roads near "blackhole" + lanes. + - Starting from most driving/biking lanes, most other lanes are reachable. + Some aren't -- such as one-way highways inevitably leading from or to a + border. These are "blackholes" -- pathfinding to or from here may fail. + - Find the largest strongly-connected component (SCC) in the driving graph. + From every other lane (a blackhole), floodfill both forwards and backwards + to find the nearest driving lane part of the main SCC. + - Later, if a car needs to park by a building on a blackhole road, it'll + instead start searching for parking at the redirect. This prevents it from + being forced to instead exit the map through a border. - `make/buildings.rs`: Match buildings up with sidewalks - Find the closest sidewalk polyline to each building's center. Then draw a straight line for the front path between the edge of the building and the @@ -227,6 +231,12 @@ Still in the `map_model` crate. - Filter out buildings too far away from any sidewalk - The front path might cross through other buildings; this is probably not worth fixing. +- `make/buildings.rs`: Same for parking lots + - Similar process to match parking lots to nearest sidewalk and driving lane + - Try to place parking spots along both sides of parking aisles + - Filter out overlapping spots +- `make/bridges.rs`: Find what roads lie beneath bridges, and update their + Z-order accordingly for later drawing. - `stop_signs.rs`: Instantiate default stop sign policies - Rank incoming roads by OSM priority (arterial beats residential) - If there's only one rank, then make an all-way stop @@ -284,17 +294,6 @@ Still in the `map_model` crate. - Later when figuring out which bus to use for a pedestrian, the resulting list of nodes is scanned for the first and last bus stop along the same route. -- `make/parking_blackholes.rs`: Find well-connected roads near "blackhole" - lanes. - - Starting from most driving/biking lanes, most other lanes are reachable. - Some aren't -- such as one-way highways inevitably leading from or to a - border. These are "blackholes" -- pathfinding to or from here may fail. - - Find the largest strongly-connected component (SCC) in the driving graph. - From every other lane (a blackhole), floodfill both forwards and backwards - to find the nearest driving lane part of the main SCC. - - Later, if a car needs to park by a building on a blackhole road, it'll - instead start searching for parking at the redirect. This prevents it from - being forced to instead exit the map through a border. ## Live edits @@ -302,6 +301,7 @@ A key feature of A/B Street is the player editing the map and seeing how traffic responds. The possible edits include: - Change lane types (driving, bus, bike, parking -- sidewalks are fixed) +- Change speed limits - Reverse a lane - Change a stop sign policy (which roads have a stop sign and which have priority) @@ -342,10 +342,10 @@ drawing layer, which uploads new geometry to the GPU accordingly. - Don't be afraid of manual intervention - The data isn't perfect. It's easy to spend lots of time fiddling with code to automatically handle all problems - - But it's sometimes faster to just manually point at problems and have a - human determine some fix. This is what the `map_editor` crate does. - - It can be sometimes easier to completely delete funky OSM data, and just map - it again from scratch. + - Instead of automatically resolving problems, prefer good tooling for finding + and specifying fixes + - Be careful of derivative structures that could get out of sync with OSM. + Prefer contributing real fixes to OSM. - Screenshot diff testing - When working on the code for intersection geometry, it's easy to check a few example cases get fixed by some change. But what if another part of the map @@ -362,9 +362,10 @@ drawing layer, which uploads new geometry to the GPU accordingly. - For the final product, lanes and such are just a contiguous array, indexed by numeric IDs. - But sometimes, we need IDs that're the same between different boundary - polygons of maps, like for MapFixes. Using (longitude, latitude) pairs hits - floating-point serialization and comparison issues, so referring to roads as - (OSM way ID, OSM node ID 1, OSM node ID 2) works instead. + polygons of maps, so that player edits can be applied anywhere. Using + (longitude, latitude) pairs hits floating-point serialization and comparison + issues, so referring to roads as (OSM way ID, OSM node ID 1, OSM node ID 2) + works instead. ## Appendix: PolyLines diff --git a/docs/articles/trafficsim/article.md b/docs/articles/trafficsim/article.md index 037c66f126..6ea9f5bacf 100644 --- a/docs/articles/trafficsim/article.md +++ b/docs/articles/trafficsim/article.md @@ -2,7 +2,11 @@ This article describes how cars, bikes, buses, and pedestrians are modeled in A/B Street. All code lives in the `sim` crate. This is up-to-date as of -July 2019. +July 2019. Since then, the main change is some gridlock resolution that I've yet +to describe. + +[This recorded presentation](https://youtu.be/chYd5I-5oyc?t=1086) covers some of +this. The traffic simulation models different agents (cars, bikes, buses, pedestrians, and intersections) over time. Agents don't constantly sense and react to the diff --git a/docs/dev.md b/docs/dev.md index 66878a966f..9d37da72e6 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -4,7 +4,6 @@ You will first need: -- Standard Unix dependencies: `curl`, `unzip`, `gunzip`, `md5sum` (`md5` on Mac) - Rust, at least 1.43. https://www.rust-lang.org/tools/install - On Linux, `sudo apt-get install xorg-dev libxcb-shape0-dev libxcb-xfixes0-dev` or the equivalent for your distro @@ -81,6 +80,7 @@ To run all pieces of the importer, you'll need some extra dependencies: - `osmconvert`: See https://wiki.openstreetmap.org/wiki/Osmconvert#Download - `libgdal-dev`: See https://gdal.org/ if your OS package manager doesn't have this +- Standard Unix utilities: `curl`, `unzip`, `gunzip` You can rerun specific stages of the importer: diff --git a/docs/history/history.md b/docs/history/history.md index 2b8e9bebdc..9d0155066f 100644 --- a/docs/history/history.md +++ b/docs/history/history.md @@ -169,7 +169,11 @@ calling out milestones. "UI churn" is pretty much constantly happening. maybe vanquished the HiDPI bugs, multi-step turn restrictions, random bios for people, and docs like this to prep for launch ;) - **milestone**: relying on pure OSM, no more `MapFixes` -- June: parking lots + +## Year 3 (June 2020-2021) + +- June: parking lots, real minimap controls, road labels + - **June 22**: alpha launch! ## Retrospective diff --git a/docs/roadmap.md b/docs/roadmap.md index 8a512a92cd..d8171c1cae 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -20,11 +20,26 @@ If I had resources to hire a team, this is roughly how I'd organize different roles. If you're interested in helping, these aren't strictly defined positions, just ideas of related tasks. +### UI and data visualization + +We've got a UX designer, but implementing all of the new designs takes time. +Also: + +- improve color schemes for colorblind players, implement night mode, rain + effects, etc +- refactor and clean up the GUI library for other Rust users +- lots of data viz design / implementation needed + +### Game design + +- the tutorial mode needs attention +- many ideas for challenge/story modes, but playtesting, tuning, and game design + needed + ### Map data / GIS Support more cities: -- generalize the import pipeline (mostly done) - write docs/tools to help people add new cities without programming experience - add support for non-OpenStreetMap input: GeoJSON for parking in Perth, other trip demand sources, etc @@ -67,21 +82,6 @@ Improve existing models: - pedestrians walking on road shoulders (some streets have no sidewalks) - buses: transfers, proper schedules, multiple buses per route -### UI and data visualization - -We've got a UX designer, but implementing all of the new designs takes time. -Also: - -- minimap camera controls are notoriously hard to get right -- refactor and clean up the GUI library for other Rust users -- lots of data viz design / implementation needed - -### Game design - -- the tutorial mode needs attention -- many ideas for challenge/story modes, but playtesting, tuning, and game design - needed - ### Web A/B Street runs on the web via WASM and WebGL; just waiting on vector text @@ -91,18 +91,17 @@ support. Besides that: ## Contributing for non-programmers -I've heard many people want to help with something other than programming or -design. The best ideas are to start mapping, especially since most work is -directly through OpenStreetMap: +There's plenty to do besides programming! -- sidewalks, crosswalks, - [on-street parking](https://dabreegster.github.io/abstreet/map_parking.html) -- traffic signal timing (needs more planning / tooling) -- fixing geometry problems with the map editor (needs tooling) - -Playtesting by attempting to implement real proposals would also be helpful, to -expose where it's awkward for A/B Street to edit the map and to write up -problems encountered. +- Mapping, most of which directly contributes to OpenStreetMap: + - sidewalks and crosswalks + - [on-street parking](https://dabreegster.github.io/abstreet/map_parking.html) + - [traffic signal timing](https://docs.google.com/document/d/1Od_7WvBVYsvpY4etRI0sKmYmZnwXMAXcJxVmm8Iwdcg/edit?usp=sharing) +- Playtesting by attempting to implement real proposals would also be helpful, + to expose where it's awkward for A/B Street to edit the map and to write up + problems encountered. +- Advocacy: I'm not great at finding the right people to to get ideas + implemented for real. Maybe you are? ## Long-term vision