US State GeoJSONs

[jdcarls2]

Overview

This pull request is specifically focused on adding US State geojsons for more specific locations. For clarity and consistency with other regions, these files have been named according to the ISO 3166-2 convention, i.e., "US-WY.geojson" for Wyoming.

At the moment, this means that a few states are duplicated, and these new geojsons are not actually referenced by any brands. I felt that a massive find-and-replace to actually implement these would be a much bigger change, and might make more sense as its own PR. First, I wanted to get these state shapes accepted as something useful to the project, then implement them later.

The Shapes

These shapes were generated using Natural Earth's Admin 1 boundaries (which are public domain) as a starting point, though they were modified heavily. The goals were to create state shapes which are:

1. As simple as possible
2. Accurate enough to be useful for the NSI's purposes
3. Seamless with respect to adjoining states and regions

Because these shapes are not meant to be cartographic representations of the states themselves, but rather regions in which brands/operators/etc., can be reliably located, I was able to make some significant simplifications. For one, coastal states could be partially "convex hulled". Hawaii, for instance, is just a 4-node box rather than a multipologyon.

Another simplification was along sinuous river-defined boundaries away from major population centers. An accurate boundary would be hopelessly complex in these areas, but as there is essentially nothing in these areas that might be tagged with an operator or brand, a bit of coarseness seems acceptable.

As expected, the biggest challenge was dealing with major metro areas that span state lines. While most brands in St. Louis would probably be in East St. Louis as well, certain operators may not be. I kept these as simple as I could, but extra nodes were unavoidable.

Overall, I think they're okay. West Virginia comes in as being the most complex shape at 52. Most have less.

Future Additions

Along national boundaries, I took care to treat them as I would an adjoining state. If provinces are added to Canada in the same way, it will allow for seamless boundaries between these as well.

Future Corrections

Using QGIS's topological editing enabled, adding/removing/adjusting vertices should be very simple. The vertices are identical wherever shared, and QGIS will be able to recognize the points as being shared, and adjust them together.

[bhousel]

Sorry I haven't had the time to really review this!

First.. I love everything about this ❤️ Thank you - a bunch of us have wanted this for a while!

I have some questions mostly about how the topological editing in QGIS works..

• If someone wants to adjust these later, do you have some sort of "project" file or do just load them all in again?
• One example: our build script will simplify the files a bit, rounding the coordinate precision to 5 decimals (i.e. to about 1 meter). I think this is ok, but just wanted to make sure. (as long as all the coordinates are rounded consistently, they'll still remain connected)

Another simplification was along sinuous river-defined boundaries away from major population centers. An accurate boundary would be hopelessly complex in these areas, but as there is essentially nothing in these areas that might be tagged with an operator or brand, a bit of coarseness seems acceptable.

Yes this is exactly the right approach - I've spend a lot of time drawing these sorts of boundaries for this and other projects, and it's good to cheat the boundary when it runs across water, wilderness, or mountains, and add extra points where populated places share a boundary. The screenshot of Davenport-Moline looks like it could use a few more points, and this is ok.

I feel like we are probably good to just start using them right away but I expect people will open issues and we'll need to tweak these features as we go.. This is why my main concern is how hard it is to maintain these in QGIS - It's not something that I could do right away, but it would be awesome if you could write up some instructions for anyone who wants to tweak them, and we can add them to our project wiki.

Related issues to this are:
rapideditor/country-coder#19
rapideditor/country-coder#26
rapideditor/location-conflation#34
#4784

[jdcarls2]

If someone wants to adjust these later, do you have some sort of "project" file or do just load them all in again?

Just load and edit! Shouldn't be too hard, and I expect with good documentation, the average user could go in and add/shift vertices as needed. There may even be other tools that work better, but Q has the benefit of being FOSS and mutli-platform. JOSM actually does really well with this, but only if the states are all in the same layer, unfortunately.

@bhousel I could do up some instructions. Just paste them here for someone to copy into the wiki?

One example: our build script will simplify the files a bit, rounding the coordinate precision to 5 decimals (i.e. to about 1 meter). I think this is ok, but just wanted to make sure. (as long as all the coordinates are rounded consistently, they'll still remain connected)

I could test this to make sure, but identical inputs should yield identical outputs, and so long as the coords are the same (or even really really close), Q should treat them as a shared node.

[bhousel]

@bhousel I could do up some instructions. Just paste them here for someone to copy into the wiki?

Yes that would be great - whenever you get to it, I'll put them on the wiki, no rush!

[jdcarls2]

How to Update State/Region GeoJSONs

Updating and refining boundaries between adjacent GeoJSONs is not too hard. It is recommended that users wishing to perform such edits use QGIS. While QGIS 3.20 is pictured below, the tools used have been in the application for many versions, and users who opt for the LTR will be as able to perform these edits as those on the latest release.

Load the Data

Open a new project in QGIS. Browse to the repository in the Browser pane and find the features you wish to edit.

From there, you can simply drag the features into the map canvas. When adjusting a boundary, you must load all features which participate in that boundary. This will typically be between two or maybe three areas. While not strictly necessary, you may load all the features.

Topological Editing / Snapping

This is what ensures your edits do not create overlaps or gaps, so it's very important. On the Snapping Toolbar, click the magnet icon to enable snapping. The toolbar may not be visible at first; go to View > Toolbars > Snapping Toolbar from the menu bar, or right-click the toolbar area and select the snapping toolbar from the context menu.

On the toolbar, you will see an icon with three ways joined by a shared node:

Click this icon to enable topological editing.

Enable Editing

In QGIS, there is an Editing Toolbar. (Look for the pencil icon.) With a layer selected in the Layers pane, click the pencil icon for Toggle Editing. You can also right-click the layer and find this command in the context menu.

NOTE: You will need to repeat this for each layer being editing. If I adjust the IL / IN boundary with editing only enabled on IL, I will only affect the IL GeoJSON.

Vertex Editor

Near the Toggle Editing icon, you'll find the Vertex Editor icon, a hammer and screwdriver under a way/node. Click this to activate the Vertex Editor tool. The cursor will change to a crosshair, and as you hover over edges and nodes, they will highlight.

Click on a vertex to "pick it up", click again to "put it down". The same is true for edges and selections of multiple nodes, though in this context that is probably less useful. On the midpoint of any edge, a "helper node" is visible as a grey +. Clicking this will add a new vertex at that point, which can be dragged into the desired position.

Saving Edits

When there are pending edits, the Save icon will be enabled on the toolbar. Simply click the icon to save your edits to the layer.

NOTE: As with Toggle Editing, this button only applies to the currently selected layer. It's possible to successfully edit two layers and inadvertently only save the edits to a single layer. Fortunately, the Edit Toolbar does have a quicker way to save multiple edits. To the left of Toggle Editing is the Current Edits icon, two red pencils.
Click this icon to open a small dropdown menu, where you can find the Save for All Layers command.

After Saving

Once you've saved your edits, you may commit the changes. If possible, run npm build first, though someone else can do this after the fact as well.

QGIS Suggestions

Here are a few things that might make your life easier using QGIS.

Reference Layers

For several versions, QGIS has come with the OSM carto tiles as a pre-configured XYZ Tile service, which you can find in the Browser pane. Drag this into your map to help guide your edits. You can also bring in aerial imagery, vector layers, etc.. Vector layers have the benefit of being "snappable".

By default, your vector layers come in as opaque areas. To make your reference layers actually useful, put them higher up on the layer list. For a raster layer like the OSM tiles, you can set the Blending Mode to something like multiply in order to view the layers below.

Use Groups

You can add layers to groups in the Layers pane. This makes it easier to keep different regions, reference layers, etc., separate, and keeps the layer list from getting too long.

Save a QGIS Project

Load all the features from the NSI repo and save your QGIS project. This will help save you setup time if you need to adjust other boundaries in the future.

@bhousel I think that's it.

[arch0345]

Thanks @jdcarls2 for making this guide! I've added this wiki page for it

[michaelblyons]

Thanks @jdcarls2 for making this guide! I've added this wiki page for it

Thanks for making the wiki page. I think formatting on the last image is a little weird right now.

[arch0345]

Thanks for making the wiki page. I think formatting on the last image is a little weird right now.

Thanks for catching this! It should be fixed now